agent-governance/agents/llm-planner/README.md

# LLM Planner Agent

> Tier 0 Observer agent with LLM-powered plan generation

## Overview

The LLM Planner is a governed Tier 0 Observer agent that uses OpenRouter LLMs to generate implementation plans. It follows strict governance constraints - it can read, analyze, and plan but cannot execute any actions.

## Capabilities

| Capability | Allowed |
|------------|---------|
| Read documentation | Yes |
| Read inventory | Yes |
| Read logs | Yes |
| Generate plans | Yes |
| LLM inference | Yes |
| Execute commands | **No** |
| Modify files | **No** |
| SSH/Terraform/Ansible | **No** |

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                      LLM Planner Agent                          │
├─────────────────────────────────────────────────────────────────┤
│  agent.py           Core agent with LLM integration             │
│  governance.py      DragonflyDB state tracking & revocation     │
│  governed_agent.py  Governance-wrapped agent runner             │
│  monitors.py        Action monitoring and logging               │
└─────────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
    ┌─────────┐        ┌───────────┐        ┌──────────┐
    │OpenRouter│        │DragonflyDB│        │  Ledger  │
    │   LLM    │        │  (State)  │        │ (SQLite) │
    └─────────┘        └───────────┘        └──────────┘
```

## Quick Start

```bash
# Enter the agent directory
cd /opt/agent-governance/agents/llm-planner

# Activate virtual environment
source .venv/bin/activate

# Run the agent
python main.py
```

## Configuration

### Agent Metadata

```python
AGENT_METADATA = {
    "agent_id": "llm-planner-001",
    "agent_role": "observer",
    "tier": 0,
    "confidence_threshold": 0.7,
    "allowed_side_effects": [
        "read_docs",
        "read_inventory",
        "read_logs",
        "generate_plan",
        "llm_inference"
    ],
    "forbidden_actions": [
        "ssh", "create_vm", "modify_vm", "delete_vm",
        "run_ansible", "run_terraform", "write_secrets",
        "execute_shell", "modify_files"
    ]
}
```

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `OPENROUTER_API_KEY` | OpenRouter API key | Yes (or from Vault) |

## Structured Output

All agent outputs follow the Foundation Document schema:

```python
class AgentOutput:
    agent_id: str           # Agent identifier
    version: str            # Agent version
    timestamp: str          # ISO timestamp
    action: str             # Action attempted
    decision: Decision      # EXECUTE, SKIP, ESCALATE, ERROR
    confidence: float       # 0.0 to 1.0
    assumptions: list[str]  # Assumptions made
    dependencies: list[str] # Required dependencies
    side_effects: list      # Side effects declared
    notes_for_humans: str   # Human-readable notes
```

### Decision Types

| Decision | Description |
|----------|-------------|
| `EXECUTE` | Action approved and completed |
| `SKIP` | Action skipped (not applicable) |
| `ESCALATE` | Requires human review |
| `INSUFFICIENT_INFORMATION` | Cannot proceed without more data |
| `ERROR` | Action failed |

## Governance Integration

### State Tracking (DragonflyDB)

```python
from governance import AgentStateTracker

tracker = AgentStateTracker(agent_id="llm-planner-001")
tracker.update_phase(AgentPhase.PLAN)
tracker.update_heartbeat()
```

### Revocation Checking

```python
from governance import is_revoked, check_lock

if is_revoked(agent_id):
    # Agent has been revoked - stop immediately
    sys.exit(1)
```

### Ledger Logging

All actions are logged to SQLite:
- `/opt/agent-governance/ledger/governance.db`

## Modules

### agent.py (410 lines)
Core agent implementation with:
- Task request handling
- LLM inference via OpenRouter
- Structured output generation
- Confidence scoring

### governance.py (750 lines)
Real-time governance via DragonflyDB:
- Agent state tracking
- Phase transitions
- Error budget management
- Revocation handling
- Lock management

### governed_agent.py (380 lines)
Governance-wrapped agent runner:
- Preflight checks
- Action monitoring
- Compliance verification
- Handoff support

### monitors.py (300 lines)
Monitoring infrastructure:
- Action logging
- Metrics collection
- Alert generation

## Example Usage

```python
from agent import LLMPlannerAgent, TaskRequest

# Create agent
agent = LLMPlannerAgent()

# Create task
task = TaskRequest(
    task_type="plan",
    description="Create deployment plan for web service",
    constraints=["No production access", "Use sandbox only"]
)

# Generate plan
output = agent.process_task(task)

print(f"Decision: {output.decision}")
print(f"Confidence: {output.confidence}")
print(f"Plan: {output.notes_for_humans}")
```

## Testing

```bash
# Activate venv
source .venv/bin/activate

# Run agent tests
python -m pytest tests/

# Test import
python -c "from agent import LLMPlannerAgent; print('OK')"
```

## Dependencies

- Python 3.11+
- OpenAI SDK (for OpenRouter compatibility)
- Pydantic (structured outputs)
- Redis (DragonflyDB client)

All dependencies are installed in `.venv/`.

## Architecture Reference

Part of the [Agent Governance System](../../docs/ARCHITECTURE.md).

See also:
- [Tier 0 Agent](../tier0-agent) - Base observer agent
- [LLM Planner TS](../llm-planner-ts) - TypeScript variant

---
*Last updated: 2026-01-24*