Create Design-v2.md

Design-v2.md

@@ -0,0 +1,363 @@
+Here’s a clean, structured **design.md** you can directly use to preserve architecture knowledge 👇
+
+---
+
+# 🧠 PygmyClaw Multi-Agent System Design
+
+## 🎯 Goal
+
+Build a **multi-agent AI system** with:
+
+* Code execution
+* Web search
+* Image generation
+* Deep research
+
+All orchestrated from a **single command center UI**
+
+---
+
+# 🏗️ Architecture Overview
+
+```
+UI (app.py)
+    ↓
+Session Manager
+    ↓
+Agent Router
+    ↓
+Agent Executor (PygmyClaw)
+    ↓
+Model Router
+    ↓
+Tool Manager
+```
+
+---
+
+# 📦 Existing Components (DO NOT REWRITE)
+
+* `app.py` → UI layer
+* `pygmyclaw.py` → core execution engine (queue + speculative decoding)
+* `pygmyclaw_multitool.py` → tools implementation
+* `config.json` → base configuration
+
+👉 Strategy: **Wrap and extend, not replace**
+
+---
+
+# 🧱 Core Classes
+
+---
+
+## 1. 🧑‍💼 SessionManager
+
+### Purpose
+
+Manages:
+
+* Users
+* Sessions
+* Workspace persistence
+* Settings
+
+### Responsibilities
+
+* Create/load users
+* Create/load sessions
+* Save/load workspace.json
+* Save/load settings.json
+
+### Structure
+
+```python
+class SessionManager:
+    def create_user(self, username): pass
+    def load_user(self, username): pass
+    def create_session(self, username): pass
+    def load_workspace(self, username, session_id): pass
+    def save_workspace(self, username, session_id, data): pass
+    def get_settings(self, username): pass
+    def save_settings(self, username, settings): pass
+```
+
+---
+
+## 2. 🧭 AgentRouter (SYSTEM BRAIN)
+
+### Purpose
+
+Routes user input to correct agent:
+
+```
+input → agent_type
+```
+
+### Agent Types
+
+* `command`
+* `code`
+* `research`
+* `image`
+
+### Structure
+
+```python
+class AgentRouter:
+    def route(self, message: str) -> str:
+        pass
+```
+
+### Notes
+
+* Start with keyword-based routing
+* Upgrade later to LLM-based intent detection
+
+---
+
+## 3. 🤖 AgentExecutor (PygmyClaw Wrapper)
+
+### Purpose
+
+Executes tasks based on agent type
+
+### Key Idea
+
+```
+Agent = behavior
+Model = engine
+```
+
+### Structure
+
+```python
+class AgentExecutor:
+    def __init__(self, model_router, tool_manager): pass
+
+    def run(self, agent_type, message, session):
+        pass
+```
+
+### Responsibilities
+
+* Select system prompt
+* Select tools
+* Call pygmyclaw generate
+* Return structured output
+
+---
+
+## 4. 🧰 ToolManager
+
+### Purpose
+
+Controls tool access per agent
+
+### Structure
+
+```python
+class ToolManager:
+    def get_tools(self, agent_type):
+        pass
+```
+
+### Example Mapping
+
+```json
+{
+  "command": ["echo", "sys_info"],
+  "code": ["run_python", "write_file"],
+  "research": ["web_search", "read_url"],
+  "image": ["generate_image"]
+}
+```
+
+### Rule
+
+👉 Agents only access allowed tools (security + clarity)
+
+---
+
+## 5. 🧠 ModelRouter (Future Ready)
+
+### Purpose
+
+Abstract model selection
+
+### Structure
+
+```python
+class ModelRouter:
+    def get_model(self, agent_type):
+        return default_model
+```
+
+### Phase Strategy
+
+* Phase 1 → single model
+* Phase 2 → role-based prompts
+* Phase 3 → multi-model routing
+
+---
+
+## 6. 📂 Workspace Structure
+
+### Directory Layout
+
+```
+/workspace/users/
+    └── <username>/
+        ├── settings.json
+        └── sessions/
+            └── <session_id>/
+                └── workspace.json
+```
+
+---
+
+## settings.json (Simplified)
+
+```json
+{
+  "default_model": "ollama:llama3",
+  "agents": {
+    "command": "default",
+    "code": "default",
+    "research": "default",
+    "image": "default"
+  }
+}
+```
+
+---
+
+## workspace.json (Core Data)
+
+Stores:
+
+* tabs
+* messages
+* agent tasks
+* timeline
+* debug history
+
+---
+
+# 🔁 Full Execution Flow
+
+```
+User Input (UI)
+    ↓
+SessionManager → load session
+    ↓
+AgentRouter → detect agent_type
+    ↓
+AgentExecutor.run()
+        ↓
+    ModelRouter → select model
+        ↓
+    ToolManager → allowed tools
+        ↓
+    PygmyClaw → generate output
+    ↓
+SessionManager → save workspace
+    ↓
+UI update
+```
+
+---
+
+# 🧠 Key Design Principles
+
+---
+
+## 1. Agent ≠ Model
+
+| Concept | Meaning          |
+| ------- | ---------------- |
+| Agent   | behavior         |
+| Model   | execution engine |
+
+👉 Many agents can share one model
+
+---
+
+## 2. Start Simple, Scale Later
+
+### Phase 1
+
+* Single model
+* Multi-agent behavior
+
+### Phase 2
+
+* Better routing
+* Tool optimization
+
+### Phase 3
+
+* Multi-model support
+
+---
+
+## 3. Tools Are Scoped
+
+| Agent    | Allowed         |
+| -------- | --------------- |
+| command  | basic tools     |
+| code     | execution tools |
+| research | web tools       |
+| image    | image tools     |
+
+---
+
+## 4. Session is Core
+
+Everything tied to:
+
+```
+username + session_id
+```
+
+---
+
+## 5. Do NOT Modify Core Engine
+
+* Keep `pygmyclaw.py` intact
+* Extend via wrapper layers
+
+---
+
+# 🚀 Future Enhancements
+
+* LLM-based agent routing
+* Multi-model support (Ollama + HF)
+* Parallel agents
+* Streaming outputs
+* Advanced workspace UI (tabs, timelines)
+
+---
+
+# 🧭 Summary
+
+This system evolves into:
+
+> **A single-model, multi-agent AI platform with persistent memory, tool orchestration, and scalable architecture**
+
+---
+
+# ✅ Next Step
+
+Design **Agent Behavior Definitions**:
+
+For each agent:
+
+* system prompt
+* tools
+* constraints
+* output format
+
+
+
+---
+