# 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

```python
# 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

```python
# 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