From d2fa0f920c311f3d8aa6772a592de27699f2e307 Mon Sep 17 00:00:00 2001 From: Mikkel Georgsen Date: Fri, 16 Jan 2026 14:31:56 +0000 Subject: [PATCH] Initial spec for MoAI - Master of AIs --- SPEC.md | 385 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 385 insertions(+) create mode 100644 SPEC.md diff --git a/SPEC.md b/SPEC.md new file mode 100644 index 0000000..fa81c1a --- /dev/null +++ b/SPEC.md @@ -0,0 +1,385 @@ +# AI Roundtable + +A multi-AI collaborative brainstorming platform where multiple AI models (Claude, GPT, Gemini, etc.) discuss topics together, see each other's responses, and work toward consensus. + +## Concept + +Instead of asking one AI a question, ask a "team" of AIs. They each provide initial thoughts, then engage in a structured discussion where each can see and respond to the others' contributions. The result is a richer, more diverse exploration of ideas that gets summarized into actionable markdown documents. + +## Core Features + +### Projects/Context +- **Projects** are containers for related discussions +- Each project maintains its own context and conversation history +- Projects have configurable model teams (e.g., Claude + GPT + Gemini) +- CRUD operations for project management +- Projects persist and can be revisited/continued + +### Two Question Modes + +#### 1. Open Question (`/open`) +- Question sent to ALL models in parallel +- Each model responds independently without seeing others +- Fast way to get diverse initial perspectives +- Results displayed together for comparison + +#### 2. Discussion Mode (`/discuss [rounds]`) +- Sequential turn-based discussion +- Each model sees the full conversation history including other models' responses +- Models can agree, disagree, build upon, or challenge each other +- Continues until: + - Consensus is reached (detected by system) + - Round limit is hit (user-defined, e.g., `/discuss 5`) + - User manually stops (`/stop`) + +### Iteration Flow +``` +┌─────────────────────────────────────────────────────────────┐ +│ /open "Initial question" │ +│ ↓ │ +│ [Parallel responses from all models] │ +│ ↓ │ +│ /discuss 5 │ +│ ↓ │ +│ [5 rounds of sequential discussion] │ +│ ↓ │ +│ /consensus │ +│ ↓ │ +│ [AI-generated summary of agreements/disagreements] │ +│ ↓ │ +│ /open "Follow-up question" (includes consensus as context) │ +│ ↓ │ +│ [Cycle continues...] │ +│ ↓ │ +│ /export → Final markdown document │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Direct Model Interaction +- `@claude ` - Direct a question/comment to a specific model +- Other models see this exchange as part of the context +- Useful for drilling down on a specific model's point + +## Architecture + +``` +┌────────────────────────────────────────────────────────────────┐ +│ Web UI (Phase 2) │ +│ - Project CRUD, settings, model config │ +│ - Full discussion timeline view │ +│ - Export/download markdown │ +│ - Rich text, syntax highlighting │ +│ - Drag-drop, edit, reorder │ +└────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────────┐ +│ Python Backend (FastAPI) │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ API Layer │ │ +│ │ /projects, /discussions, /messages, /export │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────────┐ │ +│ │ Projects │ │ Discussions │ │ AI Orchestrator │ │ +│ │ Service │ │ Service │ │ │ │ +│ │ │ │ │ │ - Round management │ │ +│ │ - CRUD │ │ - Open mode │ │ - Context building │ │ +│ │ - Settings │ │ - Discuss │ │ - Consensus detect │ │ +│ │ - Export │ │ - History │ │ - Model routing │ │ +│ └─────────────┘ └─────────────┘ └──────────────────────┘ │ +│ │ │ +│ ┌───────────────┴───────────────┐ │ +│ │ Database (SQLite) │ │ +│ │ projects, discussions, │ │ +│ │ messages, consensus │ │ +│ └───────────────────────────────┘ │ +└────────────────────────────────────────────────────────────────┘ + │ │ + ▼ ▼ +┌──────────────────┐ ┌─────────────────────────┐ +│ Telegram Bot │ │ Requesty / OpenRouter │ +│ (thin client) │ │ │ +│ │ │ - Claude (Anthropic) │ +│ - Commands only │ │ - GPT (OpenAI) │ +│ - No state │ │ - Gemini (Google) │ +│ - Calls API │ │ - Llama, Mistral, etc │ +└──────────────────┘ └─────────────────────────┘ +``` + +## Data Model + +``` +Project +├── id: uuid +├── name: string +├── created_at: timestamp +├── updated_at: timestamp +├── models: ["claude-opus-4", "gpt-4o", "gemini-2-pro"] +├── settings: +│ ├── default_rounds: int (default: 3) +│ ├── consensus_threshold: float (optional, for auto-detect) +│ └── system_prompt_override: string (optional) +└── discussions: Discussion[] + +Discussion +├── id: uuid +├── project_id: uuid (FK) +├── question: string +├── type: "open" | "discuss" +├── status: "active" | "completed" +├── created_at: timestamp +├── rounds: Round[] +└── consensus: Consensus (nullable) + +Round +├── id: uuid +├── discussion_id: uuid (FK) +├── round_number: int +├── type: "parallel" | "sequential" +└── messages: Message[] + +Message +├── id: uuid +├── round_id: uuid (FK) +├── model: string ("claude", "gpt", "gemini") +├── content: text +├── timestamp: timestamp +└── is_direct: boolean (true if @mentioned) + +Consensus +├── id: uuid +├── discussion_id: uuid (FK) +├── agreements: string[] (bullet points) +├── disagreements: [{topic, positions: {model: position}}] +├── generated_at: timestamp +└── generated_by: string (which model summarized) +``` + +## Telegram Commands (Phase 1) + +### Project Management +``` +/projects - List all projects +/project new "Name" - Create new project +/project select - Switch to project +/project delete - Delete project +/project models claude,gpt - Set models for current project +/project info - Show current project details +``` + +### Discussion +``` +/open - Ask all models (parallel) +/discuss [rounds] - Start sequential discussion (default: 3 rounds) +/next - Trigger next round manually +/stop - Stop current discussion +@claude - Direct message to specific model +@gpt +@gemini +``` + +### Output +``` +/consensus - Generate consensus summary +/summarize - Summarize current discussion +/export - Export full project as markdown +/export discussion - Export current discussion only +``` + +### Utility +``` +/status - Show current project/discussion state +/history [n] - Show last n messages +/clear - Clear current discussion (confirm required) +/help - Show commands +``` + +## System Prompts + +### Base System Prompt (all models) +``` +You are participating in a roundtable discussion with other AI models. +Other participants: {list of models} +Current topic: {project name} +Question: {current question} + +Guidelines: +- Be concise but substantive +- You can agree, disagree, or build upon others' points +- Reference other models by name when responding to their points +- Focus on practical, actionable insights +- If you reach agreement with others, state it clearly +``` + +### Consensus Detection Prompt +``` +Review the discussion above. Identify: +1. Points where all models agree +2. Points where models disagree (list each position) +3. Open questions that weren't resolved + +Format as structured JSON. +``` + +## Export Format + +```markdown +# {Project Name} + +**Date:** {date} +**Models:** Claude Opus 4, GPT-4o, Gemini 2 Pro +**Discussions:** {count} + +--- + +## Discussion 1: {Question} + +### Initial Responses (Open) + +**Claude:** +> {response} + +**GPT:** +> {response} + +**Gemini:** +> {response} + +### Discussion (5 rounds) + +**Round 1:** + +**Claude:** {response} + +**GPT:** {response} + +**Gemini:** {response} + +**Round 2:** +... + +### Consensus + +**Agreements:** +- {point 1} +- {point 2} + +**Disagreements:** +- **Topic:** {topic} + - Claude: {position} + - GPT: {position} + +**Open Questions:** +- {question} + +--- + +## Discussion 2: {Follow-up Question} +... + +--- + +## Final Summary + +{AI-generated executive summary of all discussions} +``` + +## Phase 1: Telegram POC + +### Scope +- Single-user (your Telegram only) +- SQLite database +- Basic project CRUD via commands +- Open and discuss modes working +- Export to markdown (sent as document) +- Requesty/OpenRouter integration + +### Tech Stack +- Python 3.11+ +- python-telegram-bot (async) +- FastAPI (internal API, optional for phase 1) +- SQLite + SQLAlchemy +- httpx for API calls +- Requesty or OpenRouter for model routing + +### File Structure +``` +ai-roundtable/ +├── bot/ +│ ├── __init__.py +│ ├── main.py # Bot entry point +│ ├── handlers/ +│ │ ├── projects.py # /project commands +│ │ ├── discussion.py # /open, /discuss, @mentions +│ │ └── export.py # /export, /consensus +│ └── middleware.py # Auth, logging +├── core/ +│ ├── __init__.py +│ ├── models.py # SQLAlchemy models +│ ├── database.py # DB connection +│ ├── orchestrator.py # AI round management +│ ├── ai_client.py # Requesty/OpenRouter wrapper +│ └── exporter.py # Markdown generation +├── config.py # Settings, API keys +├── requirements.txt +└── README.md +``` + +### MVP Milestones +1. **M1:** Bot responds to /help, /status +2. **M2:** Project CRUD working +3. **M3:** Single model Q&A working (no discussion yet) +4. **M4:** Open mode (parallel) working with multiple models +5. **M5:** Discuss mode (sequential) working +6. **M6:** Consensus generation working +7. **M7:** Export to markdown working +8. **M8:** @mention direct messages working + +## Phase 2: Web UI + +### Additional Features +- Visual timeline of discussions +- Project dashboard +- Model performance/cost tracking +- Edit/delete individual messages +- Branching discussions (explore alternatives) +- Share/collaborate (multi-user) +- Templates for common brainstorm types + +### Tech Stack Options +- **Frontend:** Vue 3 + Vite or React + Next.js +- **Backend:** FastAPI (expand from Phase 1) +- **Database:** PostgreSQL (upgrade from SQLite) +- **Auth:** Simple token or OAuth +- **Hosting:** Dockge/Docker on homelab + +## Cost Considerations + +Each discussion round involves multiple API calls: +- Open question: N calls (one per model) +- Discussion round: N calls +- Consensus: 1 call + +Example: 3 models, 1 open + 5 discuss rounds + consensus = 3 + 15 + 1 = 19 API calls + +Use Requesty/OpenRouter for: +- Single API key for all models +- Cost tracking +- Fallback routing +- Rate limit handling + +## Future Ideas + +- **Personas:** Configure models with different perspectives (optimist, critic, pragmatist) +- **Voting:** Models vote on proposals, user sees tally +- **Memory:** Cross-project context (reference past conclusions) +- **Triggers:** Automated discussions on schedule or webhook +- **Voice:** Voice memos transcribed and fed to discussion + +--- + +*Created: 2026-01-16* +*Status: Planning* +*Phase: 1 (Telegram POC)*