hurui200320
15e81e58f1
CI / dead_code (pull_request) Successful in 40s
CI / security (pull_request) Successful in 1m10s
CI / coverage (pull_request) Successful in 1m11s
CI / typecheck (pull_request) Successful in 1m19s
CI / unit_tests (pull_request) Successful in 1m18s
CI / lint (pull_request) Successful in 1m20s
CI / build (pull_request) Successful in 23s
CI / lint (push) Successful in 51s
CI / typecheck (push) Successful in 47s
CI / unit_tests (push) Successful in 49s
CI / coverage (push) Successful in 53s
CI / dead_code (push) Successful in 26s
CI / build (push) Successful in 26s
CI / security (push) Successful in 42s
Boundary fix: - Delete src/cleveractors/acms/index.py (ACMSIndex, FileTraversalEngine, IndexEntry, FileType, TierLevel) — these are CLI/storage concerns that belong in cleveragents-core per ADR-001; the file already exists there at cleveragents/acms/index.py - Clean src/cleveractors/acms/__init__.py: remove all index.py imports and re-exports; __all__ now derives purely from uko.__all__ ProviderRegistryPort (ADR-005): - Add src/cleveractors/ports/provider_registry.py: ProviderRegistryPort Protocol with get(provider, model) -> Agent | None; structural typing, no host imports, mirrors the shape of ToolRegistryPort - Update src/cleveractors/ports/__init__.py: export ProviderRegistryPort alongside ToolRegistryPort; update module docstring Wire provider resolution into the node executor: - compiler.py: _map_node now accepts actor_provider/actor_model defaults and merges them into AGENT node metadata (setdefault so per-node config values still win); compile_actor passes config.provider/config.model - nodes.py: Node.__init__ gains optional provider_registry parameter; _execute_agent resolution order is now: (1) pre-resolved agents dict, (2) ProviderRegistryPort.get(provider, model) from node metadata, (3) graceful synthetic fallback — the ValueError guard for missing config.agent is removed since the registry is a valid alternative path Documentation: - Port ADR-003 (actor abstraction definition) from cleveragents-core ADR-031 - Port ADR-004 (Jinja2 YAML template preprocessing) from cleveragents-core ADR-032 - Add ADR-005 (Provider Registry Protocol) for the new provider_registry port - Port five reference docs: actors_schema.md, actor_compiler.md, actor_config.md, actor_hierarchy.md, actors_examples.md - Port API reference: api/actor.md - Add provider field to all YAML examples in actors_examples.md, actor_hierarchy.md, and actor_config.md - Update error messages in actor_config.md to match actual validator output - Add graph-level provider/model propagation docs to actor_compiler.md - Add ADR-005 cross-references to ADR-001, ADR-002, and actors_schema.md - Fix ADR-005 status section to reflect that implementation is in this PR - Fix ADR-004 to reference actual test files (smoke.feature, not phantom ones) - Remove fabricated reserved-namespace constraint from ADR-003 Constraints - Fix broken LICENSE link in docs/index.md for MkDocs rendering - Add provider field to ActorConfigSchema table in api/actor.md - Add internal modules section to docs/specification.md (ticket item 7) - Fix markdown formatting in actors_schema.md provider field definition - Add ADR-005 cross-reference to actors_schema.md provider field section BDD coverage (7 scenarios, 30 steps): - ProviderRegistryPort happy-path resolution - Graceful fallback when provider registry returns None - Graceful fallback when no provider registry is supplied - Pre-resolved agents dict takes precedence over provider registry - Compile a minimal graph actor, reject missing provider, render template Post-review fixes applied in amend: - actors_examples.md and actor_hierarchy.md: added provider to all examples - ADR-003: removed fabricated reserved-namespace constraint - ADR-004: corrected phantom test file references - ADR-005: updated status to reflect implementation is included - Added 'no registry' and 'agents dict precedence' BDD scenarios - Added provider to api/actor.md ActorConfigSchema fields table - ADR-001 and ADR-002: added ADR-005 cross-references - actor_config.md: fixed error message to match validator - actor_compiler.md: documented graph-level provider/model propagation - index.md: fixed broken LICENSE link - actors_schema.md: added ADR-005 cross-reference ISSUES CLOSED: #4
2.8 KiB
2.8 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 — supply an adapter via cleveractors.ports.provider_registry.ProviderRegistryPort |
| 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.