# Agent Lightning + Tractatus Integration Demos

This directory contains demonstrations of how Microsoft's Agent Lightning framework can be integrated with the Tractatus governance framework to create high-performing, values-aligned AI systems.

## Core Thesis

**Agent Lightning** and **Tractatus** address fundamentally different problems:

- **Agent Lightning**: *"How to do this task better?"* (Performance optimization through RL)
- **Tractatus**: *"Should this decision be made at all?"* (Governance and values alignment)

**Together**, they create AI systems that are both:
- **High-performing** (optimized by AL)
- **Values-aligned** (governed by Tractatus)

## Demo Progression

### Demo 1: Basic Optimization (AL Standalone)
**Purpose**: Show Agent Lightning optimization without governance
**Key Learning**: AL excels at performance optimization
**Files**: `demo1-basic-optimization/`

### Demo 2: Governed Agent (AL + Tractatus) ⭐
**Purpose**: Show Tractatus governing AL-optimized agents
**Key Learning**: Governance layer prevents values-misaligned decisions
**Files**: `demo2-governed-agent/`
**This is the killer demo** - shows complementarity

### Demo 3: Full-Stack Production (Enterprise-Ready)
**Purpose**: Production-ready AI system with full observability
**Key Learning**: Real-world deployment architecture
**Files**: `demo3-full-stack/`

## Architecture

```
┌──────────────────────────────────────────────────────────┐
│ QUESTION: Should this decision be made at all?           │
│ FRAMEWORK: Tractatus (Governance Layer)                  │
│ FOCUS: Values alignment, human agency, pluralism         │
│ ✓ BoundaryEnforcer - blocks values decisions             │
│ ✓ PluralisticDeliberator - multi-stakeholder input       │
│ ✓ CrossReferenceValidator - instruction adherence        │
└──────────────────────────────────────────────────────────┘
                           ↓
                     [Approved Task]
                           ↓
┌──────────────────────────────────────────────────────────┐
│ QUESTION: How to do this task better?                    │
│ FRAMEWORK: Agent Lightning (Performance Layer)           │
│ FOCUS: Task success, efficiency, optimization            │
│ ✓ RL-based optimization                                  │
│ ✓ Training-agent disaggregation                          │
│ ✓ Framework-agnostic integration                         │
└──────────────────────────────────────────────────────────┘
                           ↓
                    [Optimized Execution]
```

## Prerequisites

### Agent Lightning
```bash
cd ~/projects/agent-lightning
source venv/bin/activate
pip install -e .
```

### Tractatus
```bash
cd ~/projects/tractatus
npm install
```

### Python Dependencies (Each Demo)
```bash
cd demo1-basic-optimization/
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

## Running Demos

### Demo 1: Basic Optimization
```bash
cd demo1-basic-optimization/
source venv/bin/activate
python task_optimizer.py
```

### Demo 2: Governed Agent ⭐
```bash
cd demo2-governed-agent/
source venv/bin/activate
python governed_agent.py
```

### Demo 3: Full-Stack
```bash
cd demo3-full-stack/
source venv/bin/activate
python main.py
```

## Use Cases

These demos support three strategic channels:

### Channel A: Discord Community
- Share governed agent demo in AL Discord
- Show how Tractatus complements AL
- Propose governance as a contributed feature

### Channel B: Academic Publication
- Paper: "Complementary Layers in AI Systems: Governance + Performance"
- Use demos as empirical evidence
- Target: NeurIPS workshop, IEEE, AAAI

### Channel C: Public Demonstrations
- Interactive demos at agenticgovernance.digital
- Show live governance intervention
- Educational content for AI safety community

## Documentation

- **Integration Guide**: `~/projects/tractatus/docs/integrations/agent-lightning.md`
- **API Reference**: `~/projects/tractatus/docs/api/`
- **Research Papers**: `~/projects/tractatus/research/papers/`

## Contact

- **Project**: Tractatus Framework
- **Author**: John Stroh
- **Website**: https://agenticgovernance.digital
- **Purpose**: Preserve human agency over values decisions with plural values context

## License

- **Agent Lightning**: MIT License (Microsoft)
- **Tractatus**: Apache License 2.0
- **Demos**: Apache License 2.0

---

**Last Updated**: November 2, 2025
**Agent Lightning Version**: 0.2.2
**Tractatus Version**: v3.0.2