freemo
e9c96c3d0c
CI / build (push) Successful in 17s
CI / lint (push) Failing after 19s
CI / helm (push) Successful in 34s
CI / security (push) Failing after 42s
CI / quality (push) Has been cancelled
CI / unit_tests (push) Has been cancelled
CI / e2e_tests (push) Has been cancelled
CI / integration_tests (push) Has been cancelled
CI / typecheck (push) Has been cancelled
CI / benchmark-publish (push) Has been cancelled
CI / coverage (push) Has been cancelled
CI / benchmark-regression (push) Has been cancelled
CI / docker (push) Has been cancelled
CI / status-check (push) Has been cancelled
Add docs/api/ with per-module API documentation for core, a2a, actor, skills, tool, mcp, resource, and config packages. Add docs/architecture.md with a developer-oriented system overview including component map, layer diagram, plan lifecycle, and key design decisions. Update mkdocs.yml nav to expose both new sections. ISSUES CLOSED: #N/A
116 lines
3.1 KiB
Markdown
116 lines
3.1 KiB
Markdown
# `cleveragents.actor` — Actor System
|
|
|
|
The `actor` package provides the actor registry, YAML configuration schema,
|
|
loader, and compiler. Actors are the primary execution units in CleverAgents
|
|
— they encapsulate an LLM, a set of tools, and a LangGraph execution graph.
|
|
|
|
See [ADR-010](../adr/ADR-010-actor-and-agent-architecture.md) and
|
|
[ADR-031](../adr/ADR-031-actor-abstraction-definition.md) for design rationale.
|
|
|
|
!!! note "Lazy imports"
|
|
The `actor` package uses lazy imports to avoid pulling in heavy
|
|
transitive dependencies (LangChain, LangSmith, SQLAlchemy) when only
|
|
lightweight submodules such as `role_validation` or `schema` are needed.
|
|
|
|
---
|
|
|
|
## `ActorConfiguration`
|
|
|
|
```python
|
|
from cleveragents.actor import ActorConfiguration
|
|
```
|
|
|
|
Pydantic model representing a fully-parsed actor YAML file. Key fields:
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `name` | `str` | Actor identifier (namespaced, e.g. `openai/gpt-4o`) |
|
|
| `entry_node` | `str` | Graph entry node name |
|
|
| `nodes` | `dict[str, NodeConfig]` | Node definitions |
|
|
| `edges` | `list[EdgeConfig]` | Graph edges |
|
|
| `lsp_binding` | `LSPBinding \| None` | Per-node LSP server binding |
|
|
| `tool_sources` | `list[str]` | Tool source references |
|
|
|
|
---
|
|
|
|
## `ActorLoader`
|
|
|
|
```python
|
|
from cleveragents.actor import ActorLoader
|
|
|
|
loader = ActorLoader()
|
|
actors = loader.discover(Path("./actors/"))
|
|
```
|
|
|
|
Discovers and loads actor YAML files from a directory tree. Validates
|
|
graph reachability (all nodes reachable from `entry_node`) and reports
|
|
YAML line/column positions on error.
|
|
|
|
### Methods
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `discover(path)` | Scan directory for actor YAML files |
|
|
| `load(path)` | Load a single actor YAML file |
|
|
| `validate(config)` | Validate an `ActorConfiguration` |
|
|
|
|
---
|
|
|
|
## `ActorRegistry`
|
|
|
|
```python
|
|
from cleveragents.actor import ActorRegistry
|
|
|
|
registry = ActorRegistry()
|
|
registry.register(actor_config)
|
|
actor = registry.get("openai/gpt-4o")
|
|
```
|
|
|
|
In-memory registry for actor configurations. Thread-safe.
|
|
|
|
---
|
|
|
|
## `compile_actor` / `CompiledActor`
|
|
|
|
```python
|
|
from cleveragents.actor import compile_actor, CompiledActor
|
|
|
|
compiled: CompiledActor = compile_actor(actor_config, tool_registry)
|
|
```
|
|
|
|
Compiles an `ActorConfiguration` into a runnable `CompiledActor` by
|
|
resolving tool bindings, building the LangGraph state machine, and
|
|
attaching LSP/MCP adapters.
|
|
|
|
### `CompilationMetadata`
|
|
|
|
Carries diagnostics from the compilation step: resolved tools, skipped
|
|
nodes, and any warnings.
|
|
|
|
---
|
|
|
|
## Compilation Errors
|
|
|
|
| Exception | Description |
|
|
|-----------|-------------|
|
|
| `ActorCompilationError` | General compilation failure |
|
|
| `MissingNodeError` | Referenced node not defined |
|
|
| `InvalidEntryExitError` | Entry/exit node configuration invalid |
|
|
| `SubgraphCycleError` | Cycle detected in subgraph references |
|
|
|
|
---
|
|
|
|
## Example: Loading and Compiling an Actor
|
|
|
|
```python
|
|
from pathlib import Path
|
|
from cleveragents.actor import ActorLoader, compile_actor
|
|
from cleveragents.tool import ToolRegistry
|
|
|
|
loader = ActorLoader()
|
|
config = loader.load(Path("examples/actors/graph_workflow.yaml"))
|
|
|
|
tool_registry = ToolRegistry()
|
|
compiled = compile_actor(config, tool_registry)
|
|
```
|