From c134081f3bbd047662b94c3381755d4a89384cba Mon Sep 17 00:00:00 2001 From: Allegro Date: Mon, 30 Mar 2026 16:46:35 +0000 Subject: [PATCH] [#94] Add quick reference and deployment checklist for production --- docs/DEPLOYMENT_CHECKLIST.md | 197 +++++++++++++++++++++++++++++++ docs/QUICK_REFERENCE.md | 220 +++++++++++++++++++++++++++++++++++ 2 files changed, 417 insertions(+) create mode 100644 docs/DEPLOYMENT_CHECKLIST.md create mode 100644 docs/QUICK_REFERENCE.md diff --git a/docs/DEPLOYMENT_CHECKLIST.md b/docs/DEPLOYMENT_CHECKLIST.md new file mode 100644 index 0000000..fe0d241 --- /dev/null +++ b/docs/DEPLOYMENT_CHECKLIST.md @@ -0,0 +1,197 @@ +# Uni-Wizard v4 — Deployment Checklist + +## Pre-Deployment + +- [ ] VPS provisioned (Ubuntu 22.04 LTS recommended) +- [ ] SSH access configured +- [ ] Firewall rules set (ports 22, 80, 443, 3000, 8643) +- [ ] Domain/DNS configured (optional) +- [ ] SSL certificates ready (optional) + +## Base System + +- [ ] Update system packages + ```bash + sudo apt update && sudo apt upgrade -y + ``` +- [ ] Install base dependencies + ```bash + sudo apt install -y python3 python3-pip python3-venv sqlite3 curl git + ``` +- [ ] Create timmy user + ```bash + sudo useradd -m -s /bin/bash timmy + ``` +- [ ] Configure sudo access (if needed) + +## Gitea Setup + +- [ ] Gitea installed and running +- [ ] Repository created: `Timmy_Foundation/timmy-home` +- [ ] API token generated +- [ ] Webhooks configured (optional) +- [ ] Test API access + ```bash + curl -H "Authorization: token TOKEN" http://localhost:3000/api/v1/user + ``` + +## Uni-Wizard Installation + +- [ ] Clone repository + ```bash + sudo -u timmy git clone http://143.198.27.163:3000/Timmy_Foundation/timmy-home.git /opt/timmy/repo + ``` +- [ ] Run setup script + ```bash + sudo ./scripts/setup-uni-wizard.sh + ``` +- [ ] Verify installation + ```bash + /opt/timmy/venv/bin/python -c "from uni_wizard import Harness; print('OK')" + ``` + +## Configuration + +- [ ] Edit config file + ```bash + sudo nano /opt/timmy/config/uni-wizard.yaml + ``` +- [ ] Set Gitea API token +- [ ] Configure house identity +- [ ] Set log level (INFO for production) +- [ ] Verify config syntax + ```bash + /opt/timmy/venv/bin/python -c "import yaml; yaml.safe_load(open('/opt/timmy/config/uni-wizard.yaml'))" + ``` + +## LLM Setup (if using local inference) + +- [ ] llama.cpp installed +- [ ] Model downloaded (e.g., Hermes-4 14B) +- [ ] Model placed in `/opt/timmy/models/` +- [ ] llama-server configured +- [ ] Test inference + ```bash + curl http://localhost:8080/v1/chat/completions \ + -H "Content-Type: application/json" \ + -d '{"model": "hermes4", "messages": [{"role": "user", "content": "Hello"}]}' + ``` + +## Service Startup + +- [ ] Start Uni-Wizard + ```bash + sudo systemctl start uni-wizard + ``` +- [ ] Start health daemon + ```bash + sudo systemctl start timmy-health + ``` +- [ ] Start task router + ```bash + sudo systemctl start timmy-task-router + ``` +- [ ] Enable auto-start + ```bash + sudo systemctl enable uni-wizard timmy-health timmy-task-router + ``` + +## Verification + +- [ ] Check service status + ```bash + sudo systemctl status uni-wizard + ``` +- [ ] View logs + ```bash + sudo journalctl -u uni-wizard -f + ``` +- [ ] Test health endpoint + ```bash + curl http://localhost:8082/health + ``` +- [ ] Test tool execution + ```bash + /opt/timmy/venv/bin/uni-wizard execute system_info + ``` +- [ ] Verify Gitea polling + ```bash + tail -f /opt/timmy/logs/task-router.log | grep "Polling" + ``` + +## Syncthing Mesh (if using multiple VPS) + +- [ ] Syncthing installed on all nodes +- [ ] Devices paired +- [ ] Folders shared + - `/opt/timmy/logs/` + - `/opt/timmy/data/` +- [ ] Test sync + ```bash + touch /opt/timmy/logs/test && ssh other-vps "ls /opt/timmy/logs/test" + ``` + +## Security + +- [ ] Firewall configured + ```bash + sudo ufw status + ``` +- [ ] Fail2ban installed (optional) +- [ ] Log rotation configured + ```bash + sudo logrotate -d /etc/logrotate.d/uni-wizard + ``` +- [ ] Backup strategy in place +- [ ] Secrets not in git + ```bash + grep -r "password\|token\|secret" /opt/timmy/repo/ + ``` + +## Monitoring + +- [ ] Health checks responding +- [ ] Metrics being collected +- [ ] Alerts configured (optional) +- [ ] Log aggregation setup (optional) + +## Post-Deployment + +- [ ] Document any custom configuration +- [ ] Update runbooks +- [ ] Notify team +- [ ] Schedule first review (1 week) + +## Rollback Plan + +If deployment fails: + +```bash +# Stop services +sudo systemctl stop uni-wizard timmy-health timmy-task-router + +# Disable auto-start +sudo systemctl disable uni-wizard timmy-health timmy-task-router + +# Restore from backup (if available) +# ... + +# Or reset to clean state +sudo rm -rf /opt/timmy/ +sudo userdel timmy +``` + +## Success Criteria + +- [ ] All services running (`systemctl is-active` returns "active") +- [ ] Health endpoint returns 200 +- [ ] Can execute tools via CLI +- [ ] Gitea integration working (issues being polled) +- [ ] Logs being written without errors +- [ ] No critical errors in first 24 hours + +--- + +**Deployed by:** _______________ +**Date:** _______________ +**VPS:** _______________ diff --git a/docs/QUICK_REFERENCE.md b/docs/QUICK_REFERENCE.md new file mode 100644 index 0000000..02b166e --- /dev/null +++ b/docs/QUICK_REFERENCE.md @@ -0,0 +1,220 @@ +# Uni-Wizard v4 — Quick Reference + +## Installation + +```bash +# Run setup script +sudo ./scripts/setup-uni-wizard.sh + +# Or manual install +cd uni-wizard/v4 +pip install -e . +``` + +## Basic Usage + +```python +from uni_wizard import Harness, House, Mode + +# Create harness +harness = Harness(house=House.TIMMY, mode=Mode.INTELLIGENT) + +# Execute tool +result = harness.execute("git_status", repo_path="/path/to/repo") + +# Check prediction +print(f"Predicted success: {result.provenance.prediction:.0%}") + +# Get result +if result.success: + print(result.data) +else: + print(f"Error: {result.error}") +``` + +## Command Line + +```bash +# Simple execution +uni-wizard execute git_status --repo-path /path + +# With specific house +uni-wizard execute git_status --house ezra --mode intelligent + +# Batch execution +uni-wizard batch tasks.json + +# Check health +uni-wizard health + +# View stats +uni-wizard stats +``` + +## Houses + +| House | Role | Best For | +|-------|------|----------| +| `House.TIMMY` | Sovereign | Final decisions, critical ops | +| `House.EZRA` | Archivist | Reading, analysis, documentation | +| `House.BEZALEL` | Artificer | Building, testing, implementation | +| `House.ALLEGRO` | Dispatch | Routing, connectivity, tempo | + +## Modes + +| Mode | Use When | Features | +|------|----------|----------| +| `Mode.SIMPLE` | Scripts, quick tasks | Direct execution, no overhead | +| `Mode.INTELLIGENT` | Production work | Predictions, learning, adaptation | +| `Mode.SOVEREIGN` | Critical decisions | Full provenance, approval gates | + +## Common Tasks + +### Check System Status +```python +result = harness.execute("system_info") +print(result.data) +``` + +### Git Operations +```python +# Status +result = harness.execute("git_status", repo_path="/path") + +# Log +result = harness.execute("git_log", repo_path="/path", max_count=10) + +# Pull +result = harness.execute("git_pull", repo_path="/path") +``` + +### Health Check +```python +result = harness.execute("health_check") +print(f"Status: {result.data['status']}") +``` + +### Batch Operations +```python +tasks = [ + {"tool": "git_status", "params": {"repo_path": "/path1"}}, + {"tool": "git_status", "params": {"repo_path": "/path2"}}, + {"tool": "system_info", "params": {}} +] +results = harness.execute_batch(tasks) +``` + +## Service Management + +```bash +# Start services +sudo systemctl start uni-wizard +sudo systemctl start timmy-health +sudo systemctl start timmy-task-router + +# Check status +sudo systemctl status uni-wizard + +# View logs +sudo journalctl -u uni-wizard -f +tail -f /opt/timmy/logs/uni-wizard.log + +# Restart +sudo systemctl restart uni-wizard +``` + +## Troubleshooting + +### Service Won't Start +```bash +# Check logs +journalctl -u uni-wizard -n 50 + +# Verify config +cat /opt/timmy/config/uni-wizard.yaml + +# Test manually +python -m uni_wizard health +``` + +### No Predictions +- Check pattern database exists: `ls /opt/timmy/data/patterns.db` +- Verify learning is enabled in config +- Run a few tasks to build patterns + +### Gitea Integration Failing +- Verify API token in config +- Check Gitea URL is accessible +- Test: `curl http://143.198.27.163:3000/api/v1/version` + +## Configuration + +Location: `/opt/timmy/config/uni-wizard.yaml` + +```yaml +house: timmy +mode: intelligent +enable_learning: true + +pattern_db: /opt/timmy/data/patterns.db +log_level: INFO + +gitea: + url: http://143.198.27.163:3000 + token: YOUR_TOKEN_HERE + poll_interval: 300 + +hermes: + stream_enabled: true + db_path: /root/.hermes/state.db +``` + +## API Reference + +### Harness Methods + +```python +# Execute single tool +harness.execute(tool_name, **params) -> ExecutionResult + +# Execute async +await harness.execute_async(tool_name, **params) -> ExecutionResult + +# Execute batch +harness.execute_batch(tasks) -> List[ExecutionResult] + +# Get prediction +harness.predict(tool_name, params) -> Prediction + +# Get stats +harness.get_stats() -> Dict + +# Get patterns +harness.get_patterns() -> Dict +``` + +### ExecutionResult Fields + +```python +result.success # bool +result.data # Any +result.error # Optional[str] +result.provenance # Provenance +result.suggestions # List[str] +``` + +### Provenance Fields + +```python +provenance.house # str +provenance.tool # str +provenance.mode # str +provenance.prediction # float +provenance.execution_time_ms # float +provenance.input_hash # str +provenance.output_hash # str +``` + +--- + +*For full documentation, see ARCHITECTURE.md*