tractatus/demos/agent-lightning-integration/demo2-governed-agent/README.md

# Demo 2: Governed Agent (Agent Lightning + Tractatus) ⭐

## Purpose

**This is the killer demo** that demonstrates the core thesis:

> Agent Lightning optimizes **HOW** to do tasks (performance)
> Tractatus governs **WHETHER** tasks should be done (values)

This demo shows:
- AL-optimized agent performance
- Tractatus governance layer preventing values-misaligned decisions
- **Complementarity**: Both frameworks working together
- Real-world example of governance + performance architecture

## What This Demo Shows

### The Integration ✓
1. **Governance Check First**: Tractatus evaluates whether task should be approved
2. **Optimization Second**: AL optimizes approved tasks
3. **Monitored Execution**: Tractatus monitors for boundary violations
4. **Pluralistic Input**: Multi-stakeholder values considered

### The Difference from Demo 1 ⚠️
| Aspect | Demo 1 (Ungoverned) | Demo 2 (Governed) |
|--------|---------------------|-------------------|
| Performance | High (94% engagement) | High (89% engagement) |
| Values Alignment | ✗ (clickbait) | ✓ (editorial guidelines) |
| Stakeholder Input | ✗ None | ✓ Multi-stakeholder |
| Harm Prevention | ✗ Not checked | ✓ Assessed |
| Decision Authority | AI decides | Human decides |

**Key Insight**: Small performance trade-off (5%) for large values gain (governance)

## Example Scenario

**Task**: "Optimize content for maximum engagement"

**Without Governance** (Demo 1):
```
User Request → AL Optimize → Clickbait Headlines ✗
Result: 94% engagement, but violates editorial guidelines
```

**With Governance** (Demo 2):
```
User Request
    ↓
Tractatus: "Does this require values decision?"
    ↓
[YES] → Get stakeholder input
    ↓
Stakeholders: "No clickbait, maintain accuracy"
    ↓
Tractatus: Approve with constraints
    ↓
AL: Optimize within constraints
    ↓
Result: 89% engagement, editorial guidelines maintained ✓
```

## Architecture

```
┌─────────────────────────────────────────────┐
│         TRACTATUS GOVERNANCE LAYER          │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │   BoundaryEnforcer                  │   │
│  │   - Detects values decisions        │   │
│  │   - Requires human approval         │   │
│  └─────────────────────────────────────┘   │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │   PluralisticDeliberator            │   │
│  │   - Gathers stakeholder input       │   │
│  │   - Facilitates values conflicts    │   │
│  └─────────────────────────────────────┘   │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │   CrossReferenceValidator           │   │
│  │   - Enforces constraints            │   │
│  │   - Validates adherence             │   │
│  └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘
                     ↓
              [Approved Task]
                     ↓
┌─────────────────────────────────────────────┐
│      AGENT LIGHTNING PERFORMANCE LAYER      │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │   AgentLightningClient              │   │
│  │   - Optimizes strategy (RL)         │   │
│  │   - Learns from feedback            │   │
│  │   - Improves performance            │   │
│  └─────────────────────────────────────┘   │
│                                             │
│           [Within Constraints]              │
└─────────────────────────────────────────────┘
                     ↓
           [Optimized Execution]
```

## Running the Demo

### Setup
```bash
cd ~/projects/tractatus/demos/agent-lightning-integration/demo2-governed-agent/
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### Run
```bash
python governed_agent.py
```

### Expected Output
```
Governed Agent Demo (AL + Tractatus)
====================================

Task: Optimize content for engagement
Content: "The Future of AI Safety"

┌─ Tractatus Governance Check ─────────────────┐
│ Analyzing task for values decisions...       │
│                                               │
│ ✓ Detected: Content optimization             │
│ ⚠️  Requires values decision (editorial)      │
│                                               │
│ Initiating stakeholder deliberation...       │
└───────────────────────────────────────────────┘

┌─ Pluralistic Deliberation ───────────────────┐
│ Stakeholder 1 (Editor):                      │
│   "No clickbait. Maintain accuracy."         │
│                                               │
│ Stakeholder 2 (User Rep):                    │
│   "Clear headlines. No misleading."          │
│                                               │
│ Stakeholder 3 (Safety):                      │
│   "Prevent harm. Check sources."             │
│                                               │
│ Consensus: Approved with constraints ✓       │
└───────────────────────────────────────────────┘

┌─ Constraints Established ────────────────────┐
│ • No clickbait patterns                      │
│ • Maintain factual accuracy                  │
│ • Verify all claims                          │
│ • Editorial guidelines required              │
└───────────────────────────────────────────────┘

┌─ Agent Lightning Optimization ───────────────┐
│ Training agent within constraints...         │
│                                               │
│ Round 1: Engagement = 45% ✓                  │
│ Round 2: Engagement = 62% ✓                  │
│ Round 3: Engagement = 77% ✓                  │
│ Round 4: Engagement = 85% ✓                  │
│ Round 5: Engagement = 89% ✓                  │
│                                               │
│ ✓ All rounds passed governance checks        │
└───────────────────────────────────────────────┘

Results:
  Final engagement: 89% ✓
  Governance checks: 5/5 passed ✓
  Constraints violated: 0 ✓
  Values-aligned: YES ✓

Comparison with Demo 1 (Ungoverned):
  Demo 1 engagement: 94%
  Demo 2 engagement: 89%
  Performance cost: -5% (acceptable)

  Demo 1 values: ✗ (clickbait, guidelines violated)
  Demo 2 values: ✓ (accurate, guidelines maintained)
  Values gain: Significant ✓

✓ Governed optimization complete!
  - High performance (89%)
  - Values-aligned ✓
  - Stakeholder input incorporated ✓
  - Human agency preserved ✓
```

## Key Code Patterns

### 1. Governance Check Before Optimization
```python
from tractatus import BoundaryEnforcer, PluralisticDeliberator

# Initialize governance
enforcer = BoundaryEnforcer()
deliberator = PluralisticDeliberator()

# Check if task requires governance
if enforcer.requires_human_approval(task):
    # Get stakeholder input
    decision = deliberator.deliberate(
        task=task,
        stakeholders=["editor", "user_rep", "safety"]
    )

    if not decision.approved:
        return "Task blocked by governance"

    # Extract constraints
    constraints = decision.constraints
else:
    constraints = None
```

### 2. AL Optimization Within Constraints
```python
from agentlightning import AgentLightningClient

# Initialize AL
al_client = AgentLightningClient()

# Optimize with constraints
result = al_client.optimize(
    task=task,
    constraints=constraints  # Tractatus constraints
)
```

### 3. Continuous Monitoring
```python
# Monitor execution for violations
for step in result.execution_steps:
    if not enforcer.validate_step(step, constraints):
        # Governance violation detected!
        return enforcer.halt_execution(reason="Constraint violated")
```

## Comparison: Demo 1 vs Demo 2

### Performance Metrics
```
Metric              | Demo 1 | Demo 2 | Delta
--------------------|--------|--------|-------
Engagement          |   94%  |   89%  |  -5%
Training Time       |  2.3s  |  3.1s  | +0.8s
Task Success        |  100%  |  100%  |   0%
```

### Governance Metrics
```
Metric                      | Demo 1 | Demo 2
----------------------------|--------|--------
Values alignment            |   ✗    |   ✓
Stakeholder input           |   ✗    |   ✓
Boundary checks             |   ✗    |   ✓
Harm assessment             |   ✗    |   ✓
Editorial guidelines        |   ✗    |   ✓
Human agency preserved      |   ✗    |   ✓
```

### The Trade-off
- **Performance cost**: 5% (acceptable)
- **Values gain**: Complete governance coverage (essential)

**Conclusion**: Small performance trade-off for large values gain demonstrates complementarity.

## Why This Matters

### For the AI Community
- Shows governance + performance can coexist
- Demonstrates practical integration architecture
- Provides reusable patterns

### For Agent Lightning Users
- Governance doesn't break AL optimization
- Minimal performance impact
- Easy integration (constraint passing)

### For Tractatus Users
- AL provides performance layer Tractatus lacks
- RL optimization improves outcomes
- Proves framework complementarity

## Next Steps

→ **Demo 3**: See full production architecture
→ **Documentation**: Integration guide at tractatus/docs/integrations/
→ **Discord**: Share with Agent Lightning community
→ **Academic**: Use in paper on complementary frameworks

## Files

- `governed_agent.py` - Main governed agent implementation
- `tractatus_integration.py` - Governance layer integration
- `config/governance_rules.json` - Tractatus rules configuration
- `requirements.txt` - Python dependencies
- `README.md` - This file

---

**Last Updated**: November 2, 2025
**Purpose**: Demonstrate AL + Tractatus complementarity
**Status**: ⭐ Killer Demo - Ready for Community