150 lines
4.8 KiB
Markdown
150 lines
4.8 KiB
Markdown
|
# 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
|
||
|
|
|
||
|
|
```python
|
||
|
|
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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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
|