moai/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MoAI (Master of AIs) is a multi-AI collaborative brainstorming platform. Multiple AI models (Claude, GPT, Gemini) discuss topics together in structured rounds, working toward consensus. Phase 1 is a Telegram bot; Phase 2 adds a web UI.

Build & Development Commands

# Install dependencies (use uv or pip)
uv sync                          # or: pip install -e ".[dev]"

# Run the bot
python -m moai.bot.main

# Run tests
pytest                           # all tests
pytest tests/test_models.py      # single file
pytest -k "test_create"          # by name pattern
pytest --cov=moai --cov-report=term-missing  # with coverage

# Linting & formatting
ruff check src tests             # lint
ruff format src tests            # format
ruff check --fix src tests       # auto-fix

Architecture

Core flow: Telegram command → Handler → Service → AI Orchestrator → Requesty/OpenRouter → Multiple AI APIs

src/moai/
├── bot/
│   ├── main.py           # Bot entry point, dispatcher setup
│   ├── handlers/         # Telegram command handlers (thin, delegate to core)
│   │   ├── projects.py   # /project commands
│   │   ├── discussion.py # /open, /discuss, @mentions
│   │   └── export.py     # /export, /consensus
│   └── middleware.py     # Auth, logging
└── core/
    ├── models.py         # SQLAlchemy models (Project, Discussion, Round, Message, Consensus)
    ├── database.py       # DB session management
    ├── orchestrator.py   # AI round management, context building, consensus detection
    ├── ai_client.py      # Requesty/OpenRouter wrapper, model routing
    └── exporter.py       # Markdown generation

Key patterns:

• Bot handlers are thin clients—business logic lives in core/
• Orchestrator manages discussion state: parallel (open) vs sequential (discuss) modes
• All AI calls go through ai_client.py which abstracts the routing layer
• SQLite for Phase 1, models designed for PostgreSQL upgrade

Coding Standards

• Python 3.11+
• Formatting: ruff (line length 100)
• Type hints: Required on all public functions
• Docstrings: Required on modules and classes
• Logging: Use logging module, no print()
• Testing: pytest, target 80%+ coverage on core logic
• Dependencies: No pinned versions unless security required

Data Model Relationships

Project (has many) → Discussion (has many) → Round (has many) → Message
                   ↘ Discussion (has one) → Consensus

Current Phase

Phase 1: Telegram POC. Milestones:

• M1: Bot responds to /help, /status
• M2: Project CRUD
• M3-M8: Discussion modes, consensus, export, @mentions