128 lines
5.3 KiB
Markdown
128 lines
5.3 KiB
Markdown
|
# 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
|