# `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)
```