feat(actor): add actor yaml schema models #292

Closed
opened 2026-02-22 23:40:59 +00:00 by freemo · 1 comment
Owner

Metadata

  • Commit: feat(actor): add actor yaml schema models
  • Branch: feature/m3-actor-schema-examples

Subtasks

  • Add schema models (ActorType, NodeType, ContextView, ToolDefinition, RouteDefinition, ActorConfigSchema) with strict validation in src/cleveragents/actor/schema.py.
  • Add tool-node schema fields that reference Tool Registry names, including validation nodes, and require input/output schema presence.
  • Add hierarchical graph node schema (children, edges, entrypoint, exitpoints) to support nested actors and subgraphs.
  • Add YAML load/serialize helpers and schema version guard.
  • Add graph validation rules (entrypoint exists, exitpoints reachable, no orphan nodes).
  • Add cycle detection for actor graphs and explicit errors for invalid loops.
  • Add docs/reference/actors_schema.md with field definitions, tool node semantics, and graph constraints.
  • Add graph validation examples (valid/invalid) and error messages.
  • Tests (Behave): Add features/actor_schema.feature scenarios for validation and topology errors.
  • Tests (Robot): Add robot/actor_schema.robot YAML load smoke test.
  • Tests (ASV): Add benchmarks/actor_schema_bench.py for YAML validation cost.
  • Run nox (all default sessions, including benchmark).
  • Verify coverage >=97% via nox -s coverage_report. If coverage is <97% then review the current unit test coverage report at build/coverage.xml and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun nox -s coverage_report to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.

Section: ### Section 5: Actors, Skills & Tool Execution [WORKSTREAM C - Aditya Lead]
Status: Completed

## Metadata - **Commit**: `feat(actor): add actor yaml schema models` - **Branch**: `feature/m3-actor-schema-examples` ## Subtasks - [x] Add schema models (ActorType, NodeType, ContextView, ToolDefinition, RouteDefinition, ActorConfigSchema) with strict validation in `src/cleveragents/actor/schema.py`. - [x] Add tool-node schema fields that reference Tool Registry names, including validation nodes, and require input/output schema presence. - [x] Add hierarchical graph node schema (`children`, `edges`, `entrypoint`, `exitpoints`) to support nested actors and subgraphs. - [x] Add YAML load/serialize helpers and schema version guard. - [x] Add graph validation rules (entrypoint exists, exitpoints reachable, no orphan nodes). - [x] Add cycle detection for actor graphs and explicit errors for invalid loops. - [x] Add `docs/reference/actors_schema.md` with field definitions, tool node semantics, and graph constraints. - [x] Add graph validation examples (valid/invalid) and error messages. - [x] Tests (Behave): Add `features/actor_schema.feature` scenarios for validation and topology errors. - [x] Tests (Robot): Add `robot/actor_schema.robot` YAML load smoke test. - [x] Tests (ASV): Add `benchmarks/actor_schema_bench.py` for YAML validation cost. - [x] Run `nox` (all default sessions, including benchmark). - [x] Verify coverage >=97% via `nox -s coverage_report`. If coverage is <97% then review the current unit test coverage report at `build/coverage.xml` and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `nox -s coverage_report` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. **Section**: ### Section 5: Actors, Skills & Tool Execution [WORKSTREAM C - Aditya Lead] **Status**: Completed
freemo added this to the v3.1.0 milestone 2026-02-22 23:40:59 +00:00
Author
Owner

Implementation Notes — C1.schema: Actor YAML Schema Models

2026-02-17: Task C1.schema Complete - Actor YAML Schema Models

  • Created src/cleveragents/actor/schema.py (695 lines) with three actor types (LLM, TOOL, GRAPH), graph topology validation with cycle detection using DFS, type-specific field requirements, environment variable interpolation.
  • 5 example actor YAMLs, 50+ Behave scenarios, 11 Robot test cases, 8 ASV benchmark classes.

(Migrated from docs/implementation-notes.md)

## Implementation Notes — C1.schema: Actor YAML Schema Models **2026-02-17**: Task C1.schema Complete - Actor YAML Schema Models - Created `src/cleveragents/actor/schema.py` (695 lines) with three actor types (LLM, TOOL, GRAPH), graph topology validation with cycle detection using DFS, type-specific field requirements, environment variable interpolation. - 5 example actor YAMLs, 50+ Behave scenarios, 11 Robot test cases, 8 ASV benchmark classes. *(Migrated from `docs/implementation-notes.md`)*
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#354 Epic: Actor & Skill Schema + CLI (C0)
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#292
No description provided.