cleveractors-core/docs/specification.md

CleverActors Specification

Overview

CleverActors is a pure Python library: it parses a CleverAgents v3 actor YAML file, validates it against a Pydantic schema, optionally preprocesses it through a sandboxed Jinja2 engine, and compiles it into a LangGraph node + edge graph ready for execution by a host application.

The library carries no runtime concerns of its own — no I/O, no persistence, no event publishing, no CLI, no HTTP, no DI container. Everything that needs the host's state goes through the small set of Protocols in cleveractors.ports.

Scope

                      Customer YAML
                          │
                          ▼
                  ┌──────────────────────┐
                  │  cleveractors.actor  │  ← schema, loader, compiler,
                  │  .{loader,schema,    │    role validation, Jinja2
                  │   compiler,config,   │    preprocessing
                  │   yaml_loader,…}     │
                  └──────────┬───────────┘
                             │
                             ▼
                  ┌──────────────────────┐
                  │  cleveractors.       │  ← compile target — pure
                  │  langgraph.{nodes,   │    data classes describing
                  │  state, …}           │    node/edge structure
                  └──────────┬───────────┘
                             │
                             ▼
                       host application
                  (cleveragents-core, cleverrouter,
                   third-party)  drives the resulting
                   graph through whatever execution
                   model it chooses.

Public surface

from cleveractors.actor.schema   import ActorConfigSchema
from cleveractors.actor.compiler import compile_actor, CompiledActor
from cleveractors.actor.loader   import ActorLoader
from cleveractors.actor.config   import ActorConfiguration
from cleveractors.actor          import (
    ActorCompilationError,
    SubgraphCycleError,
    MissingNodeError,
    InvalidEntryExitError,
)
from cleveractors.langgraph.nodes import Node, Edge, NodeConfig, NodeType
from cleveractors.langgraph.state import GraphState, StateSnapshot
from cleveractors.templates.secure_renderer import SecureTemplateRenderer
from cleveractors.lsp.models     import LspBinding
from cleveractors.agents.base    import Agent       # minimal ABC
from cleveractors.acms.uko       import VocabularyRegistry
from cleveractors.core           import ValidationError, NotFoundError
from cleveractors.ports          import ToolRegistryPort, ProviderRegistryPort

Extension points (Protocols)

Protocol	Where the library calls it	Host concrete
cleveractors.ports.tool_registry.ToolRegistryPort	ActorLoader._resolve_tools() — looks up tool references at load time and emits a warning when unknown	cleveragents.tool.registry.ToolRegistry (cleveragents-core); cleverrouter's own tool registry; anything with a .get(name) -> spec | None method
cleveractors.ports.provider_registry.ProviderRegistryPort	Node._execute_agent() — resolves (provider, model) to an Agent instance at graph execution time	cleveragents.providers.registry wrapped in an adapter; cleverrouter's provider registry; any object with a .get(provider, model) -> Agent | None method — see ADR-005

What is intentionally NOT in the library

These belong to the host application:

Concern	Where it lives
Actor persistence (database)	cleveragents.application.services.actor_service
Decision-tree recording	cleveragents.application.services.decision_service
Invariant reconciliation runtime	cleveragents.actor.reconciliation
Actor registry runtime (ActorRegistry, v3_registry)	cleveragents.actor.{registry, v3_registry}
Reactive stream routing (rx, BehaviorSubject)	cleveragents.reactive
LangChain provider configuration	cleveragents.providers.registry
LSP runtime (registry, lifecycle, transport)	cleveragents.lsp.{registry, lifecycle, server, transport}
Plan lifecycle (Action / Strategize / Execute / Apply)	cleveragents.application
CLI / TUI / A2A wire protocol	cleveragents.{cli, tui, a2a}
ACMS indexer / file traversal engine	cleveragents.acms.index

Internal modules (not public API)

The following modules exist in the source tree but are not part of the public API surface. They are implementation details used internally and may change without a semver bump:

Module	Purpose
cleveractors.actor.role_validation	Validates that an actor config is appropriate for a declared role (strategy, execution, etc.) — logic used by the compiler, not exposed directly
cleveractors.actor.utils	Small shared helpers (name normalisation, namespace parsing) used across the actor package
cleveractors.actor.yaml_template_engine	YAMLTemplateEngine — the Jinja2 + env-var two-phase pipeline described in ADR-004; consumed by ActorLoader and SecureTemplateRenderer
cleveractors.langgraph.dynamic_router	DynamicRouter — minimal predicate-based edge selector; used internally by graph execution
cleveractors.langgraph.message_router	Helpers that build MESSAGE_ROUTER NodeConfig and its outgoing Edge list from a rule set
cleveractors.langgraph.pure_graph	PureGraph — lightweight Pydantic model for a named node/edge graph; used in tests and by the compiler before LangGraph wiring
cleveractors.langgraph.routing_adapter	build_route_nodes_from_stream — translates a reactive stream operator list into a NodeConfig / Edge chain; kept for migration compatibility

Origin

Extracted from cleveragents/cleveragents-core at commit 20ad9a46 in 2026. The extraction preserves the customer-facing actor YAML format exactly; consumers see the same ActorConfigSchema and compile_actor() surface — only the import path changes.

The decision tree that produced the extraction is recorded in:

• ADR-001: Library Boundary and Extraction Scope
• ADR-002: Tool Registry Protocol
• ADR-003: Actor Abstraction Definition
• ADR-004: Jinja2 YAML Template Preprocessing
• ADR-005: Provider Registry Protocol

Versioning

0.x.y while the library is following cleveragents-core changes closely. 1.0.0 will be cut once the surface has stabilised through at least one cleveragents-core release and one cleverrouter release that consume it.

Consumer integration patterns

cleveragents-core

The host already owns the actor lifecycle. It calls the library only for parsing + compile, and keeps its own registry/persistence/runtime.

from cleveractors.actor.loader import ActorLoader
from cleveractors.actor.compiler import compile_actor

# Host supplies its own tool registry (any object with .get(name) works).
loader = ActorLoader(search_roots=[...], tool_registry=my_tool_registry)
configs = loader.discover()
for cfg in configs:
    compiled = compile_actor(cfg)
    my_actor_service.persist(cfg, compiled)

cleverrouter

The cleverrouter gateway accepts an actor YAML upload, compiles it once into an immutable IR, and serves it as a model endpoint (model: actor/{namespace}/{name}@{version}). The library handles the parse + compile; cleverrouter holds the compiled artefact and runs it through its own LangGraph executor on each request.

from cleveractors.actor.compiler import compile_actor
from cleveractors.actor.schema   import ActorConfigSchema

# Inside the data-plane actor.deploy handler:
cfg = ActorConfigSchema.model_validate(yaml.safe_load(yaml_text))
compiled = compile_actor(cfg)
db.session.add(ActorVersion(
    actor_id=actor.id,
    source_hash=hashlib.sha256(yaml_text.encode()).hexdigest(),
    compiled_ir=compiled.model_dump(),
    safety_report=cleverrouter_safety_pass(compiled),
))