# 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.*