cleveragents/cleveragents-core

Fork 3

UAT: `ActorConfigSchema` `version` field defaults to `"1.0"` but spec defines `cleveragents.version: "3.0"` metadata block #5475

New issue

Open

opened 2026-04-09 06:57:14 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 06:57:14 +00:00

Owner

Bug Report

Feature Area

Actor System Compilation — Actor YAML schema version field

What Was Tested

Code-level analysis of src/cleveragents/actor/schema.py against the specification's actor YAML schema definition.

Expected Behavior (from spec)

Per docs/specification.md lines 30991, 31019-31056, actor configuration files use a cleveragents metadata block for schema versioning:

cleveragents:
  version: "3.0"             # Schema version (default: "3.0")
  logging:
    level: "INFO"
  template_engine: "JINJA2"
  unsafe: false
  default_actor: my_actor

The spec states: "Configuration files may include a top-level cleveragents.version field to indicate which schema version they target (currently "3.0"). When omitted, the latest schema version is assumed."

The JSON Schema definition (lines 31019-31056) defines cleveragents as a top-level object with version, logging, template_engine, unsafe, and default_actor sub-fields.

Actual Behavior (from code)

src/cleveragents/actor/schema.py defines a top-level version field on ActorConfigSchema that defaults to "1.0":

class ActorConfigSchema(BaseModel):
    ...
    version: str = Field(default="1.0", description="Schema version")
    ...

This is a flat top-level version field, not a nested cleveragents.version field. The ActorConfigSchema does not model the cleveragents metadata block at all — there is no cleveragents field, no logging sub-field, no template_engine sub-field, and no default_actor sub-field.

Impact

Actor YAML files that include cleveragents: {version: "3.0"} (per spec) will have this block silently ignored or cause a validation error.
The version field in the schema defaults to "1.0" instead of the spec-required "3.0".
The cleveragents.logging, cleveragents.template_engine, cleveragents.unsafe, and cleveragents.default_actor metadata fields are completely unsupported.
This creates a schema incompatibility between the v3 actor YAML format described in the spec and what the code actually validates.

Code Location

src/cleveragents/actor/schema.py line 715 (version: str = Field(default="1.0", ...))
docs/specification.md lines 30991, 31019-31056 (spec defines cleveragents metadata block)

Fix Required

Add a CleverAgentsMetadata Pydantic model with version, logging, template_engine, unsafe, default_actor fields
Add a cleveragents: CleverAgentsMetadata | None field to ActorConfigSchema
Update the version field default to "3.0" or remove it in favor of cleveragents.version
Ensure backward compatibility with actor YAML files that use the flat version field

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

## Bug Report ### Feature Area Actor System Compilation — Actor YAML schema version field ### What Was Tested Code-level analysis of `src/cleveragents/actor/schema.py` against the specification's actor YAML schema definition. ### Expected Behavior (from spec) Per `docs/specification.md` lines 30991, 31019-31056, actor configuration files use a `cleveragents` metadata block for schema versioning: ```yaml cleveragents: version: "3.0" # Schema version (default: "3.0") logging: level: "INFO" template_engine: "JINJA2" unsafe: false default_actor: my_actor ``` The spec states: "Configuration files may include a top-level `cleveragents.version` field to indicate which schema version they target (currently `"3.0"`). When omitted, the latest schema version is assumed." The JSON Schema definition (lines 31019-31056) defines `cleveragents` as a top-level object with `version`, `logging`, `template_engine`, `unsafe`, and `default_actor` sub-fields. ### Actual Behavior (from code) `src/cleveragents/actor/schema.py` defines a top-level `version` field on `ActorConfigSchema` that defaults to `"1.0"`: ```python class ActorConfigSchema(BaseModel): ... version: str = Field(default="1.0", description="Schema version") ... ``` This is a flat top-level `version` field, not a nested `cleveragents.version` field. The `ActorConfigSchema` does not model the `cleveragents` metadata block at all — there is no `cleveragents` field, no `logging` sub-field, no `template_engine` sub-field, and no `default_actor` sub-field. ### Impact - Actor YAML files that include `cleveragents: {version: "3.0"}` (per spec) will have this block silently ignored or cause a validation error. - The `version` field in the schema defaults to `"1.0"` instead of the spec-required `"3.0"`. - The `cleveragents.logging`, `cleveragents.template_engine`, `cleveragents.unsafe`, and `cleveragents.default_actor` metadata fields are completely unsupported. - This creates a schema incompatibility between the v3 actor YAML format described in the spec and what the code actually validates. ### Code Location - `src/cleveragents/actor/schema.py` line 715 (`version: str = Field(default="1.0", ...)`) - `docs/specification.md` lines 30991, 31019-31056 (spec defines `cleveragents` metadata block) ### Fix Required 1. Add a `CleverAgentsMetadata` Pydantic model with `version`, `logging`, `template_engine`, `unsafe`, `default_actor` fields 2. Add a `cleveragents: CleverAgentsMetadata | None` field to `ActorConfigSchema` 3. Update the `version` field default to `"3.0"` or remove it in favor of `cleveragents.version` 4. Ensure backward compatibility with actor YAML files that use the flat `version` field --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 06:57:47 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-09 06:59:20 +00:00

HAL9000 added

and removed

labels

2026-04-09 07:00:16 +00:00

HAL9000 commented

2026-04-09 07:00:39 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: - Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 referenced this issue

2026-04-09 07:01:00 +00:00

[AUTO-PROJ-OWN] Project Owner Report (Cycle 26) #5296

HAL9000 referenced this issue

2026-04-09 07:06:47 +00:00

EPIC: Actor Execution & Configuration — GRAPH Actor, Config Schema & CLI Compliance (v3.5.0) #5502

HAL9000 added a new dependency

2026-04-09 07:09:06 +00:00

#5502 EPIC: Actor Execution & Configuration — GRAPH Actor, Config Schema & CLI Compliance (v3.5.0)

HAL9000 referenced this issue

2026-04-09 07:13:39 +00:00

[AUTO-EPIC] Epic Planning Health Report (Cycle 11) #5298