# Reference Implementations

This directory contains simplified reference implementations of the three core components described in the "Deep & Difficult" problem statement. These are educational implementations that demonstrate the key concepts.

## Overview

The self-correcting agent kernel implements a **Dual-Loop Architecture** that goes beyond simple error catching:

### The Three Core Components

#### 1. **Completeness Auditor** (`auditor.py`)
**Problem:** Agents give up with "No data found" when data actually exists.

**Solution:** Detects "soft failures" (laziness) through heuristic analysis:
- Checks for verbal resignation signals ("I cannot", "I'm sorry", "no data found")
- Detects empty tool outputs that suggest incomplete searches
- Flags responses that need intervention from a teacher model

```python
from agent_kernel import SimpleCompletenessAuditor

auditor = SimpleCompletenessAuditor()
agent_response = "I cannot find any logs for that error."
needs_intervention = auditor.audit_response(agent_response, None)
# Returns: True (soft failure detected)
```

#### 2. **Shadow Teacher** (`teacher.py`)
**Problem:** When agents fail, we need a "patch" that fixes the root cause, not just a retry.

**Solution:** Uses a stronger "teacher model" (e.g., o1-preview, Claude Sonnet) to diagnose WHY the agent failed:
- Analyzes the agent's reasoning chain
- Identifies cognitive glitches (laziness, hallucination, skill gaps)
- Generates specific lesson patches to prevent recurrence

```python
from agent_kernel import diagnose_failure
import asyncio

diagnosis = asyncio.run(diagnose_failure(
    prompt="Find logs for error 500",
    failed_response="No logs found.",
    tool_trace="search_logs(error='500')"
))
# Returns: {"cause": "...", "lesson_patch": "..."}
```

#### 3. **Memory Manager** (`memory_manager.py`)
**Problem:** Accumulated lessons cause unbounded prompt growth (context bloat).

**Solution:** Semantic purge through lesson taxonomy:
- **Type A (SYNTAX)**: Model-specific issues, purged on model upgrade
- **Type B (BUSINESS)**: Domain knowledge, retained permanently  
- **Type C (ONE_OFF)**: Transient issues, deleted immediately

```python
from agent_kernel import MemoryManager, LessonType

manager = MemoryManager()

# Add lessons with lifecycle tags
manager.add_lesson("Output JSON format", LessonType.SYNTAX)
manager.add_lesson("Fiscal year starts Oct", LessonType.BUSINESS)

# On model upgrade, purge Type A lessons
result = manager.run_upgrade_purge("gpt-5")
# Removes syntax lessons, keeps business lessons
```

## The Gap Analysis

| Component | Before (MVP) | After (Anthropic/OpenAI Standard) |
|-----------|-------------|-----------------------------------|
| **Failure Detection** | Catches Exceptions only | Detects "Soft Failures" (laziness, empty results) |
| **Correction** | Generic retry | Teacher model diagnoses WHY and generates specific patch |
| **Memory** | Appends all lessons | Semantic taxonomy: purge syntax, keep business context |
| **Loop** | Linear (one-time) | Circular OODA: output becomes next input |

## Production Implementations

These reference implementations demonstrate the core concepts. The production implementations provide:

- **`completeness_auditor.py`**: Full differential auditing with teacher model integration
- **`semantic_purge.py`**: Sophisticated patch classification and lifecycle management
- **`analyzer.py`**: Deep cognitive diagnosis with failure trace analysis

## Running the Demo

```bash
python examples/reference_demo.py
```

This demonstrates:
1. Soft failure detection by the auditor
2. Diagnosis by the shadow teacher
3. Lesson lifecycle management
4. Complete integration workflow

## Testing

```bash
# Test reference implementations
pytest tests/test_reference_implementations.py -v

# Test all components
pytest tests/ -v
```

## Key Insights

### 1. Completeness Auditor
- Not every interaction needs auditing (too expensive)
- Only audit "give-up signals" (differential auditing)
- Teacher model verifies if data actually exists

### 2. Shadow Teacher
- Use expensive reasoning models (o1, Sonnet) ONLY on failures
- Identify cognitive glitches, not just symptoms
- Generate actionable lesson patches, not generic advice

### 3. Memory Manager
- Context bloat is inevitable without lifecycle management
- Syntax lessons decay with model improvements
- Business lessons are permanent world truths
- Achieves 40-60% token reduction on upgrades

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    DUAL-LOOP ARCHITECTURE                    │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  LOOP 1: Runtime Safety (Constraint Engine)                  │
│  ┌────────────────────────────────────────────────┐          │
│  │  • Block unsafe actions                         │          │
│  │  • Enforce policies                             │          │
│  │  • Immediate intervention                       │          │
│  └────────────────────────────────────────────────┘          │
│                                                               │
│  LOOP 2: Offline Alignment (Alignment Engine)                │
│  ┌────────────────────────────────────────────────┐          │
│  │  • Completeness Auditor (detect laziness)       │          │
│  │  • Shadow Teacher (diagnose failures)           │          │
│  │  • Memory Manager (semantic purge)              │          │
│  │  • Circular feedback: output → next input       │          │
│  └────────────────────────────────────────────────┘          │
│                                                               │
└─────────────────────────────────────────────────────────────┘
```

## Benefits

1. **Sustained Performance**: Agents work reliably for 6+ months
2. **Cost Optimization**: 40-60% context reduction on model upgrades
3. **Quality Improvement**: Teacher model catches subtle failures
4. **Scalability**: Differential auditing keeps costs manageable

## See Also

- [Dual-Loop Architecture](./Dual-Loop-Architecture.md) - Detailed architecture
- [Three Failure Types](./Three-Failure-Types.md) - Failure taxonomy
- [Enhanced Features](./Enhanced-Features.md) - Advanced features
