Skip to main content

cleveractors-core

cleveractors-core is the Python library that implements Actor YAML parsing, validation, and execution. It lives at packages/cleveractors-core/ and is imported by the API server as a regular Python dependency.

The library has no HTTP surface — it is purely a library. This boundary is intentional: it means the Actor execution engine can be used in other contexts (CLI tools, test harnesses, alternative server implementations) without any dependency on FastAPI or the CleverThis server infrastructure.

Library structure​

packages/cleveractors-core/
├── cleveractors/
│   ├── schema/
│   │   └── actor_config.py    # Pydantic models for the Actor YAML schema
│   ├── executor/
│   │   ├── base.py            # ActorExecutor base class and protocol
│   │   ├── llm_agent.py       # LlmAgent execution logic
│   │   ├── router_agent.py    # RouterAgent execution logic
│   │   ├── tool_agent.py      # ToolAgent execution logic
│   │   └── graph.py           # Graph traversal and routing logic
│   ├── loader.py              # YAML parsing and validation entry point
│   └── streaming.py           # SSE streaming utilities
└── tests/

Executor API​

The primary entry point is ActorExecutor:

from cleveractors import ActorExecutor, load_actor

actor = load_actor("path/to/actor.yaml")  # parses + validates YAML
executor = ActorExecutor(actor, provider_client=...)

async for chunk in executor.stream(messages):
    yield chunk  # SSE-compatible chunk

ActorExecutor accepts a provider_client argument that abstracts upstream LLM calls. In production, the API server passes a client that routes through the CleverThis provider registry. In tests, a mock client is injected.

Adding a new agent type​

To add a new agent type:

  1. Add a new Pydantic model in schema/actor_config.py.
  2. Add the new type to the AgentConfig discriminated union.
  3. Implement the execution logic in a new file under executor/.
  4. Register the new type in executor/base.py's agent factory.
  5. Add tests in tests/ covering the new agent type.
Coming soon

Full executor API reference and a guide for implementing custom tool agents are being added.