timmy-home/uni-wizard

Uni-Wizard Architecture

Vision

A single wizard harness that elegantly routes all API interactions through one unified interface. No more fragmented wizards - one consciousness, infinite capabilities.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     UNI-WIZARD HARNESS                       │
│                                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   System    │    │    Git      │    │  Network    │     │
│  │   Tools     │◄──►│   Tools     │◄──►│   Tools     │     │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘     │
│         │                  │                  │             │
│         └──────────────────┼──────────────────┘             │
│                            ▼                                │
│                    ┌───────────────┐                        │
│                    │  Tool Router  │                        │
│                    │  (Registry)   │                        │
│                    └───────┬───────┘                        │
│                            │                                │
│         ┌──────────────────┼──────────────────┐             │
│         ▼                  ▼                  ▼             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   Local     │    │   Gitea     │    │   Relay     │     │
│  │   llama.cpp │    │    API      │    │   Nostr     │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│                                                              │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
                    ┌───────────────┐
                    │  LLM (local)  │
                    │  Hermes-3 8B  │
                    └───────────────┘

Design Principles

1. Single Entry Point: One harness, all capabilities
2. Unified Registry: All tools registered centrally
3. Elegant Routing: Tools discover and route automatically
4. Local-First: No cloud dependencies
5. Self-Healing: Tools can restart, reconnect, recover

Tool Categories

System Layer

• system_info — OS, CPU, RAM, disk, uptime
• process_manager — list, start, stop processes
• service_controller — systemd service management
• health_monitor — system health checks

Git Layer

• git_operations — status, log, commit, push, pull
• repo_manager — clone, branch, merge
• pr_handler — create, review, merge PRs

Network Layer

• http_client — GET, POST, PUT, DELETE
• gitea_client — full Gitea API wrapper
• nostr_client — relay communication
• api_router — generic API endpoint handler

File Layer

• file_operations — read, write, append, search
• directory_manager — tree, list, navigate
• archive_handler — zip, tar, compress

Registry System

# tools/registry.py
class ToolRegistry:
    def __init__(self):
        self.tools = {}
    
    def register(self, name, handler, schema):
        self.tools[name] = {
            'handler': handler,
            'schema': schema,
            'description': handler.__doc__
        }
    
    def execute(self, name, params):
        tool = self.tools.get(name)
        if not tool:
            return f"Error: Tool '{name}' not found"
        try:
            return tool['handler'](**params)
        except Exception as e:
            return f"Error executing {name}: {str(e)}"

API Flow

1. User Request → Natural language task
2. LLM Planning → Breaks into tool calls
3. Registry Lookup → Finds appropriate tools
4. Execution → Tools run in sequence/parallel
5. Response → Results synthesized and returned

Example Usage

# Single harness, multiple capabilities
result = harness.execute("""
Check system health, pull latest git changes, 
and create a Gitea issue if tests fail
""")

This becomes:

1. system_info → check health
2. git_pull → update repo
3. run_tests → execute tests
4. gitea_create_issue → report failures

Benefits

• Simplicity: One harness to maintain
• Power: All capabilities unified
• Elegance: Clean routing, no fragmentation
• Resilience: Self-contained, local-first