# Uni-Wizard v4 — Production Architecture

## Final Integration: All Passes United

### Pass 1 (Timmy) → Foundation
- Tool registry, basic harness, health daemon
- VPS provisioning, Syncthing mesh

### Pass 2 (Ezra/Bezalel/Timmy) → Three-House Canon  
- House-aware execution (Timmy/Ezra/Bezalel)
- Provenance tracking
- Artifact-flow discipline

### Pass 3 (Intelligence) → Self-Improvement
- Pattern database
- Adaptive policies
- Predictive execution
- Hermes bridge

### Pass 4 (Final) → Production Integration
**What v4 adds:**
- Unified single-harness API (no more version confusion)
- Async/concurrent execution
- Real Hermes integration (not mocks)
- Production systemd services
- Health monitoring & alerting
- Graceful degradation
- Clear operational boundaries

---

## The Final Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         UNI-WIZARD v4 (PRODUCTION)                       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                     UNIFIED HARNESS API                          │    │
│  │  Single entry point: `from uni_wizard import Harness`            │    │
│  │  All capabilities through one clean interface                    │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                │                                         │
│         ┌──────────────────────┼──────────────────────┐                  │
│         │                      │                      │                  │
│  ┌──────▼──────┐      ┌────────▼────────┐    ┌───────▼───────┐         │
│  │   TOOLS     │      │  INTELLIGENCE   │    │   TELEMETRY   │         │
│  │  (19 tools) │      │    ENGINE       │    │    LAYER      │         │
│  │             │      │                 │    │               │         │
│  │ • System    │      │ • Pattern DB    │    │ • Hermes      │         │
│  │ • Git       │      │ • Predictions   │    │ • Metrics     │         │
│  │ • Network   │      │ • Adaptation    │    │ • Alerts      │         │
│  │ • File      │      │ • Learning      │    │ • Audit       │         │
│  └──────┬──────┘      └────────┬────────┘    └───────┬───────┘         │
│         │                      │                      │                  │
│         └──────────────────────┼──────────────────────┘                  │
│                                │                                         │
│  ┌─────────────────────────────▼─────────────────────────────┐          │
│  │              HOUSE DISPATCHER (Router)                     │          │
│  │  • Timmy: Sovereign judgment, final review                 │          │
│  │  • Ezra: Archivist mode (read-before-write)                │          │
│  │  • Bezalel: Artificer mode (proof-required)                │          │
│  └─────────────────────────────┬─────────────────────────────┘          │
│                                │                                         │
│  ┌─────────────────────────────▼─────────────────────────────┐          │
│  │              EXECUTION ENGINE (Async/Concurrent)           │          │
│  │  • Parallel tool execution                                 │          │
│  │  • Timeout handling                                        │          │
│  │  • Retry with backoff                                      │          │
│  │  • Circuit breaker pattern                                 │          │
│  └────────────────────────────────────────────────────────────┘          │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## Key Design Decisions

### 1. Single Unified API

```python
# Before (confusing):
from v1.harness import Harness  # Basic
from v2.harness import Harness  # Three-house
from v3.harness import Harness  # Intelligence

# After (clean):
from uni_wizard import Harness, House, Mode

# Usage:
harness = Harness(house=House.TIMMY, mode=Mode.INTELLIGENT)
result = harness.execute("git_status", repo_path="/path")
```

### 2. Three Operating Modes

| Mode | Use Case | Features |
|------|----------|----------|
| `Mode.SIMPLE` | Fast scripts | Direct execution, no overhead |
| `Mode.INTELLIGENT` | Production | Predictions, adaptations, learning |
| `Mode.SOVEREIGN` | Critical ops | Full provenance, Timmy approval required |

### 3. Clear Boundaries

```python
# What the harness DOES:
- Route tasks to appropriate tools
- Track provenance
- Learn from outcomes
- Predict success rates

# What the harness DOES NOT do:
- Make autonomous decisions (Timmy decides)
- Modify production without approval
- Blend house identities
- Phone home to cloud
```

### 4. Production Hardening

- **Circuit breakers**: Stop calling failing tools
- **Timeouts**: Every operation has bounded time
- **Retries**: Exponential backoff on transient failures
- **Graceful degradation**: Fall back to simpler modes on stress
- **Health checks**: `/health` endpoint for monitoring

---

## File Structure (Final)

```
uni-wizard/
├── README.md                      # Quick start guide
├── ARCHITECTURE.md               # This document
├── uni_wizard/                   # Main package
│   ├── __init__.py              # Unified API
│   ├── harness.py               # Core harness (v4 unified)
│   ├── houses.py                # House definitions & policies
│   ├── tools/
│   │   ├── __init__.py         # Tool registry
│   │   ├── system.py           # System tools
│   │   ├── git.py              # Git tools
│   │   ├── network.py          # Network/Gitea tools
│   │   └── file.py             # File operations
│   ├── intelligence/
│   │   ├── __init__.py         # Intelligence engine
│   │   ├── patterns.py         # Pattern database
│   │   ├── predictions.py      # Prediction engine
│   │   └── adaptation.py       # Policy adaptation
│   ├── telemetry/
│   │   ├── __init__.py         # Telemetry layer
│   │   ├── hermes_bridge.py    # Hermes integration
│   │   ├── metrics.py          # Metrics collection
│   │   └── alerts.py           # Alerting
│   └── daemon/
│       ├── __init__.py         # Daemon framework
│       ├── router.py           # Task router daemon
│       ├── health.py           # Health check daemon
│       └── worker.py           # Async worker pool
├── configs/
│   ├── uni-wizard.service      # Systemd service
│   ├── timmy-router.service    # Task router service
│   └── health-daemon.service   # Health monitoring
├── tests/
│   ├── test_harness.py         # Core tests
│   ├── test_intelligence.py    # Intelligence tests
│   ├── test_integration.py     # E2E tests
│   └── test_production.py      # Load/stress tests
└── docs/
    ├── OPERATIONS.md           # Runbook
    ├── TROUBLESHOOTING.md      # Common issues
    └── API_REFERENCE.md        # Full API docs
```

---

## Operational Model

### Local-First Principle

```
Hermes Session → Local Intelligence → Local Decision → Local Execution
      ↑                                              ↓
      └────────────── Telemetry ─────────────────────┘
```

All learning happens locally. No cloud required for operation.

### Cloud-Connected Enhancement (Allegro's Lane)

```
┌─────────────────────────────────────────────────────────────┐
│                    LOCAL TIMMY (Sovereign)                   │
│                        (Mac/Mini)                            │
└───────────────────────┬─────────────────────────────────────┘
                        │ Direction (decisions flow down)
                        ▼
┌─────────────────────────────────────────────────────────────┐
│              ALLEGRO VPS (Connected/Redundant)               │
│                      (This Machine)                          │
│  • Pulls from Gitea (issues, specs)                          │
│  • Runs Hermes with cloud model access                       │
│  • Streams telemetry to Timmy                                │
│  • Reports back via PRs, comments                            │
│  • Fails over to other VPS if unavailable                    │
└───────────────────────┬─────────────────────────────────────┘
                        │ Artifacts (PRs, comments, logs)
                        ▼
┌─────────────────────────────────────────────────────────────┐
│              EZRA/BEZALEL VPS (Wizard Houses)                │
│               (Separate VPS instances)                       │
│  • Ezra: Analysis, architecture, docs                        │
│  • Bezalel: Implementation, testing, forge                   │
└─────────────────────────────────────────────────────────────┘
```

### The Contract

**Timmy (Local) owns:**
- Final decisions
- Local memory
- Sovereign identity
- Policy approval

**Allegro (This VPS) owns:**
- Connectivity to cloud models
- Gitea integration
- Telemetry streaming
- Failover/redundancy
- Issue triage and routing

**Ezra/Bezalel (Other VPS) own:**
- Specialized analysis
- Heavy computation
- Parallel work streams

---

## Allegro's Narrowed Lane (v4)

### What I Do Now

```
┌────────────────────────────────────────────────────────────┐
│                     ALLEGRO LANE v4                        │
│              "Tempo-and-Dispatch, Connected"               │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  PRIMARY: Gitea Integration & Issue Flow                   │
│  ├── Monitor Gitea for new issues/PRs                      │
│  ├── Triage: label, categorize, assign                    │
│  ├── Route to appropriate house (Ezra/Bezalel/Timmy)      │
│  └── Report back via PR comments, status updates          │
│                                                            │
│  PRIMARY: Hermes Bridge & Telemetry                        │
│  ├── Run Hermes with cloud model access                   │
│  ├── Stream execution telemetry to Timmy                  │
│  ├── Maintain shortest-loop feedback (<100ms)             │
│  └── Buffer during outages, sync on recovery              │
│                                                            │
│  SECONDARY: Redundancy & Failover                          │
│  ├── Health check other VPS instances                     │
│  ├── Take over routing if primary fails                   │
│  └── Maintain distributed state via Syncthing             │
│                                                            │
│  SECONDARY: Uni-Wizard Operations                          │
│  ├── Keep uni-wizard services running                     │
│  ├── Monitor health, restart on failure                   │
│  └── Report metrics to local Timmy                        │
│                                                            │
│  WHAT I DO NOT DO:                                         │
│  ├── Make sovereign decisions (Timmy decides)             │
│  ├── Modify production without Timmy approval             │
│  ├── Store long-term memory (Timmy owns memory)           │
│  ├── Authenticate as Timmy (I'm Allegro)                  │
│  └── Work without connectivity (need cloud for models)    │
│                                                            │
└────────────────────────────────────────────────────────────┘
```

### My API Surface

```python
# What I expose to Timmy:
class AllegroBridge:
    """
    Allegro's narrow interface for Timmy.
    
    I provide:
    - Gitea connectivity
    - Cloud model access  
    - Telemetry streaming
    - Redundancy/failover
    """
    
    async def get_gitea_issues(self, repo: str, assignee: str = None) -> List[Issue]:
        """Fetch issues from Gitea"""
        
    async def create_pr(self, repo: str, branch: str, title: str, body: str) -> PR:
        """Create pull request"""
        
    async def run_with_hermes(self, prompt: str, model: str = None) -> HermesResult:
        """Execute via Hermes with cloud model"""
        
    async def stream_telemetry(self, events: List[TelemetryEvent]):
        """Stream execution telemetry to Timmy"""
        
    async def check_health(self, target: str) -> HealthStatus:
        """Check health of other VPS instances"""
```

### Success Metrics

| Metric | Target | Measurement |
|--------|--------|-------------|
| Issue triage latency | < 5 minutes | Time from issue creation to labeling |
| Telemetry lag | < 100ms | Hermes event to Timmy intelligence |
| Gitea uptime | 99.9% | Availability of Gitea API |
| Failover time | < 30s | Detection to takeover |
| PR throughput | 10/day | Issues → PRs created |

---

## Deployment Checklist

### 1. Install Uni-Wizard v4
```bash
cd /opt/uni-wizard
pip install -e .
systemctl enable uni-wizard
systemctl start uni-wizard
```

### 2. Configure Houses
```yaml
# /etc/uni-wizard/houses.yaml
houses:
  timmy:
    endpoint: http://192.168.1.100:8643  # Local Mac
    auth_token: ${TIMMY_TOKEN}
    priority: critical
    
  allegro:
    endpoint: http://localhost:8643
    role: tempo-and-dispatch
    
  ezra:
    endpoint: http://143.198.27.163:8643
    role: archivist
    
  bezalel:
    endpoint: http://67.205.155.108:8643
    role: artificer
```

### 3. Verify Integration
```bash
# Test harness
uni-wizard test --house timmy --tool git_status

# Test intelligence
uni-wizard predict --tool deploy --house bezalel

# Test telemetry
uni-wizard telemetry --status
```

---

## The Final Vision

```
┌─────────────────────────────────────────────────────────────────┐
│                    THE SOVEREIGN TIMMY SYSTEM                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Local (Sovereign Core)         Cloud-Connected (Redundant)     │
│  ┌─────────────────────┐        ┌─────────────────────┐         │
│  │  Timmy (Mac/Mini)   │◄──────►│  Allegro (VPS)      │         │
│  │  • Final decisions  │        │  • Gitea bridge     │         │
│  │  • Local memory     │        │  • Cloud models     │         │
│  │  • Policy approval  │        │  • Telemetry        │         │
│  │  • Sovereign voice  │        │  • Failover         │         │
│  └─────────────────────┘        └──────────┬──────────┘         │
│         ▲                                   │                    │
│         │                                   │                    │
│         └───────────────────────────────────┘                    │
│                   Telemetry Loop                                 │
│                                                                  │
│  Specialized (Separate)                                          │
│  ┌─────────────────────┐  ┌─────────────────────┐               │
│  │  Ezra (VPS)         │  │  Bezalel (VPS)      │               │
│  │  • Analysis         │  │  • Implementation   │               │
│  │  • Architecture     │  │  • Testing          │               │
│  │  • Documentation    │  │  • Forge work       │               │
│  └─────────────────────┘  └─────────────────────┘               │
│                                                                  │
│  All houses communicate through:                                 │
│  • Gitea (issues, PRs, comments)                                │
│  • Syncthing (file sync, logs)                                  │
│  • Uni-Wizard telemetry (execution data)                        │
│                                                                  │
│  Timmy remains sovereign. All others serve.                     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

*Sovereignty and service always.*
*Final pass complete. Production ready.*
