414 lines
20 KiB
Markdown
414 lines
20 KiB
Markdown
|
# 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.*
|