# Multi-Agent Meeting Framework

A lightweight, Unix-style multi-agent collaboration system in pure Python. No heavy frameworks — just `pydantic`, an LLM SDK, and clean code.

## Quick Start

### 1. Install dependencies

```bash
pip install -r requirements.txt
```

### 2. Set your API key

```bash
# For Anthropic (default)
export ANTHROPIC_API_KEY="your-key-here"

# Or for OpenAI
export LLM_PROVIDER=openai
export OPENAI_API_KEY="your-key-here"
```

### 3. Create agents

```bash
python agent_builder.py --description "资深软件架构师，关注系统可扩展性和技术债务" --name architect
python agent_builder.py --description "商业分析师，关注 ROI 和市场可行性" --name business_analyst
python agent_builder.py --description "DevOps 工程师，关注部署复杂度和运维成本" --name devops
```

### 4. Run a meeting

```bash
# Manual agent selection
python run_meeting.py --topic "评估从 PostgreSQL 迁移到 MongoDB 的方案" --agents architect,business_analyst,devops

# Or use a preset scenario
python run_meeting.py --topic "评估从 PostgreSQL 迁移到 MongoDB 的方案" --scenario tech_design

# Or let PM auto-select agents
python run_meeting.py --topic "评估从 PostgreSQL 迁移到 MongoDB 的方案" --auto-select

# With background context for deeper discussion
python run_meeting.py --topic "评估从 PostgreSQL 迁移到 MongoDB 的方案" --scenario tech_design --context-file docs/migration-brief.md

# Interactive mode: provide feedback mid-discussion
python run_meeting.py --topic "评估从 PostgreSQL 迁移到 MongoDB 的方案" --agents architect,devops --interactive
```

## CLI Reference

### agent_builder.py

Generate an Agent config from a natural language description.

```
python agent_builder.py --description "..." --name NAME [--output-dir agents/] [--format json|yaml]
```

### run_meeting.py

Run a multi-agent meeting.

```
python run_meeting.py --topic "..." --agents name1,name2 [options]
python run_meeting.py --topic "..." --scenario SCENARIO [options]
python run_meeting.py --topic "..." --auto-select [options]
python run_meeting.py --list-scenarios
```

| Option | Description | Default |
|--------|-------------|---------|
| `--topic` | Discussion topic (required) | — |
| `--agents` | Comma-separated agent names | — |
| `--scenario` | Use a preset scenario | — |
| `--auto-select` | PM auto-selects agents | — |
| `--list-scenarios` | List preset scenarios and exit | — |
| `--context` | Inline background context | `""` |
| `--context-file` | Read context from file | — |
| `--max-rounds` | Maximum discussion rounds | 10 |
| `--interactive` | Enable human-in-the-loop mode | `false` |
| `--agents-dir` | Agent config directory | `agents/` |
| `--output-dir` | Report output directory | `reports/` |

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `LLM_PROVIDER` | `anthropic` | LLM backend: `anthropic` or `openai` |
| `LLM_MODEL` | auto | Model name (defaults: `claude-sonnet-4-20250514` / `gpt-4o`) |
| `ANTHROPIC_API_KEY` | — | Anthropic API key |
| `OPENAI_API_KEY` | — | OpenAI API key |

## Architecture

- **Stateless Agents**: Each agent receives only the PM's question and a whiteboard summary
- **PM Router**: A state-machine PM agent outputs structured JSON decisions
- **Shared Whiteboard**: All context lives in a `MeetingState` Pydantic model
- **Hard Loop Limit**: `max_rounds` prevents infinite discussions (default: 10)
- **Full Transcript**: Every discussion is saved as `.transcript.md` alongside the report
- **Preset Scenarios**: 6 built-in scenarios for common meeting types
- **Auto Agent Selection**: PM can automatically choose the best agents for a topic
- **Human-in-the-Loop**: `--interactive` mode lets you inject feedback mid-discussion

## Running Tests

```bash
python -m pytest tests/ -v
```