31026ddcc1
Complete four-pass evolution to production-ready architecture: **Pass 1 → Foundation:** - Tool registry, basic harness, 19 tools - VPS provisioning, Syncthing mesh - Health daemon, systemd services **Pass 2 → Three-House Canon:** - Timmy (Sovereign), Ezra (Archivist), Bezalel (Artificer) - Provenance tracking, artifact-flow discipline - House-aware policy enforcement **Pass 3 → Self-Improvement:** - Pattern database with SQLite backend - Adaptive policies (auto-adjust thresholds) - Predictive execution (success prediction) - Hermes bridge for shortest-loop telemetry - Learning velocity tracking **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) **Allegro Lane Definition:** - Narrowed to: Gitea integration, Hermes bridge, redundancy/failover - Provides: Cloud connectivity, telemetry streaming, issue routing - Does NOT: Make sovereign decisions, authenticate as Timmy **Files:** - v3/: Intelligence engine, adaptive harness, Hermes bridge - v4/: Unified API, production harness, final architecture Total: ~25KB architecture documentation + production code
20 KiB
20 KiB
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
# 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
# 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:
/healthendpoint 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
# 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
cd /opt/uni-wizard
pip install -e .
systemctl enable uni-wizard
systemctl start uni-wizard
2. Configure Houses
# /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
# 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.