cleveragents/cleveragents-core

Fork 3

UAT: `ActorConfigSchema` does not support spec-defined top-level multi-actor structure — `actors`/`agents` map, `routes`, `merges`, `splits`, `templates`, `instances`, `global_context`, `prompts`, `pipelines` keys missing #3001

New issue

Open

opened 2026-04-05 03:28:40 +00:00 by freemo · 3 comments

freemo commented

2026-04-05 03:28:40 +00:00

Owner

Metadata

Branch: fix/actor-config-schema-multi-actor-structure
Commit Message: fix(actor): add top-level multi-actor keys to ActorConfigSchema per spec
Milestone: v3.7.0
Parent Epic: #392

Bug Report

Feature Area: Configuration Files — Actor Configuration Files Schema

Spec Reference: Actor Configuration Files section, JSON Schema definition:

{
  "properties": {
    "name": {...},
    "cleveragents": {...},
    "actors": {"$ref": "#/$defs/actorMap"},
    "agents": {"$ref": "#/$defs/actorMap", "description": "Alias for 'actors'"},
    "routes": {...},
    "merges": {...},
    "splits": {...},
    "templates": {...},
    "instances": {...},
    "global_context": {...},
    "prompts": {...},
    "pipelines": {...}
  }
}

Expected Behavior (per spec)

The actor configuration file schema should support:

A top-level actors (or agents) map containing multiple named actor definitions
routes — map of route names to graph topology definitions
merges — stream merge operations
splits — stream split operations
templates — reusable template definitions for Jinja2 template inheritance
instances — instantiated templates with bound parameters
global_context — key-value pairs available to all actors via {{ context.key }}
prompts — named prompt templates
pipelines — hybrid pipeline definitions
A cleveragents metadata block with version, logging, template_engine, unsafe, default_actor

Actual Behavior

src/cleveragents/actor/schema.py defines ActorConfigSchema as a flat single-actor model with fields:

name, type, description, version, model, system_prompt, tools, context_view, memory, context, route, skills, lsp, lsp_capabilities, lsp_context_enrichment, env_vars

This model represents a single actor definition, not the multi-actor file structure described in the spec. The following top-level keys from the spec are entirely absent from ActorConfigSchema:

actors / agents (map of actor definitions)
routes (top-level route map)
merges (stream merge operations)
splits (stream split operations)
templates (Jinja2 template definitions)
instances (template instantiations)
global_context (shared context variables)
prompts (named prompt templates)
pipelines (hybrid pipeline definitions)
cleveragents metadata block (with version, logging, template_engine, unsafe, default_actor)

The ActorConfiguration class in src/cleveragents/actor/config.py does handle the agents key (for v2 compatibility) but only extracts the first agent's provider/model — it does not validate or expose the full multi-actor structure.

Steps to Reproduce

Create an actor YAML file with the spec-defined multi-actor structure:

cleveragents:
  version: "3.0"
  default_actor: my_actor
actors:
  my_actor:
    type: llm
    model: gpt-4
    system_prompt: "You are a helpful assistant"
global_context:
  project_name: MyProject

Run agents actor add --config actor.yaml
Observe: The cleveragents metadata block, actors map, and global_context are not validated by ActorConfigSchema

Impact

The spec-defined actor config file format cannot be validated against the schema
Multi-actor configurations with shared global_context, templates, and prompts are not supported
The cleveragents.version, cleveragents.logging, cleveragents.template_engine, cleveragents.unsafe, and cleveragents.default_actor metadata fields are not validated
Stream topology features (merges, splits) are not accessible from the config schema

Code Location

src/cleveragents/actor/schema.py — ActorConfigSchema class

Subtasks

Audit ActorConfigSchema in src/cleveragents/actor/schema.py against the spec JSON Schema definition
Add cleveragents metadata block schema (with version, logging, template_engine, unsafe, default_actor sub-fields)
Add actors / agents top-level map field (referencing the existing single-actor schema as the map value type)
Add routes top-level map field for graph topology definitions
Add merges and splits top-level fields for stream operations
Add templates and instances top-level fields for Jinja2 template support
Add global_context top-level field for shared key-value context
Add prompts top-level field for named prompt templates
Add pipelines top-level field for hybrid pipeline definitions
Update ActorConfiguration in src/cleveragents/actor/config.py to validate and expose the full multi-actor structure
Add/update unit tests covering all new top-level schema fields
Verify agents actor add --config <FILE> correctly validates multi-actor YAML files end-to-end

Definition of Done

ActorConfigSchema supports all spec-defined top-level keys: cleveragents, actors/agents, routes, merges, splits, templates, instances, global_context, prompts, pipelines
ActorConfiguration validates and exposes the full multi-actor structure from a config file
A multi-actor YAML file (as shown in Steps to Reproduce) passes schema validation without errors
All new fields are covered by unit tests
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/actor-config-schema-multi-actor-structure` - **Commit Message**: `fix(actor): add top-level multi-actor keys to ActorConfigSchema per spec` - **Milestone**: v3.7.0 - **Parent Epic**: #392 ## Bug Report **Feature Area:** Configuration Files — Actor Configuration Files Schema **Spec Reference:** Actor Configuration Files section, JSON Schema definition: ```json { "properties": { "name": {...}, "cleveragents": {...}, "actors": {"$ref": "#/$defs/actorMap"}, "agents": {"$ref": "#/$defs/actorMap", "description": "Alias for 'actors'"}, "routes": {...}, "merges": {...}, "splits": {...}, "templates": {...}, "instances": {...}, "global_context": {...}, "prompts": {...}, "pipelines": {...} } } ``` ### Expected Behavior (per spec) The actor configuration file schema should support: - A top-level `actors` (or `agents`) map containing multiple named actor definitions - `routes` — map of route names to graph topology definitions - `merges` — stream merge operations - `splits` — stream split operations - `templates` — reusable template definitions for Jinja2 template inheritance - `instances` — instantiated templates with bound parameters - `global_context` — key-value pairs available to all actors via `{{ context.key }}` - `prompts` — named prompt templates - `pipelines` — hybrid pipeline definitions - A `cleveragents` metadata block with `version`, `logging`, `template_engine`, `unsafe`, `default_actor` ### Actual Behavior `src/cleveragents/actor/schema.py` defines `ActorConfigSchema` as a **flat single-actor model** with fields: - `name`, `type`, `description`, `version`, `model`, `system_prompt`, `tools`, `context_view`, `memory`, `context`, `route`, `skills`, `lsp`, `lsp_capabilities`, `lsp_context_enrichment`, `env_vars` This model represents a **single actor** definition, not the multi-actor file structure described in the spec. The following top-level keys from the spec are entirely absent from `ActorConfigSchema`: - `actors` / `agents` (map of actor definitions) - `routes` (top-level route map) - `merges` (stream merge operations) - `splits` (stream split operations) - `templates` (Jinja2 template definitions) - `instances` (template instantiations) - `global_context` (shared context variables) - `prompts` (named prompt templates) - `pipelines` (hybrid pipeline definitions) - `cleveragents` metadata block (with `version`, `logging`, `template_engine`, `unsafe`, `default_actor`) The `ActorConfiguration` class in `src/cleveragents/actor/config.py` does handle the `agents` key (for v2 compatibility) but only extracts the first agent's provider/model — it does not validate or expose the full multi-actor structure. ### Steps to Reproduce 1. Create an actor YAML file with the spec-defined multi-actor structure: ```yaml cleveragents: version: "3.0" default_actor: my_actor actors: my_actor: type: llm model: gpt-4 system_prompt: "You are a helpful assistant" global_context: project_name: MyProject ``` 2. Run `agents actor add --config actor.yaml` 3. Observe: The `cleveragents` metadata block, `actors` map, and `global_context` are not validated by `ActorConfigSchema` ### Impact - The spec-defined actor config file format cannot be validated against the schema - Multi-actor configurations with shared `global_context`, `templates`, and `prompts` are not supported - The `cleveragents.version`, `cleveragents.logging`, `cleveragents.template_engine`, `cleveragents.unsafe`, and `cleveragents.default_actor` metadata fields are not validated - Stream topology features (`merges`, `splits`) are not accessible from the config schema ### Code Location `src/cleveragents/actor/schema.py` — `ActorConfigSchema` class ## Subtasks - [ ] Audit `ActorConfigSchema` in `src/cleveragents/actor/schema.py` against the spec JSON Schema definition - [ ] Add `cleveragents` metadata block schema (with `version`, `logging`, `template_engine`, `unsafe`, `default_actor` sub-fields) - [ ] Add `actors` / `agents` top-level map field (referencing the existing single-actor schema as the map value type) - [ ] Add `routes` top-level map field for graph topology definitions - [ ] Add `merges` and `splits` top-level fields for stream operations - [ ] Add `templates` and `instances` top-level fields for Jinja2 template support - [ ] Add `global_context` top-level field for shared key-value context - [ ] Add `prompts` top-level field for named prompt templates - [ ] Add `pipelines` top-level field for hybrid pipeline definitions - [ ] Update `ActorConfiguration` in `src/cleveragents/actor/config.py` to validate and expose the full multi-actor structure - [ ] Add/update unit tests covering all new top-level schema fields - [ ] Verify `agents actor add --config <FILE>` correctly validates multi-actor YAML files end-to-end ## Definition of Done - [ ] `ActorConfigSchema` supports all spec-defined top-level keys: `cleveragents`, `actors`/`agents`, `routes`, `merges`, `splits`, `templates`, `instances`, `global_context`, `prompts`, `pipelines` - [ ] `ActorConfiguration` validates and exposes the full multi-actor structure from a config file - [ ] A multi-actor YAML file (as shown in Steps to Reproduce) passes schema validation without errors - [ ] All new fields are covered by unit tests - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-05 03:30:37 +00:00

freemo referenced this issue

2026-04-05 03:33:18 +00:00

Task: Autonomous build progress report — 2026-04-05 #2874

freemo added a new dependency

2026-04-05 03:35:16 +00:00

#392 Epic: Actor YAML & Compiler

freemo commented

2026-04-05 03:36:29 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels: Priority/High, State/Unverified, Type/Bug
Reason: Issue was missing all required labels per CONTRIBUTING.md. Inferred Type/Bug from the "UAT:" prefix. Applied Priority/High (schema missing spec-defined fields is high severity) and State/Unverified as defaults.

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

Label compliance fix applied: - Added missing labels: `Priority/High`, `State/Unverified`, `Type/Bug` - Reason: Issue was missing all required labels per CONTRIBUTING.md. Inferred `Type/Bug` from the "UAT:" prefix. Applied `Priority/High` (schema missing spec-defined fields is high severity) and `State/Unverified` as defaults. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-05 03:38:31 +00:00

[CA-AUTO] Backlog Groomer — groomer-1 — Session Tracker #2771

freemo commented

2026-04-05 03:43:11 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Confirmed
MoSCoW: Should Have

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 Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo commented

2026-04-05 06:12:33 +00:00

Author

Owner

Label compliance fix applied:

Removed conflicting label: State/In Progress
Retained: State/Verified
Reason: Issue had two conflicting State/* labels simultaneously. Per CONTRIBUTING.md, only one State/* label is permitted. State/Verified is the more advanced state and has been retained.

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

Label compliance fix applied: - Removed conflicting label: `State/In Progress` - Retained: `State/Verified` - Reason: Issue had two conflicting `State/*` labels simultaneously. Per CONTRIBUTING.md, only one `State/*` label is permitted. `State/Verified` is the more advanced state and has been retained. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-05 06:15:22 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo referenced this issue

2026-04-05 06:35:39 +00:00

[CA-AUTO] Backlog Groomer — groomer-1 — Session Tracker #2771