brent.edwards
2ce29092f5
This code adds documentation of a sample actor. ISSUES CLOSED: #1 Reviewed-on: #3 Reviewed-by: Luis Mendes <luis.mendes@cleverthis.com>
CleverActors Core
CleverActors is the declarative-actor library used by CleverAgents and CleverRouter.
It is the smallest possible Python module that lets a host application:
- Parse a CleverAgents v3 actor YAML file (with sandboxed Jinja2 + env-var preprocessing).
- Validate it against the Pydantic schema.
- Compile it into a LangGraph node + edge graph ready for execution.
The library carries no I/O concerns of its own — no databases, no HTTP, no CLI, no dependency-injection containers. Persistence, event publishing, and lifecycle management belong to whoever consumes it.
Origin
Extracted from cleveragents/cleveragents-core at commit 20ad9a46 in 2026.
The extraction preserves the customer-facing YAML format exactly; the host
application sees the same ActorConfigSchema and compile_actor() surface
as before, just at a different import path.
Install
pip install "cleveractors @ git+https://git.cleverthis.com/cleveragents/cleveractors-core@master"
Quick start
from cleveractors.actor import compile_actor
from cleveractors.actor.schema import ActorConfigSchema
from cleveractors.actor.yaml_loader import load_yaml_text
raw = load_yaml_text(open("my-actor.yaml").read())
config = ActorConfigSchema.model_validate(raw)
compiled = compile_actor(config)
print(compiled.metadata.node_ids)
The compiled GraphConfig is the LangGraph spec — feed it to a runtime
that understands cleveractors.langgraph.nodes.Node / Edge /
NodeConfig, which the library also provides.
What the library does NOT do
These belong to the host application (cleveragents-core, cleverrouter, your own integration) — not the library:
| Concern | Where it lives |
|---|---|
| Actor persistence (DB) | cleveragents.application.services.actor_service |
| Decision tree recording | cleveragents.application.services.decision_service |
| Invariant reconciliation runtime | cleveragents.actor.reconciliation |
| Reactive stream routing | cleveragents.reactive |
| LangChain provider lookups | cleveragents.providers.registry (or supply via cleveractors.ports.provider_registry) |
| LSP runtime | cleveragents.lsp (only the data models live here) |
| Plan lifecycle (Action / Strategize / Execute / Apply) | cleveragents.application |
License
MIT — see LICENSE.
See also CleverAgents Operations Code (CONTRIBUTING) for commit, PR, and testing conventions.