timmy-home/docs/QUICK_REFERENCE.md

Uni-Wizard v4 — Quick Reference

Installation

# Run setup script
sudo ./scripts/setup-uni-wizard.sh

# Or manual install
cd uni-wizard/v4
pip install -e .

Basic Usage

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

# 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

result = harness.execute("system_info")
print(result.data)

Git Operations

# 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

result = harness.execute("health_check")
print(f"Status: {result.data['status']}")

Batch Operations

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

# 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

# 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

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

# 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

result.success          # bool
result.data            # Any
result.error           # Optional[str]
result.provenance      # Provenance
result.suggestions     # List[str]

Provenance Fields

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