cleveragents/cleveragents-core

Fork 3

UAT: `ActorRegistry.add()` requires `provider` and `model` fields in YAML but v3 `ActorConfigSchema` has no `provider` field — YAML-first actor registration is broken #4786

New issue

Open

opened 2026-04-08 18:57:41 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-08 18:57:41 +00:00

Owner

Bug Report

Feature Area: Actor YAML schema and validation / actor add command
Severity: High — YAML-first actor registration via ActorRegistry.add() is broken for v3 actor configs
Found by: UAT tester instance uat-worker-actor-yaml
Spec reference: docs/specification.md §Actor Definition Fields (lines 20417–20456)

What Was Tested

Code-level analysis of src/cleveragents/actor/registry.py (the add() method) and src/cleveragents/actor/schema.py (the ActorConfigSchema) for field compatibility.

Expected Behavior (from spec)

The spec (lines 20417–20456) defines the v3 actor YAML schema fields. The top-level fields include:

name (required)
type (required: llm, tool, or graph)
description (required)
model (required for LLM/GRAPH types)
system_prompt, tools, context_view, memory, context, route, env_vars, skills, lsp, etc.

The spec does not define a top-level provider field in the v3 actor YAML schema. Provider information is embedded in the model field or in the config.actor field (e.g., openai/gpt-4).

Actual Behavior

ActorRegistry.add() (lines 208–219) requires provider AND model fields:

def add(self, yaml_text: str, ...) -> Actor:
    blob = ActorConfiguration.load_yaml_text(yaml_text)
    name_raw: str = blob.get("name", "")
    ...
    provider_raw = blob.get("provider") or blob.get("provider_type", "")
    model_raw = blob.get("model") or blob.get("model_id", "")

    if not provider_raw or not model_raw:
        raise ValidationError(
            "Actor YAML must include 'provider' and 'model' fields."
        )

ActorConfigSchema (v3 schema) has NO provider field:

class ActorConfigSchema(BaseModel):
    name: str = Field(...)
    type: ActorType = Field(...)
    description: str = Field(...)
    version: str = Field(default="1.0")
    model: str | None = Field(default=None)  # ← optional, no provider
    # ... no provider field at all

This means a valid v3 actor YAML like:

name: local/my-reviewer
type: llm
description: Code reviewer
model: gpt-4
system_prompt: You are a code reviewer.

Will pass ActorConfigSchema.model_validate() but fail ActorRegistry.add() with:

ValidationError: Actor YAML must include 'provider' and 'model' fields.

Because provider is not in the v3 schema and not in the YAML.

Code Locations

Registry: src/cleveragents/actor/registry.py lines 208–253 (add() method)
Schema: src/cleveragents/actor/schema.py — ActorConfigSchema class (no provider field)
Spec: docs/specification.md lines 20417–20456

Root Cause

The ActorRegistry.add() method appears to be designed for a legacy YAML format that includes provider and model as separate top-level fields. The v3 ActorConfigSchema does not include provider as a top-level field — instead, provider information is embedded in the model string (e.g., "openai/gpt-4") or in the config.actor field.

The ActorRegistry.upsert_actor() method (the legacy path used by the CLI add command) does not have this restriction, which is why the CLI works. But the YAML-first add() method is broken for v3 configs.

Impact

Any code calling ActorRegistry.add(yaml_text) with a v3 actor YAML will fail with a validation error
The YAML-first actor registration path is non-functional for v3 configs
Users who try to use the ActorRegistry.add() API directly will encounter confusing errors

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Feature Area:** Actor YAML schema and validation / actor add command **Severity:** High — YAML-first actor registration via `ActorRegistry.add()` is broken for v3 actor configs **Found by:** UAT tester instance `uat-worker-actor-yaml` **Spec reference:** docs/specification.md §Actor Definition Fields (lines 20417–20456) --- ### What Was Tested Code-level analysis of `src/cleveragents/actor/registry.py` (the `add()` method) and `src/cleveragents/actor/schema.py` (the `ActorConfigSchema`) for field compatibility. ### Expected Behavior (from spec) The spec (lines 20417–20456) defines the v3 actor YAML schema fields. The top-level fields include: - `name` (required) - `type` (required: `llm`, `tool`, or `graph`) - `description` (required) - `model` (required for LLM/GRAPH types) - `system_prompt`, `tools`, `context_view`, `memory`, `context`, `route`, `env_vars`, `skills`, `lsp`, etc. The spec does **not** define a top-level `provider` field in the v3 actor YAML schema. Provider information is embedded in the `model` field or in the `config.actor` field (e.g., `openai/gpt-4`). ### Actual Behavior **`ActorRegistry.add()` (lines 208–219) requires `provider` AND `model` fields:** ```python def add(self, yaml_text: str, ...) -> Actor: blob = ActorConfiguration.load_yaml_text(yaml_text) name_raw: str = blob.get("name", "") ... provider_raw = blob.get("provider") or blob.get("provider_type", "") model_raw = blob.get("model") or blob.get("model_id", "") if not provider_raw or not model_raw: raise ValidationError( "Actor YAML must include 'provider' and 'model' fields." ) ``` **`ActorConfigSchema` (v3 schema) has NO `provider` field:** ```python class ActorConfigSchema(BaseModel): name: str = Field(...) type: ActorType = Field(...) description: str = Field(...) version: str = Field(default="1.0") model: str | None = Field(default=None) # ← optional, no provider # ... no provider field at all ``` This means a valid v3 actor YAML like: ```yaml name: local/my-reviewer type: llm description: Code reviewer model: gpt-4 system_prompt: You are a code reviewer. ``` Will **pass** `ActorConfigSchema.model_validate()` but **fail** `ActorRegistry.add()` with: ``` ValidationError: Actor YAML must include 'provider' and 'model' fields. ``` Because `provider` is not in the v3 schema and not in the YAML. ### Code Locations - **Registry:** `src/cleveragents/actor/registry.py` lines 208–253 (`add()` method) - **Schema:** `src/cleveragents/actor/schema.py` — `ActorConfigSchema` class (no `provider` field) - **Spec:** docs/specification.md lines 20417–20456 ### Root Cause The `ActorRegistry.add()` method appears to be designed for a legacy YAML format that includes `provider` and `model` as separate top-level fields. The v3 `ActorConfigSchema` does not include `provider` as a top-level field — instead, provider information is embedded in the `model` string (e.g., `"openai/gpt-4"`) or in the `config.actor` field. The `ActorRegistry.upsert_actor()` method (the legacy path used by the CLI `add` command) does not have this restriction, which is why the CLI works. But the YAML-first `add()` method is broken for v3 configs. ### Impact - Any code calling `ActorRegistry.add(yaml_text)` with a v3 actor YAML will fail with a validation error - The YAML-first actor registration path is non-functional for v3 configs - Users who try to use the `ActorRegistry.add()` API directly will encounter confusing errors --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-08 18:59:36 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4743

HAL9000 referenced this issue

2026-04-08 19:46:08 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 added the

labels

2026-04-08 23:00:11 +00:00

HAL9000 commented

2026-04-09 03:07:08 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — spec compliance bug identified by UAT testing
Story Points: 3 (M) — targeted fix to align implementation with spec
MoSCoW: Must Have — spec compliance is required for correct system behavior

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — spec compliance bug identified by UAT testing - **Story Points**: 3 (M) — targeted fix to align implementation with spec - **MoSCoW**: Must Have — spec compliance is required for correct system behavior --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added

and removed

labels

2026-04-09 03:07:08 +00:00

HAL9000 added this to the v3.5.0 milestone