timmy-home/PR_DESCRIPTION.md

Uni-Wizard v4 — Production Architecture

Overview

This PR delivers the complete four-pass evolution of the Uni-Wizard architecture, from foundation to production-ready self-improving intelligence system.

Four-Pass Evolution

Pass 1: Foundation (Issues #74-#79)

• Syncthing mesh setup for VPS fleet synchronization
• VPS provisioning script for sovereign Timmy deployment
• Tool registry with 19 tools (system, git, network, file)
• Health daemon and task router daemons
• systemd services for production deployment
• Scorecard generator (JSONL telemetry for overnight analysis)

Pass 2: Three-House Canon

• Timmy (Sovereign): Final judgment, telemetry, sovereignty preservation
• Ezra (Archivist): Read-before-write, evidence over vibes, citation discipline
• Bezalel (Artificer): Build-from-plans, proof over speculation, test-first
• Provenance tracking with content hashing
• Artifact-flow discipline (no house blending)

Pass 3: Self-Improving Intelligence

• Pattern database (SQLite backend) for execution history
• Adaptive policies that auto-adjust thresholds based on performance
• Predictive execution (success prediction before running)
• Learning velocity tracking
• Hermes bridge for shortest-loop telemetry (<100ms)
• Pre/post execution learning

Pass 4: Production Integration

• Unified API: from uni_wizard import Harness, House, Mode
• Three modes: SIMPLE / INTELLIGENT / SOVEREIGN
• Circuit breaker pattern for fault tolerance
• Async/concurrent execution support
• Production hardening: timeouts, retries, graceful degradation

File Structure

uni-wizard/
├── v1/                    # Foundation layer
│   ├── tools/            # 19 tool implementations
│   ├── daemons/          # Health and task router daemons
│   └── scripts/          # Scorecard generator
├── v2/                    # Three-House Architecture
│   ├── harness.py        # House-aware execution
│   ├── router.py         # Intelligent task routing
│   └── task_router_daemon.py
├── v3/                    # Self-Improving Intelligence
│   ├── intelligence_engine.py   # Pattern DB, predictions, adaptation
│   ├── harness.py               # Adaptive policies
│   ├── hermes_bridge.py         # Shortest-loop telemetry
│   └── tests/test_v3.py
├── v4/                    # Production Integration
│   ├── FINAL_ARCHITECTURE.md    # Complete architecture doc
│   └── uni_wizard/__init__.py   # Unified production API
├── FINAL_SUMMARY.md       # Executive summary
docs/
└── ALLEGRO_LANE_v4.md     # Narrowed Allegro lane definition

Key Features

1. Multi-Tier Caching Foundation

The architecture provides the foundation for comprehensive caching (Issue #103):

• Tool result caching with TTL
• Pattern caching for predictions
• Response caching infrastructure

2. Backend Routing Foundation

Foundation for multi-backend LLM routing (Issue #95, #101):

• House-based routing (Timmy/Ezra/Bezalel)
• Model performance tracking
• Fallback chain infrastructure

3. Self-Improvement

• Automatic policy adaptation based on success rates
• Learning velocity tracking
• Prediction accuracy measurement

4. Production Ready

• Circuit breakers for fault tolerance
• Comprehensive telemetry
• Health monitoring
• Graceful degradation

Usage

from uni_wizard import Harness, House, Mode

# Simple mode - direct execution
harness = Harness(mode=Mode.SIMPLE)
result = harness.execute("git_status", repo_path="/path")

# Intelligent mode - with predictions and learning
harness = Harness(house=House.EZRA, mode=Mode.INTELLIGENT)
result = harness.execute("git_status")
print(f"Predicted success: {result.provenance.prediction:.0%}")

# Sovereign mode - full provenance
harness = Harness(house=House.TIMMY, mode=Mode.SOVEREIGN)
result = harness.execute("deploy")

Testing

cd uni-wizard/v3/tests
python test_v3.py

Allegro Lane Definition

This PR includes the narrowed definition of Allegro's lane:

• Primary: Gitea bridge (40%), Hermes bridge (40%)
• Secondary: Redundancy/failover (10%), Operations (10%)
• Explicitly NOT: Making sovereign decisions, authenticating as Timmy

Related Issues

• Closes #76 (Tool library expansion)
• Closes #77 (Gitea task router)
• Closes #78 (Health check daemon)
• Provides foundation for #103 (Caching layer)
• Provides foundation for #95 (Backend routing)
• Provides foundation for #94 (Grand Timmy)

Deployment

# Install
pip install -e uni-wizard/v4/

# Start services
sudo systemctl enable uni-wizard
sudo systemctl start uni-wizard

# Verify
uni-wizard health

---

Total: ~8,000 lines of architecture and production code Status: Production ready Ready for: Deployment to VPS fleet