freemo
bd93ae8894
Initial scaffolding for the library extracted from cleveragents-core
at commit 20ad9a46. This commit lays the empty package shell and the
quality-gate machinery; subsequent commits move actual source.
- pyproject.toml: Hatchling build; Python 3.13; pinned runtime
deps trimmed to what the library actually needs (pydantic,
structlog, langchain-core, langgraph, jinja2, pyyaml, jsonschema,
python-ulid). Dev/tests/docs extras mirror the parent.
- noxfile.py: 8 sessions matching cleveragents-core by name
(format, lint, typecheck, unit_tests, coverage_report,
security_scan, dead_code, complexity, build, docs); slimmed of
the parent's pabot / template-DB / worker plumbing because the
library is pure-domain.
- LICENSE, NOTICE, CODE_OF_CONDUCT.md, ATTRIBUTIONS.md,
.editorconfig, .gitattributes, .gitignore, .pre-commit-config.yaml,
.semgrep.yml, .bumpversion.cfg, behave.ini, pyrightconfig.json,
.python-version: copied verbatim from cleveragents-core so org-
wide policy stays in lockstep.
- README.md: tailored to the library's role; explains the
boundary with cleveragents-core and what's NOT in scope.
- src/cleveractors/__init__.py + py.typed: empty package marker
with module-level docstring listing the eventual sub-packages.
- features/steps/__init__.py: Behave test tree placeholder.
No source code is moved in this commit. The next two commits add the
CI workflow and the minimal shared types, after which the actor /
langgraph / templates / lsp / acms / agents subpackages land one
commit at a time.
2.6 KiB
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.