UAT: `ActorRegistry.add()` requires `provider` and `model` fields that are absent from the spec v3 actor YAML format — spec-compliant actor YAML files fail to register #2501

New issue

Open

opened 2026-04-03 18:40:04 +00:00 by freemo · 2 comments

freemo commented

2026-04-03 18:40:04 +00:00

Owner

Metadata

Branch: fix/actor-registry-v3-yaml-format
Commit Message: fix(actor): ActorRegistry.add() should accept spec v3 YAML format without requiring provider/model fields
Milestone: v3.6.0
Parent Epic: #392

Summary

ActorRegistry.add() (in src/cleveragents/actor/registry.py) requires provider and model fields in the actor YAML. However, the specification's v3 actor YAML format uses type: llm with a model: field but no provider: field. Spec-compliant actor YAML files fail to register with a ValidationError: "Actor YAML must include 'provider' and 'model' fields.".

Expected Behavior (from spec)

The specification (docs/specification.md, Actor Definition section) shows the canonical v3 actor YAML format:

name: local/my-workflow

cleveragents:
  version: "3.0"
  default_actor: workflow_controller

actors:
  my_assistant:
    type: llm
    config:
      actor: openai/gpt-4        # References a built-in actor by name
      temperature: 0.7
      system_prompt: |
        You are a helpful assistant.
    skills:
      - local/file-ops
      - local/git-ops

The v3 format uses:

type: llm (not provider:)
config.actor: openai/gpt-4 (references a built-in actor, not a raw provider/model)
No top-level provider: or model: fields

The ActorConfigSchema (in src/cleveragents/actor/schema.py) correctly models this v3 format with type, model, system_prompt, skills, etc. — but ActorRegistry.add() bypasses ActorConfigSchema and uses ActorConfiguration.load_yaml_text() which requires provider and model.

Actual Behavior

ActorRegistry.add() calls ActorConfiguration.load_yaml_text() and then checks:

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."
    )

A spec-compliant v3 actor YAML (with type: llm and config.actor: openai/gpt-4) fails:

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

Root Cause

ActorRegistry.add() uses ActorConfiguration (a v2-era model) instead of ActorConfigSchema (the v3 schema). The v3 schema correctly handles the type: llm format, but the registry's add() method never calls it.

Code Locations

src/cleveragents/actor/registry.py — ActorRegistry.add() uses ActorConfiguration.load_yaml_text() and requires provider/model
src/cleveragents/actor/schema.py — ActorConfigSchema correctly models v3 format but is not used by ActorRegistry.add()
src/cleveragents/actor/config.py — ActorConfiguration is a v2-era model requiring provider and model

Subtasks

Update ActorRegistry.add() to use ActorConfigSchema for v3 YAML parsing
Derive provider and model from ActorConfigSchema fields (e.g., from config.actor reference or model field)
Maintain backward compatibility with v2 YAML format (which has provider: and model: directly)
Add Behave unit tests for agents actor add with spec-compliant v3 YAML
Update agents actor add CLI to handle the v3 format

Definition of Done

agents actor add --config actor-v3.yaml succeeds with spec-compliant v3 YAML
ActorRegistry.add() uses ActorConfigSchema for v3 format parsing
Backward compatibility with v2 YAML format is maintained
nox -e unit_tests passes

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

## Metadata - **Branch**: `fix/actor-registry-v3-yaml-format` - **Commit Message**: `fix(actor): ActorRegistry.add() should accept spec v3 YAML format without requiring provider/model fields` - **Milestone**: v3.6.0 - **Parent Epic**: #392 ## Summary `ActorRegistry.add()` (in `src/cleveragents/actor/registry.py`) requires `provider` and `model` fields in the actor YAML. However, the specification's v3 actor YAML format uses `type: llm` with a `model:` field but no `provider:` field. Spec-compliant actor YAML files fail to register with a `ValidationError: "Actor YAML must include 'provider' and 'model' fields."`. ## Expected Behavior (from spec) The specification (`docs/specification.md`, Actor Definition section) shows the canonical v3 actor YAML format: ```yaml name: local/my-workflow cleveragents: version: "3.0" default_actor: workflow_controller actors: my_assistant: type: llm config: actor: openai/gpt-4 # References a built-in actor by name temperature: 0.7 system_prompt: | You are a helpful assistant. skills: - local/file-ops - local/git-ops ``` The v3 format uses: - `type: llm` (not `provider:`) - `config.actor: openai/gpt-4` (references a built-in actor, not a raw provider/model) - No top-level `provider:` or `model:` fields The `ActorConfigSchema` (in `src/cleveragents/actor/schema.py`) correctly models this v3 format with `type`, `model`, `system_prompt`, `skills`, etc. — but `ActorRegistry.add()` bypasses `ActorConfigSchema` and uses `ActorConfiguration.load_yaml_text()` which requires `provider` and `model`. ## Actual Behavior `ActorRegistry.add()` calls `ActorConfiguration.load_yaml_text()` and then checks: ```python 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." ) ``` A spec-compliant v3 actor YAML (with `type: llm` and `config.actor: openai/gpt-4`) fails: ``` ValidationError: Actor YAML must include 'provider' and 'model' fields. ``` ## Root Cause `ActorRegistry.add()` uses `ActorConfiguration` (a v2-era model) instead of `ActorConfigSchema` (the v3 schema). The v3 schema correctly handles the `type: llm` format, but the registry's `add()` method never calls it. ## Code Locations - `src/cleveragents/actor/registry.py` — `ActorRegistry.add()` uses `ActorConfiguration.load_yaml_text()` and requires `provider`/`model` - `src/cleveragents/actor/schema.py` — `ActorConfigSchema` correctly models v3 format but is not used by `ActorRegistry.add()` - `src/cleveragents/actor/config.py` — `ActorConfiguration` is a v2-era model requiring `provider` and `model` ## Subtasks - [ ] Update `ActorRegistry.add()` to use `ActorConfigSchema` for v3 YAML parsing - [ ] Derive `provider` and `model` from `ActorConfigSchema` fields (e.g., from `config.actor` reference or `model` field) - [ ] Maintain backward compatibility with v2 YAML format (which has `provider:` and `model:` directly) - [ ] Add Behave unit tests for `agents actor add` with spec-compliant v3 YAML - [ ] Update `agents actor add` CLI to handle the v3 format ## Definition of Done - `agents actor add --config actor-v3.yaml` succeeds with spec-compliant v3 YAML - `ActorRegistry.add()` uses `ActorConfigSchema` for v3 format parsing - Backward compatibility with v2 YAML format is maintained - `nox -e unit_tests` passes --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo commented

2026-04-03 18:40:59 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: Should Have — Spec compliance or quality improvement that should be included in the milestone.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: Should Have — Spec compliance or quality improvement that should be included in the milestone. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-03 18:43:28 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1571 — v3.7.0 #2516

freemo commented

2026-04-05 03:15:03 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Confirmed
MoSCoW: Should Have (already set)

Valid finding verified during batch triage.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have (already set) Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added this to the v3.7.0 milestone

2026-04-05 05:07:07 +00:00