# v3.1.0 — Actor YAML Format & Compiler

Declarative actor definitions compiled into LangGraph graphs.

---

## Actor YAML Format

Every actor file must specify `version: "3"` and one of three types: `llm`, `tool`, or `graph`.

See [Actor YAML Schema Reference](../../reference/actors_schema.md) for full fields.

### LLM Actor

```yaml
version: "3"
name: assistants/code-reviewer
type: llm
model: gpt-4
system_prompt: |
  You are an expert Python code reviewer.
context_view: reviewer
memory:
  enabled: true
  max_messages: 20
```

### Tool Actor

```yaml
version: "3"
name: utilities/file-ops
type: tool
tools:
  - files/read_file
  - files/write_file
  - files/list_directory
```

### Graph Actor

```yaml
version: "3"
name: workflows/tdd-cycle
type: graph
model: gpt-4
route:
  nodes:
    - id: planner; type: agent; name: Task Planner
      config: { model: gpt-4, prompt: "Plan implementation tasks." }
    - id: implementer; type: agent; name: Code Implementer
      config: { model: gpt-4, prompt: "Implement planned tasks." }
    - id: verifier; type: tool; name: Test Runner
      config: { tool_name: testing/run_pytest }
    - id: check_results; type: conditional
      config: { conditions: [{check: "passed==True", route_to: done}, {check: "passed==False", route_to: implementer}] }
    - id: done; type: agent; name: Summary Writer
  edges:
    - {from_node: planner, to_node: implementer}
    - {from_node: implementer, to_node: verifier}
    - {from_node: verifier, to_node: check_results}
  entry_node: planner
  exit_nodes: [done]
```

### Actor Name Format

Must use `namespace/name`:
- `assistants/code-reviewer` — valid
- `code-reviewer` — invalid (no namespace)
- `a/b/c` — invalid (too many slashes)

---

## Actor Compiler (LangGraph Integration)

Translates GRAPH-type YAML into LangGraph `StateGraph` structures.

See [Actor Compiler Reference](../../reference/actor_compiler.md).

### Compilation Pipeline

```
ActorConfigSchema (type=GRAPH)
  -> validate type, route
  -> reference validation (all node IDs exist)
  -> intra-graph cycle detection
  -> cross-actor subgraph cycle detection
  -> node mapping (NodeDef -> LangGraph NodeConfig)
  -> edge mapping
  -> metadata assembly
  => CompiledActor (nodes, edges, entry_point, metadata)
```

### Node Type Mapping

| Actor Node | LangGraph Type |
|------------|----------------|
| `agent` | AGENT |
| `tool` | TOOL |
| `conditional` | CONDITIONAL |
| `subgraph` | SUBGRAPH |

### Compilation Errors

| Error | Class | When |
|-------|-------|------|
| Non-GRAPH type | `ActorCompilationError` | config.type != GRAPH |
| Missing route | `ActorCompilationError` | config.route is None |
| Missing node | `MissingNodeError` | edge refs unknown node |
| Invalid entry/exit | `InvalidEntryExitError` | node not in graph |
| Cycle detected | `SubgraphCycleError` | intra or cross-actor cycle |

### Graph Validation Rules

1. Unique node IDs within graph
2. Entry node exists and is valid
3. All exit_nodes reference valid nodes
4. All edge from_node/to_node exist
5. No cycles (graphs are acyclic)
6. All nodes reachable from entry_node

---

## See Also

- [Actor YAML Schema Reference](../../reference/actors_schema.md)
- [Actor Compiler Reference](../../reference/actor_compiler.md)
- [ADR-010](../../adr/ADR-010-actor-and-agent-architecture.md): Actor Architecture
- [ADR-022](../../adr/ADR-022-langchain-langgraph-integration.md): LangGraph Integration
- [ADR-031](../../adr/ADR-031-actor-abstraction-definition.md): Actor Abstraction Definition
