# Actor YAML Examples

## Overview

Comprehensive examples of actor YAML configurations, demonstrating various
use cases and patterns. Each example is valid against the `ActorConfigSchema`
and can be parsed and compiled by this library.

**Module:** `cleveractors.actor.schema`  
**Schema Version:** 1.0

**Related Documentation:**
- [Actor YAML Schema Reference](./actors_schema.md) — complete schema documentation
- [Actor Configuration Guide](./actor_config.md) — practical authoring guide
- [Actor Hierarchy Extensions](./actor_hierarchy.md) — LSP bindings and tool sources

---

## Table of Contents

1. [Simple LLM Actors](#simple-llm-actors)
2. [Strategist Actors](#strategist-actors)
3. [Executor Actors](#executor-actors)
4. [Reviewer Actors](#reviewer-actors)
5. [Estimation Actors](#estimation-actors)
6. [Tool-Only Actors](#tool-only-actors)
7. [Validation-Node Actors](#validation-node-actors)
8. [Graph Workflows](#graph-workflows)
9. [Hierarchical Actor Graphs](#hierarchical-actor-graphs)
10. [Best Practices](#best-practices)

---

## Simple LLM Actors

### Minimal Code Reviewer

A basic LLM actor with system prompt, memory, and context configuration.

```yaml
name: assistants/code_reviewer
type: llm
description: Reviews Python code for best practices, style, and potential bugs
version: "1.0"

provider: openai
model: gpt-4
system_prompt: |
  You are an expert Python code reviewer. Review code for:
  - PEP 8 style compliance
  - Best practices and design patterns
  - Potential bugs and edge cases
  - Performance considerations
  - Security vulnerabilities

  Provide constructive feedback with specific suggestions for improvement.

context_view: reviewer
memory:
  enabled: true
  max_messages: 20
  max_tokens: 4000

context:
  include_files:
    - "README.md"
    - "pyproject.toml"
  include_dirs:
    - "src/"
  exclude_patterns:
    - "**/__pycache__/**"
    - "*.pyc"
    - "**/.pytest_cache/**"
  max_context_tokens: 8000
```

**Use Cases:**
- Code review assistants
- Documentation reviewers
- Simple conversational agents
- Single-purpose analysis tools

---

## Strategist Actors

### Planning & Decomposition Actor

**Purpose:** Breaks down high-level goals into actionable steps.

```yaml
name: strategists/task_planner
type: llm
description: Analyzes requirements and creates detailed execution plans
version: "1.0"

provider: openai
model: gpt-4
system_prompt: |
  You are a strategic planning expert. Your role is to:

  1. Analyze the user's high-level goal
  2. Break it down into concrete, actionable steps
  3. Identify dependencies between steps
  4. Suggest parallel execution opportunities
  5. Estimate effort and risk for each step
  6. Recommend tools and resources needed

  Think carefully about edge cases and potential obstacles.
  Provide clear, specific instructions for each step.

context_view: strategist
memory:
  enabled: true
  max_messages: 50
  max_tokens: 16000

context:
  include_files:
    - "README.md"
    - "ARCHITECTURE.md"
    - "requirements.txt"
  include_dirs:
    - "src/"
    - "docs/"
    - "tests/"
  max_context_tokens: 32000

tools:
  - files/read_file
  - files/list_directory
  - git/get_status
```

**Key Features:**
- Large context window for complex planning
- Read-only tools for information gathering
- Strategist context view for high-level perspective
- Extended memory for multi-turn planning

---

## Executor Actors

### Implementation & Execution Actor

**Purpose:** Executes concrete tasks with write capabilities.

```yaml
name: executors/code_writer
type: llm
description: Implements code changes based on detailed specifications
version: "1.0"

provider: openai
model: gpt-4
system_prompt: |
  You are an expert software engineer. Your role is to:

  1. Read and understand the specification
  2. Implement clean, well-tested code
  3. Follow project conventions and style guides
  4. Write comprehensive docstrings and comments
  5. Consider edge cases and error handling

  Always verify your changes don't break existing tests.
  Write new tests for new functionality.

context_view: executor
memory:
  enabled: true
  max_messages: 30
  max_tokens: 8000

context:
  include_files:
    - "README.md"
    - "pyproject.toml"
    - "CONTRIBUTING.md"
  include_dirs:
    - "src/"
    - "tests/"
  exclude_patterns:
    - "**/__pycache__/**"
    - "**/.pytest_cache/**"
    - "**/htmlcov/**"
  max_context_tokens: 16000

tools:
  - files/read_file
  - files/write_file
  - files/create_directory
  - git/add
  - testing/run_pytest
```

**Key Features:**
- Write-capable tools for code modification
- Executor context view for implementation focus
- Testing tools for verification
- Project-aware context filtering

---

## Reviewer Actors

### Code Quality & Standards Reviewer

**Purpose:** Reviews changes for quality, standards compliance, and correctness.

```yaml
name: reviewers/quality_gate
type: llm
description: Reviews code changes for quality, standards, and correctness
version: "1.0"

provider: openai
model: gpt-4
system_prompt: |
  You are a senior code reviewer and quality expert. Review changes for:

  **Code Quality:**
  - Clean code principles
  - SOLID design patterns
  - DRY (Don't Repeat Yourself)
  - Proper error handling

  **Standards:**
  - Project coding standards
  - Documentation completeness
  - Type hints and static typing
  - Test coverage

  **Correctness:**
  - Logic errors
  - Edge cases
  - Race conditions
  - Security vulnerabilities

  Provide specific, actionable feedback with examples.

context_view: reviewer
memory:
  enabled: true
  max_messages: 40
  max_tokens: 12000

context:
  include_files:
    - "README.md"
    - "CONTRIBUTING.md"
    - "docs/coding_standards.md"
  include_dirs:
    - "src/"
    - "tests/"
    - "docs/"
  max_context_tokens: 24000

tools:
  - files/read_file
  - files/list_directory
  - git/diff
  - testing/run_pytest
  - linting/run_ruff
  - linting/run_pyright
```

**Key Features:**
- Read-only + linting tools
- Reviewer context view
- Large context for thorough review
- Access to coding standards

---

## Estimation Actors

### Structured Estimation Reporter

This actor is intended for the optional `estimation_actor` slot on host
action configurations. It uses `context_view: strategist`, declares
`role_hint: estimation`, and defines `response_format` with an
`EstimationReport` JSON-schema metadata object.

```yaml
name: estimators/effort_reporter
type: llm
description: Estimates effort and cost for proposed changes
version: "1.0"

provider: openai
model: gpt-4
context_view: strategist
role_hint: estimation

system_prompt: |
  You are an effort estimation expert. Given a plan or specification,
  estimate the effort required in terms of:
  - Hours of engineering work
  - Risk level (low / medium / high)
  - Confidence level (0–100%)
  - Key assumptions

  Return your answer as structured JSON matching the EstimationReport schema.

response_format:
  type: json_schema
  schema:
    name: EstimationReport
    schema:
      type: object
      properties:
        estimated_hours: {type: number}
        risk_level:
          type: string
          enum: [low, medium, high]
        confidence_pct: {type: integer}
        assumptions:
          type: array
          items: {type: string}
      required: [estimated_hours, risk_level, confidence_pct, assumptions]

tools:
  - files/read_file
```

---

## Tool-Only Actors

### File Operations Toolkit

**Purpose:** Provides a reusable collection of file operation tools without
LLM interaction.

```yaml
name: utilities/file_ops
type: tool
description: Collection of file system operation tools
version: "1.0"

tools:
  - files/read_file
  - files/write_file
  - files/create_directory
  - files/delete_file
  - files/move_file
  - files/copy_file
  - files/list_directory
```

**Key Features:**
- No LLM required
- Pure tool collection
- Reusable across multiple actors
- Minimal configuration

### Git Operations Toolkit

```yaml
name: utilities/git_ops
type: tool
description: Collection of Git operation tools
version: "1.0"

tools:
  - git/status
  - git/add
  - git/commit
  - git/diff
  - git/log
  - git/branch
```

---

## Validation-Node Actors

### Validation & Linting Actor

**Purpose:** Runs validation checks without modifying code.

```yaml
name: validators/python_checker
type: llm
description: Validates Python code for correctness and style
version: "1.0"

provider: openai
model: gpt-4
system_prompt: |
  You are a validation expert. Your role is to:

  1. Run all configured validators and linters
  2. Analyze the results
  3. Categorize issues by severity
  4. Provide clear explanations of each issue
  5. Suggest specific fixes

  Focus on actionable feedback. Explain WHY something is an issue.

context_view: reviewer
memory:
  enabled: false

context:
  include_files:
    - "pyproject.toml"
    - "ruff.toml"
  include_dirs:
    - "src/"
  max_context_tokens: 8000

tools:
  - files/read_file
  - linting/run_ruff
  - linting/run_pyright
  - testing/run_pytest
  - security/run_bandit
```

**Key Features:**
- Read-only + validation tools
- No memory (stateless validation)
- Reviewer context view
- Security scanning included

---

## Graph Workflows

### Linear Graph: Three-Step Review

**Purpose:** Simple linear workflow with three sequential steps.

```yaml
name: workflows/simple_review
type: graph
description: Linear workflow for code review in three steps
version: "1.0"

provider: openai
model: gpt-4

route:
  nodes:
    - id: analyzer
      type: agent
      name: Code Analyzer
      description: Analyzes code structure and patterns
      config:
        model: gpt-4
        prompt: "Analyze the code structure and identify patterns"
        tools:
          - files/read_file
          - files/list_directory

    - id: reviewer
      type: agent
      name: Code Reviewer
      description: Reviews code for quality issues
      config:
        model: gpt-4
        prompt: "Review code for quality, style, and best practices"
        tools:
          - files/read_file

    - id: reporter
      type: agent
      name: Report Generator
      description: Generates summary report
      config:
        model: gpt-4
        prompt: "Generate a comprehensive review report"
        tools:
          - files/write_file

  edges:
    - from_node: analyzer
      to_node: reviewer
    - from_node: reviewer
      to_node: reporter

  entry_node: analyzer
  exit_nodes:
    - reporter

context_view: reviewer
memory:
  enabled: true
  max_messages: 50
  max_tokens: 16000
```

---

### Complex Graph: Test-Driven Development

**Purpose:** Complex workflow with conditional routing, retry logic, and
subgraph delegation.

```yaml
name: workflows/test_driven_dev
type: graph
description: Test-driven development workflow with automated testing and feedback loops
version: "1.0"

provider: openai
model: gpt-4

route:
  nodes:
    - id: planner
      type: agent
      name: Test Planner
      description: Plans test cases based on requirements
      config:
        model: gpt-4
        prompt: |
          You are a test planning expert. Analyze the requirements and create
          a comprehensive test plan covering unit tests, integration tests,
          and edge cases.
        tools:
          - files/read_file
          - files/list_directory

    - id: test_writer
      type: agent
      name: Test Writer
      description: Writes test cases based on the plan
      config:
        model: gpt-4
        prompt: |
          You are a test writing expert. Write pytest tests based on the plan.
          Follow best practices: descriptive names, docstrings, fixtures,
          and test one thing per test.
        tools:
          - files/write_file
          - files/read_file

    - id: run_tests
      type: tool
      name: Test Runner
      description: Executes pytest test suite
      config:
        tool_name: testing/run_pytest
        parameters:
          verbose: true
          coverage: true

    - id: check_results
      type: conditional
      name: Test Result Checker
      description: Routes based on test pass/fail status
      config:
        conditions:
          - check: "state.get('tests_passed') == True"
            route_to: code_review
          - check: "state.get('tests_passed') == False"
            route_to: implementation_writer

    - id: implementation_writer
      type: agent
      name: Implementation Writer
      description: Writes code to make the tests pass
      config:
        model: gpt-4
        prompt: |
          You are an implementation expert. Write clean, well-documented code
          that makes the failing tests pass. Follow SOLID principles.
        tools:
          - files/write_file
          - files/read_file

    - id: rerun_tests
      type: tool
      name: Test Rerunner
      description: Re-executes tests after implementation
      config:
        tool_name: testing/run_pytest
        parameters:
          verbose: true
          coverage: true

    - id: verify_tests
      type: conditional
      name: Test Verification
      description: Verify tests pass after implementation
      config:
        conditions:
          - check: "state.get('tests_passed') == True"
            route_to: code_review
          - check: "state.get('tests_passed') == False and state.get('retry_count', 0) < 3"
            route_to: debug_failures
          - check: "state.get('tests_passed') == False and state.get('retry_count', 0) >= 3"
            route_to: escalate

    - id: debug_failures
      type: agent
      name: Debugger
      description: Analyzes and fixes test failures
      config:
        model: gpt-4
        prompt: |
          You are a debugging expert. Analyze the test failures and fix the
          implementation. Look for logic errors, edge cases, type mismatches,
          and missing error handling.
        tools:
          - files/read_file
          - files/write_file

    - id: code_review
      type: subgraph
      name: Code Reviewer
      description: Runs code review workflow
      actor_ref: assistants/code_reviewer

    - id: escalate
      type: tool
      name: Escalation Handler
      description: Escalates persistent failures
      config:
        tool_name: notifications/send_alert
        parameters:
          channel: engineering
          priority: high

  edges:
    - from_node: planner
      to_node: test_writer
    - from_node: test_writer
      to_node: run_tests
    - from_node: run_tests
      to_node: check_results
    - from_node: implementation_writer
      to_node: rerun_tests
    - from_node: rerun_tests
      to_node: verify_tests
    - from_node: debug_failures
      to_node: rerun_tests

  entry_node: planner
  exit_nodes:
    - code_review
    - escalate

context_view: strategist
memory:
  enabled: true
  max_messages: 100
  max_tokens: 16000
  summarize_old: true

context:
  include_files:
    - "README.md"
    - "requirements.txt"
    - "pyproject.toml"
  include_dirs:
    - "src/"
    - "tests/"
  exclude_patterns:
    - "**/__pycache__/**"
    - "*.pyc"
    - "**/.pytest_cache/**"
    - "**/htmlcov/**"
  max_context_tokens: 32000

env_vars:
  PYTEST_ARGS: --verbose --cov --cov-report=html
  MAX_RETRIES: "3"
```

**Key Features:**
- **Conditional routing** based on test results
- **Retry logic** with configurable max attempts
- **Subgraph invocation** for code review via `actor_ref`
- **Escalation path** for persistent failures
- **Tool nodes** for test execution
- **Multiple exit points** (success or escalation)

---

## Hierarchical Actor Graphs

### Graph with Subgraph: Multi-Level Planning

**Purpose:** Demonstrates hierarchical composition with nested subgraphs.

```yaml
name: workflows/hierarchical_planner
type: graph
description: Multi-level planning with strategic and tactical subgraphs
version: "1.0"

provider: openai
model: gpt-4

route:
  nodes:
    - id: strategic_planner
      type: agent
      name: Strategic Planner
      description: High-level goal decomposition
      config:
        model: gpt-4
        prompt: |
          You are a strategic planner. Break down the high-level goal into
          major phases. For each phase, define success criteria and
          dependencies.
        tools:
          - files/read_file

    - id: tactical_planning
      type: subgraph
      name: Tactical Planner
      description: Detailed task planning for each phase
      actor_ref: strategists/task_planner

    - id: execution_coordinator
      type: agent
      name: Execution Coordinator
      description: Coordinates parallel task execution
      config:
        model: gpt-4
        prompt: |
          You are an execution coordinator. Identify which tasks can run
          in parallel and which have dependencies. Create execution plan.
        tools:
          - files/read_file

    - id: task_executor
      type: subgraph
      name: Task Executor
      description: Executes individual tasks
      actor_ref: executors/code_writer

    - id: results_aggregator
      type: agent
      name: Results Aggregator
      description: Collects and summarizes results
      config:
        model: gpt-4
        prompt: |
          Aggregate results from all task executions. Identify successes,
          failures, and any issues that need attention.
        tools:
          - files/read_file
          - files/write_file

    - id: quality_review
      type: subgraph
      name: Quality Reviewer
      description: Comprehensive quality review
      actor_ref: reviewers/quality_gate

  edges:
    - from_node: strategic_planner
      to_node: tactical_planning
    - from_node: tactical_planning
      to_node: execution_coordinator
    - from_node: execution_coordinator
      to_node: task_executor
    - from_node: task_executor
      to_node: results_aggregator
    - from_node: results_aggregator
      to_node: quality_review

  entry_node: strategic_planner
  exit_nodes:
    - quality_review

context_view: strategist
memory:
  enabled: true
  max_messages: 200
  max_tokens: 32000
  summarize_old: true

context:
  include_files:
    - "README.md"
    - "ARCHITECTURE.md"
  include_dirs:
    - "src/"
    - "docs/"
    - "tests/"
  max_context_tokens: 64000
```

**Key Features:**
- **Three levels of hierarchy**: Strategic → Tactical → Execution
- **Subgraph composition**: Each level invokes specialized actors via `actor_ref`
- **Large context window**: Supports complex multi-level planning

---

### Multi-Level Planner/Executor Graph

**Purpose:** Separate planning and execution phases with feedback loops.

```yaml
name: workflows/planner_executor_loop
type: graph
description: Iterative planning and execution with feedback
version: "1.0"

provider: openai
model: gpt-4

route:
  nodes:
    - id: requirements_analyzer
      type: agent
      name: Requirements Analyzer
      description: Analyzes and clarifies requirements
      config:
        model: gpt-4
        prompt: "Analyze requirements and identify ambiguities"
        tools:
          - files/read_file

    - id: plan_generator
      type: subgraph
      name: Plan Generator
      description: Generates detailed execution plan
      actor_ref: strategists/task_planner

    - id: executor_pool
      type: subgraph
      name: Executor Pool
      description: Parallel task execution
      actor_ref: executors/code_writer

    - id: validator
      type: subgraph
      name: Validator
      description: Validates execution results
      actor_ref: validators/python_checker

    - id: validation_check
      type: conditional
      name: Validation Check
      description: Decides next action based on validation
      config:
        conditions:
          - check: "state.get('validation_passed') == True"
            route_to: final_review
          - check: "state.get('validation_passed') == False and state.get('iteration', 0) < 3"
            route_to: issue_analyzer
          - check: "state.get('validation_passed') == False and state.get('iteration', 0) >= 3"
            route_to: escalate_to_human

    - id: issue_analyzer
      type: agent
      name: Issue Analyzer
      description: Analyzes validation failures
      config:
        model: gpt-4
        prompt: "Analyze validation failures and suggest fixes"
        tools:
          - files/read_file

    - id: replanner
      type: subgraph
      name: Replanner
      description: Creates corrective plan
      actor_ref: strategists/task_planner

    - id: final_review
      type: subgraph
      name: Final Reviewer
      description: Comprehensive final review
      actor_ref: reviewers/quality_gate

    - id: escalate_to_human
      type: tool
      name: Human Escalation
      description: Escalates to human intervention
      config:
        tool_name: notifications/send_alert
        parameters:
          priority: high

  edges:
    - from_node: requirements_analyzer
      to_node: plan_generator
    - from_node: plan_generator
      to_node: executor_pool
    - from_node: executor_pool
      to_node: validator
    - from_node: validator
      to_node: validation_check
    - from_node: issue_analyzer
      to_node: replanner
    - from_node: replanner
      to_node: executor_pool

  entry_node: requirements_analyzer
  exit_nodes:
    - final_review
    - escalate_to_human

context_view: strategist
memory:
  enabled: true
  max_messages: 150
  max_tokens: 24000
  summarize_old: true
```

**Key Features:**
- **Multi-phase workflow**: Requirements → Plan → Execute → Validate → Review
- **Feedback loop**: Failed validation triggers replanning and re-execution
- **Iteration limiting**: Maximum 3 attempts before human escalation
- **Context preservation**: Memory carries through iterations

---

## Best Practices

### Naming Conventions

**Good:**
- `assistants/code_reviewer`
- `strategists/task_planner`
- `executors/code_writer`
- `workflows/test_driven_dev`

**Avoid:**
- `CodeReviewer` (not namespaced)
- `assistant-1` (not descriptive)
- `my_actor` (ambiguous namespace)

### Context Configuration

- **Strategist actors**: Large context (32k–64k tokens), broad file access
- **Executor actors**: Medium context (16k tokens), focused on implementation
- **Reviewer actors**: Medium-large context (24k tokens), access to standards
- **Validation actors**: Small context (8k tokens), focused on specific checks

### Memory Settings

- **Simple tasks**: Disable memory or use small buffer (10–20 messages)
- **Planning tasks**: Large memory (50–100 messages) with summarization
- **Execution tasks**: Medium memory (20–40 messages)
- **Stateless validators**: Disable memory

### Tool Selection

- **Read-only actors**: Only query tools (read, list, diff, status)
- **Write actors**: Full tool access (read, write, create, delete)
- **Validators**: Read + linting/testing tools only

### Subgraph References

Always use `actor_ref: namespace/name` to reference other actors in
subgraph nodes. Avoid `config.actor_path` (a file-path-based approach
that bypasses the library's compilation and cycle-detection logic).