- Python 99.7%
- Gherkin 0.3%
d2d26f1780
Some checks failed
CI / unit_tests (push) Successful in 1m18s
CI / build (push) Has been skipped
CI / typecheck (push) Failing after 1m20s
CI / lint (push) Failing after 1m20s
CI / dead_code (push) Failing after 43s
CI / security (push) Successful in 1m19s
CI / coverage (push) Successful in 1m20s
docs/specification.md — the library's architectural commitment:
scope diagram, public surface, extension points (ToolRegistryPort),
explicit list of what's NOT in scope, origin sha, versioning
policy, and concrete integration patterns for cleveragents-core
and cleverrouter.
docs/adr/ADR-001-library-boundary-and-extraction-scope.md —
records the Medium-scope decision; lists the file-by-file
extraction table; documents the rejected alternatives (Narrow,
Wide, and 'no extraction'); names the upstream commit
(20ad9a46) the extraction baseline traces back to.
docs/adr/ADR-002-tool-registry-protocol.md — records the Protocol
decoupling that lets the library accept any object with
`get(name) -> spec | None` as a tool registry without
importing cleveragents-core or cleverrouter.
mkdocs.yml — site config with three-page nav (Home + Specification +
ADRs), Material theme, permalinked TOC.
docs/index.md — symlinked copy of README.md so the rendered site
renders the library README as the home page.
The two ADRs use the same metadata frontmatter shape (adr_number,
status_history, tier, authors, related_adrs) as cleveragents-core's
ADRs so contributors moving between projects see identical structure.
|
||
|---|---|---|
| .forgejo/workflows | ||
| docs | ||
| features | ||
| src/cleveractors | ||
| .bumpversion.cfg | ||
| .editorconfig | ||
| .gitattributes | ||
| .gitignore | ||
| .pre-commit-config.yaml | ||
| .semgrep.yml | ||
| ATTRIBUTIONS.md | ||
| behave.ini | ||
| CODE_OF_CONDUCT.md | ||
| LICENSE | ||
| mkdocs.yml | ||
| NOTICE | ||
| noxfile.py | ||
| pyproject.toml | ||
| pyrightconfig.json | ||
| README.md | ||
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.