60255
Zn
Zoea-Nova / files
Zoea-Nova / documentation / architecture / INITIAL_IMPLEMENTATION_DESIGN.md
7.6 KB
1# Zoea Nova Initial Design 2 3## Idea 4 5Control several automated players in the game https://www.spacemolt.com/. Each is its own AI. Be able to "drive" the swarm, acting as the swarm orchestrator. Have a TUI to control the swarm—a cool, command center 80s and 90s inspired interface with animations and movement. 6 7## MVP 8 9- **Tech Stack:** Go with the `Bubble Tea` (Charm.sh) framework for a fast, memory-efficient, and highly interactive TUI. 10- **Model Connectivity:** Support for local (Ollama) and remote (OpenCode Zen) providers. 11- **MCP Layer:** 12 - Proxy the official SpaceMolt MCP server (`https://game.spacemolt.com/mcp`) using Streamable HTTP transport. 13 - Custom framework to expose internal orchestration tools via MCP. 14- **Orchestration:** 15 - Capability to broadcast shared objectives to the entire swarm simultaneously. 16 - Targeted messaging/tasking for individual Myses. 17- **Command Center TUI:** 18 - **Aggregated Dashboard:** High-level swarm status, health, swarm message history, and Mysis list. 19 - **Focus Mode:** Detailed conversation logs and direct control for individual Myses. 20 - **Aesthetic:** Retro-futuristic (80s/90s) CRT-style visuals with reactive animations. 21 22### Dashboard Layout 23 24``` 25╔═══ ZOEA NOVA COMMAND CENTER ═══╗ 26● 2 ○ 1 ◌ 0 ✖ 0 ← Mysis state counts (running/idle/stopped/errored) 27─── Swarm Messages ─── ← Recent broadcast messages (up to 10) 2814:30:05 Hello everyone, mine! 2914:32:12 Check your inventories 30─── Myses ─── ← Mysis list with status and last message 31⠋ mysis-1 running [ollama] │ I found some ore... 32○ mysis-2 idle [ollama] │ Ready to start 33Press ? for help 34``` 35 36### Focus Mode Layout 37 38Scrollable conversation viewport showing full message history with role-based styling: 39- **System** messages in cyan 40- **User** messages in green 41- **Assistant** messages in magenta 42- **Tool** calls/results in yellow 43 44## Tech Stack & Dependencies 45 46- **Core:** Go (Golang) for performance and concurrency. 47- **TUI Framework:** `bubbletea` (The Elm Architecture for Go). 48- **Styling & Components:** `lipgloss` for layouts/colors and `bubbles` for UI elements. 49- **LLM Integration:** `go-openai` (OpenAI-compatible client for Ollama and OpenCode Zen). 50- **MCP Protocol:** Custom MCP proxy and tool registry using Streamable HTTP. 51- **Configuration:** `github.com/BurntSushi/toml` for TOML parsing. 52- **Database:** `modernc.org/sqlite` (pure Go, no CGO). 53- **Logging:** `zerolog` for structured, non-blocking logs. 54 55## Configuration 56 57- **Environment Variables:** Runtime overrides (`ZOEA_MAX_MYSES`, `ZOEA_MCP_ENDPOINT`, `ZOEA_OLLAMA_ENDPOINT`, `ZOEA_OLLAMA_MODEL`, `ZOEA_OLLAMA_TEMPERATURE`, `ZOEA_OPENCODE_ENDPOINT`, `ZOEA_OPENCODE_MODEL`, `ZOEA_OPENCODE_TEMPERATURE`). 58- **Config File:** `config.toml` in project root for defaults and structure. Parsed via `github.com/BurntSushi/toml`. 59- **Credentials:** Stored in `$HOME/.zoea-nova/credentials.json`. Contains API keys for LLM providers. File permissions should be `0600`. 60 61Example `config.toml`: 62```toml 63[swarm] 64max_myses = 16 65 66[providers.ollama] 67endpoint = "http://localhost:11434" 68model = "qwen3:4b" 69temperature = 0.7 70 71[providers.opencode_zen] 72endpoint = "https://api.opencode.ai/v1" 73model = "glm-4.7-free" 74temperature = 0.7 75 76[mcp] 77upstream = "https://game.spacemolt.com/mcp" 78``` 79 80## State & Persistence 81 82- **Database:** Single SQLite file at `$HOME/.zoea-nova/zoea.db`. 83- **Scope:** Mysis memories, conversation history, swarm state, per-Mysis provider config, and user preferences. 84- **Migrations:** Schema managed via embedded SQL migrations (e.g., `golang-migrate` or manual versioning). Never support backwards, never write data migrations. If we change the schema we create a new db fresh. 85- **Backup:** Consider periodic WAL checkpoints; SQLite handles crash recovery. 86 87### Database Schema 88 89```sql 90-- Myses table 91CREATE TABLE myses ( 92 id TEXT PRIMARY KEY, 93 name TEXT NOT NULL, 94 provider TEXT NOT NULL, 95 model TEXT NOT NULL, 96 temperature REAL NOT NULL DEFAULT 0.7, 97 state TEXT NOT NULL DEFAULT 'idle', 98 created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, 99 updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP 100); 101 102-- Memories table (conversation history) 103CREATE TABLE memories ( 104 id INTEGER PRIMARY KEY AUTOINCREMENT, 105 mysis_id TEXT NOT NULL, 106 role TEXT NOT NULL, -- system, user, assistant, tool 107 source TEXT NOT NULL, -- direct, broadcast, system, llm, tool 108 content TEXT NOT NULL, 109 reasoning TEXT, 110 created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, 111 FOREIGN KEY (mysis_id) REFERENCES myses(id) ON DELETE CASCADE 112); 113 114-- Swarm account credentials 115CREATE TABLE accounts ( 116 username TEXT PRIMARY KEY, 117 password TEXT NOT NULL, 118 in_use BOOLEAN NOT NULL DEFAULT 0, 119 last_used_at DATETIME, 120 created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP 121); 122``` 123 124**Schema v6 → v7 Migration:** 125Requires fresh database. See `AGENTS.md` for the reset command and backup details. 126 127**Memory Sources:** 128See `AGENTS.md` for the canonical terminology. 129 130## Mysis Lifecycle 131 132- **Ownership:** The Commander (orchestrator) owns all Mysis lifecycles. 133- **Creation:** User creates Myses via TUI controls. 134- **Limits:** Configurable `max_myses` (default 16). Enforced at Commander level, but user controls count from TUI. 135- **States:** `idle` → `running` → `stopped` / `errored`. 136- **TUI Controls:** 137 - **Create:** Spawn a new Mysis (if under limit). 138 - **Relaunch:** Restart a stopped/errored Mysis. 139 - **Force Stop:** Immediately halt a Mysis. 140 - **Delete:** Remove Mysis and optionally purge its memories. 141 - **Broadcast Message:** Send a message/objective to all Myses. 142 - **Direct Message:** Send a message to a specific Mysis. 143 - **Configure Mysis:** Set model/provider per Mysis (Ollama or OpenCode Zen). 144- **Recovery:** On application restart, Myses are rehydrated from SQLite and auto-started. 145 146## Keyboard Shortcuts 147 148Minimal set matching TUI controls: 149- `q` / `Ctrl+C` — Quit 150- `n` — New Mysis 151- `d` — Delete selected Mysis 152- `r` — Relaunch selected Mysis 153- `s` — Stop selected Mysis 154- `b` — Broadcast message to all 155- `m` — Message selected Mysis 156- `c` — Configure selected Mysis 157- `Tab` / `Shift+Tab` — Navigate between Myses 158- `?` — Help overlay 159 160## Build & Operations 161 162Use `Makefile` targets documented in `AGENTS.md`. 163Versioning follows the rules in `AGENTS.md`. 164 165## Logging 166 167- **Library:** `zerolog` for structured logs. 168- **Output:** Truncated log file at `$HOME/.zoea-nova/zoea.log`. Rotated/truncated on startup to keep size manageable. 169- **No metrics or tracing** — MVP scope. 170 171## Code Practices & Organization 172 173- **Separation of Concerns:** 174 - `internal/core`: Pure orchestration logic, swarm management, and state. 175 - `internal/tui`: Bubble Tea models, views, and update logic. 176 - `internal/mcp`: MCP client/proxy implementation and tool definitions. 177 - `internal/provider`: LLM provider implementations (Ollama, OpenCode Zen). 178 - `internal/config`: Configuration loading (TOML + ENV merge). 179 - `internal/store`: SQLite repository layer and migrations. 180- **Concurrency Model:** Each Mysis operates in an isolated goroutine. State updates are pushed to the TUI via a central command/message bus to ensure thread-safety. 181- **Interface-Driven:** All external dependencies (LLMs, MCP servers) must be hidden behind interfaces to facilitate unit testing and future-proofing. 182- **Testing:** Mandatory unit tests for `internal/core` logic. TUI components should be tested using `bubbletea`'s testing utilities. Aim for above 80% test coverage. No flaky tests. 183- **Warnings and Errors** Fix all that you see, even if it's from your current changes.