<p align="center">
<img src="assets/logo.png" alt="MassGen Logo" width="360" />
</p>
<p align="center">
<a href="https://www.python.org/downloads/">
<img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+" style="margin-right: 5px;">
</a>
<a href="LICENSE">
<img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License" style="margin-right: 5px;">
</a>
<a href="https://discord.massgen.ai">
<img src="https://img.shields.io/discord/1153072414184452236?color=7289da&label=chat&logo=discord&style=flat-square" alt="Join our Discord">
</a>
</p>
<h1 align="center">🚀 MassGen: Multi-Agent Scaling System for GenAI</h1>
<p align="center">
<i>MassGen is a cutting-edge multi-agent system that leverages the power of collaborative AI to solve complex tasks.</i>
</p>
<p align="center">
<a href="https://youtu.be/Dp2oldJJImw">
<img src="https://img.youtube.com/vi/Dp2oldJJImw/0.jpg" alt="MassGen Demo Video" width="600">
</a>
</p>
<p align="center">
<i>Multi-agent scaling through intelligent collaboration in Grok Heavy style</i>
</p>
MassGen is a cutting-edge multi-agent system that leverages the power of collaborative AI to solve complex tasks. It assigns a task to multiple AI agents who work in parallel, observe each other's progress, and refine their approaches to converge on the best solution to deliver a comprehensive and high-quality result. The power of this "parallel study group" approach is exemplified by advanced systems like xAI's Grok Heavy and Google DeepMind's Gemini Deep Think.
This project started with the "threads of thought" and "iterative refinement" ideas presented in [The Myth of Reasoning](https://docs.ag2.ai/latest/docs/blog/2025/04/16/Reasoning/), and extends the classic "multi-agent conversation" idea in [AG2](https://github.com/ag2ai/ag2). Here is a [video recording](https://www.youtube.com/watch?v=xM2Uguw1UsQ) of the background context introduction presented at the Berkeley Agentic AI Summit 2025.
---
## 📋 Table of Contents
<details open>
<summary><h3>✨ Key Features</h3></summary>
- [Cross-Model/Agent Synergy](#-key-features-1)
- [Parallel Processing](#-key-features-1)
- [Intelligence Sharing](#-key-features-1)
- [Consensus Building](#-key-features-1)
- [Live Visualization](#-key-features-1)
</details>
<details open>
<summary><h3>🏗️ System Design</h3></summary>
- [System Architecture](#%EF%B8%8F-system-design-1)
- [Parallel Processing](#%EF%B8%8F-system-design-1)
- [Real-time Collaboration](#%EF%B8%8F-system-design-1)
- [Convergence Detection](#%EF%B8%8F-system-design-1)
- [Adaptive Coordination](#%EF%B8%8F-system-design-1)
</details>
<details open>
<summary><h3>🚀 Quick Start</h3></summary>
- [📥 Installation](#1--installation)
- [🔐 API Configuration](#2--api-configuration)
- [🧩 Supported Models and Tools](#3--supported-models-and-tools)
- [Models](#models)
- [Tools](#tools)
- [🏃 Run MassGen](#4--run-massgen)
- [Quick Test with A Single Model](#quick-test-with-a-single-model)
- [Multiple Agents from Config](#multiple-agents-from-config)
- [CLI Configuration Parameters](#cli-configuration-parameters)
- [Configuration File Format](#configuration-file-format)
- [Interactive Multi-Turn Mode](#interactive-multi-turn-mode)
- [📊 View Results](#5--view-results)
- [Real-time Display](#real-time-display)
- [Comprehensive Logging](#comprehensive-logging)
</details>
<details open>
<summary><h3>💡 Examples</h3></summary>
- [📚 Case Studies](#case-studies)
- [❓ Question Answering](#1--question-answering)
- [🧠 Creative Writing](#2--creative-writing)
- [🔬 Research](#3-research)
</details>
<details open>
<summary><h3>🗺️ Roadmap</h3></summary>
- [Key Future Enhancements](#key-future-enhancements)
- Advanced Agent Collaboration
- Expanded Model, Tool & Agent Integration
- Improved Performance & Scalability
- Enhanced Developer Experience
- Web Interface
- [v0.0.4 Roadmap](#v004-roadmap)
</details>
<details open>
<summary><h3>📚 Additional Resources</h3></summary>
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)
- [⭐ Star History](#-star-history)
</details>
---
## ✨ Key Features
| Feature | Description |
|---------|-------------|
| **🤝 Cross-Model/Agent Synergy** | Harness strengths from diverse frontier model-powered agents |
| **⚡ Parallel Processing** | Multiple agents tackle problems simultaneously |
| **👥 Intelligence Sharing** | Agents share and learn from each other's work |
| **🔄 Consensus Building** | Natural convergence through collaborative refinement |
| **📊 Live Visualization** | See agents' working processes in real-time |
---
## 🏗️ System Design
MassGen operates through an architecture designed for **seamless multi-agent collaboration**:
```mermaid
graph TB
O[🚀 MassGen Orchestrator<br/>📋 Task Distribution & Coordination]
subgraph Collaborative Agents
A1[Agent 1<br/>🏗️ Anthropic/Claude + Tools]
A2[Agent 2<br/>🌟 Google/Gemini + Tools]
A3[Agent 3<br/>🤖 OpenAI/GPT/O + Tools]
A4[Agent 4<br/>⚡ xAI/Grok + Tools]
end
H[🔄 Shared Collaboration Hub<br/>📡 Real-time Notification & Consensus]
O --> A1 & A2 & A3 & A4
A1 & A2 & A3 & A4 <--> H
classDef orchestrator fill:#e1f5fe,stroke:#0288d1,stroke-width:3px
classDef agent fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
classDef hub fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
class O orchestrator
class A1,A2,A3,A4 agent
class H hub
```
The system's workflow is defined by the following key principles:
**Parallel Processing** - Multiple agents tackle the same task simultaneously, each leveraging their unique capabilities (different models, tools, and specialized approaches).
**Real-time Collaboration** - Agents continuously share their working summaries and insights through a notification system, allowing them to learn from each other's approaches and build upon collective knowledge.
**Convergence Detection** - The system intelligently monitors when agents have reached stability in their solutions and achieved consensus through natural collaboration rather than forced agreement.
**Adaptive Coordination** - Agents can restart and refine their work when they receive new insights from others, creating a dynamic and responsive problem-solving environment.
This collaborative approach ensures that the final output leverages collective intelligence from multiple AI systems, leading to more robust and well-rounded results than any single agent could achieve alone.
---
## 🚀 Quick Start
### 1. 📥 Installation
```bash
git clone https://github.com/Leezekun/MassGen.git
cd MassGen
pip install uv
uv venv
```
### 2. 🔐 API Configuration
Create a `.env` file in the `massgen` directory with your API keys:
```bash
# Copy example configuration
cp .env.example .env
# Edit with your API keys
ANTHROPIC_API_KEY=your-anthropic-key-here
GEMINI_API_KEY=your-gemini-key-here
OPENAI_API_KEY=your-openai-key-here
XAI_API_KEY=your-xai-key-here
```
Make sure you set up the API key for the model you want to use.
**Useful links to get API keys:**
- [Claude](https://docs.anthropic.com/en/api/overview)
- [Gemini](https://ai.google.dev/gemini-api/docs)
- [Grok](https://docs.x.ai/docs/overview)
- [OpenAI](https://platform.openai.com/api-keys)
### 3. 🧩 Supported Models and Tools
#### Models
The system currently supports four model providers with advanced reasoning capabilities: **Anthropic Claude**, **Google Gemini**, **OpenAI**, **xAI Grok**.
More providers and local inference of open-weight models (using vllm or sglang) are welcome to be added.
#### Tools
MassGen agents can leverage various tools to enhance their problem-solving capabilities. `Claude`, `Gemini`, and `OpenAI` models support built-in web search and code execution. `Grok` supports web search as well, but it does not currently offer native code execution at the model level.
**Supported Built-in Tools by Models:**
| Backend | Live Search | Code Execution |
|---------|:-----------:|:--------------:|
| **Claude** | ✅ | ✅ |
| **OpenAI** | ✅ | ✅ |
| **Grok** | ✅ | ❌ |
| **Gemini** | ✅ | ✅ |
### 4. 🏃 Run MassGen
#### Quick Test with A Single Model
```bash
uv run python -m massgen.cli --model gemini-2.5-flash "Which AI won IMO in 2025?"
uv run python -m massgen.cli --model gpt-4o-mini "Which AI won IMO in 2025?"
uv run python -m massgen.cli --model grok-3-mini "Which AI won IMO in 2025?"
```
All supported models can be found [here](massgen/utils.py).
#### Multiple Agents from Config
```bash
# Use configuration file
uv run python -m massgen.cli --config three_agents_default.yaml "Compare different approaches to renewable energy"
```
All available quick configuration files can be found [here](massgen/configs).
#### CLI Configuration Parameters
| Parameter | Description |
|-------------------|-------------|
| `--config` | Path to YAML configuration file with agent definitions, model parameters, backend parameters and UI settings |
| `--backend` | Backend type for quick setup without a config file (`claude`, `gemini`, `grok` or `openai`). Optional because we can infer backend type through model.|
| `--model` | Model name for quick setup (e.g., `gpt-4o-mini`, `claude-sonnet-4-20250514`, ...). See all [supported models](massgen/utils.py). `--config` and `--model` are mutually exclusive - use one or the other. |
| `--system-message` | System prompt for the agent in quick setup mode. If `--config` is provided, `--system-message` is omitted. |
| `--no-display` | Disable real-time streaming UI coordination display (fallback to simple text output).|
| `--no-logs` | Disable real-time logging.|
| `"<your question>"` | Optional single-question input; if omitted, MassGen enters interactive chat mode. |
#### Configuration File Format
MassGen supports YAML configuration files with the following structure (All available quick configuration files can be found [here](massgen/configs)):
**Single Agent Configuration:**
Use the `agent` field to define a single agent with its backend and settings:
```yaml
agent:
id: "<agent_name>"
backend:
type: "claude" | "gemini" | "grok" | "openai" #Type of backend (Optional because we can infer backend type through model.)
model: "<model_name>" # Model name
api_key: "<optional_key>" # API key for backend. Uses env vars by default.
system_message: "..." # System Message for Single Agent
```
**Multi-Agent Configuration:**
Use the `agents` field to define multiple agents, each with its own backend and config:
```yaml
agents: # Multiple agents (alternative to 'agent')
- id: "<agent1 name>"
backend:
type: "claude" | "gemini" | "grok" | "openai" #Type of backend (Optional because we can infer backend type through model.)
model: "<model_name>" # Model name
api_key: "<optional_key>" # API key for backend. Uses env vars by default.
system_message: "..." # System Message for Single Agent
- id: "..."
backend:
type: "..."
model: "..."
...
system_message: "..."
```
**Backend Configuration:**
Detailed parameters for each agent's backend can be specified using the following configuration formats:
#### Claude
```yaml
backend:
type: "claude"
model: "claude-sonnet-4-20250514" # Model name
api_key: "<optional_key>" # API key for backend. Uses env vars by default.
temperature: 0.7 # Creativity vs consistency (0.0-1.0)
max_tokens: 2500 # Maximum response length
enable_web_search: true # Web search capability
enable_code_execution: true # Code execution capability
```
#### Gemini
```yaml
backend:
type: "gemini"
model: "gemini-2.5-flash" # Model name
api_key: "<optional_key>" # API key for backend. Uses env vars by default.
temperature: 0.7 # Creativity vs consistency (0.0-1.0)
max_tokens: 2500 # Maximum response length
enable_web_search: true # Web search capability
enable_code_execution: true # Code execution capability
```
#### Grok
```yaml
backend:
type: "grok"
model: "grok-3-mini" # Model name
api_key: "<optional_key>" # API key for backend. Uses env vars by default.
temperature: 0.7 # Creativity vs consistency (0.0-1.0)
max_tokens: 2500 # Maximum response length
enable_web_search: true # Web search capability
return_citations: true # Include search result citations
max_search_results: 10 # Maximum search results to use
search_mode: "auto" # Search strategy: "auto", "fast", "thorough"
```
#### OpenAI
```yaml
backend:
type: "openai"
model: "gpt-4o" # Model name
api_key: "<optional_key>" # API key for backend. Uses env vars by default.
temperature: 0.7 # Creativity vs consistency (0.0-1.0, o-series models don't support this)
max_tokens: 2500 # Maximum response length (o-series models don't support this)
enable_web_search: true # Web search capability
enable_code_interpreter: true # Code interpreter capability
```
**UI Configuration:**
Configure how MassGen displays information and handles logging during execution:
```yaml
ui:
display_type: "rich_terminal" | "terminal" | "simple" # Display format for agent interactions
logging_enabled: true | false # Enable/disable real-time logging
```
- `display_type`: Controls the visual presentation of agent interactions
- `"rich_terminal"`: Full-featured display with multi-region layout, live status updates, and colored output
- `"terminal"`: Standard terminal display with basic formatting and sequential output
- `"simple"`: Plain text output without any formatting or special display features
- `logging_enabled`: When `true`, saves detailed timestamp, agent outputs and system status
**Advanced Parameters:**
```yaml
# Global backend parameters
backend_params:
temperature: 0.7
max_tokens: 2000
enable_web_search: true # Web search capability (all backends)
enable_code_interpreter: true # OpenAI only
enable_code_execution: true # Gemini/Claude only
```
#### Interactive Multi-Turn Mode
MassGen supports an interactive mode where you can have ongoing conversations with the system:
```bash
# Start interactive mode with a single agent
uv run python -m massgen.cli --model gpt-4o-mini
# Start interactive mode with configuration file
uv run python -m massgen.cli --config three_agents_default.yaml
```
**Interactive Mode Features:**
- **Multi-turn conversations**: Multiple agents collaborate to chat with you in an ongoing conversation
- **Real-time feedback**: Displays real-time agent and system status
- **Clear conversation history**: Type `/clear` to reset the conversation and start fresh
- **Easy exit**: Type `/quit`, `/exit`, `/q`, or press `Ctrl+C` to stop
**Watch the recorded demo:**
[](https://www.youtube.com/watch?v=h1R7fxFJ0Zc)
### 5. 📊 View Results
The system provides multiple ways to view and analyze results:
#### Real-time Display
- **Live Collaboration View**: See agents working in parallel through a multi-region terminal display
- **Status Updates**: Real-time phase transitions, voting progress, and consensus building
- **Streaming Output**: Watch agents' reasoning and responses as they develop
**Watch an example here:**
[](https://www.youtube.com/watch?v=Dp2oldJJImw)
#### Comprehensive Logging
All sessions are automatically logged with detailed information. The file can be viewed throught the interaction with UI.
```bash
agent_outputs/
├── agent_1.txt # The full logs by agent 1
├── agent_2.txt # The full logs by agent 2
├── agent_3.txt # The full logs by agent 3
├── system_status.txt # The full logs of system status
```
---
## 💡 Examples
Here are a few examples of how you can use MassGen for different tasks:
### Case Studies
To see how MassGen works in practice, check out these detailed case studies based on real session logs:
- [**MassGen Case Studies**](docs/case_studies/index.md)
<!-- Uncomment when we add coding agent support -->
<!-- ### 1. 📝 Code Generation
```bash
uv run python cli.py --config examples/fast_config.yaml "Design a logo for MassGen (multi-agent scaling system for GenAI) GitHub README"
``` -->
### 1. ❓ Question Answering
```bash
# Ask a question about a complex topic
uv run python -m massgen.cli --config massgen/configs/gemini_4o_claude.yaml "what's best to do in Stockholm in October 2025"
uv run python -m massgen.cli --config massgen/configs/gemini_4o_claude.yaml "give me all the talks on agent frameworks in Berkeley Agentic AI Summit 2025, note, the sources must include the word Berkeley, don't include talks from any other agentic AI summits"
```
### 2. 🧠 Creative Writing
```bash
# Generate a short story
uv run python -m massgen.cli --config massgen/configs/gemini_4o_claude.yaml "Write a short story about a robot who discovers music."
```
### 3. Research
```bash
uv run python -m massgen.cli --config massgen/configs/gemini_4o_claude.yaml "How much does it cost to run HLE benchmark with Grok-4"
```
---
## 🗺️ Roadmap
MassGen is currently in its foundational stage, with a focus on parallel, asynchronous multi-agent collaboration and orchestration. Our roadmap is centered on transforming this foundation into a highly robust, intelligent, and user-friendly system, while enabling frontier research and exploration. An earlier version of MassGen can be found [here](./massgen/v1).
⚠️ **Early Stage Notice:** As MassGen is in active development, please expect upcoming breaking architecture changes as we continue to refine and improve the system.
### Key Future Enhancements:
- **Advanced Agent Collaboration:** Exploring improved communication patterns and consensus-building protocols to improve agent synergy.
- **Expanded Model, Tool & Agent Integration:** Adding support for more models/tools/agents, including a wider range of tools like MCP Servers, and coding agents.
- **Improved Performance & Scalability:** Optimizing the streaming and logging mechanisms for better performance and resource management.
- **Enhanced Developer Experience:** Introducing a more modular agent design and a comprehensive benchmarking framework for easier extension and evaluation.
- **Web Interface:** Developing a web-based UI for better visualization and interaction with the agent ecosystem.
We welcome community contributions to help us achieve these goals.
### v0.0.4 Roadmap
Version 0.0.4 focuses primarily on **Coding Agent Integration**, introducing Claude Code CLI and Gemini CLI as powerful coding agents. Key enhancements include:
- **Coding Agent Integration** (Required): Seamless integration of Claude Code CLI and Gemini CLI with coding-specific tools and workflows
- **Enhanced Backend Features** (Optional): Improved error handling, health monitoring, and support for additional model providers
- **Advanced CLI Features** (Optional): Conversation save/load functionality, templates, export formats, and better multi-turn display
For detailed milestones and technical specifications, see the [full v0.0.4 roadmap](ROADMAP_v0.0.4.md).
---
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
---
## 📄 License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
---
<div align="center">
**⭐ Star this repo if you find it useful! ⭐**
Made with ❤️ by the MassGen team
</div>
## ⭐ Star History
[](https://www.star-history.com/#Leezekun/MassGen&Date)
Raw data
{
"_id": null,
"home_page": null,
"name": "massgen",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, multi-agent, collaboration, orchestration, llm, claude, gemini, gpt, xai",
"author": null,
"author_email": "MassGen Team <contact@massgen.dev>",
"download_url": "https://files.pythonhosted.org/packages/d8/ab/7d31da7f6476218cfe520704af2d94e73f86278e46ede494ea18f534c897/massgen-0.0.3.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"assets/logo.png\" alt=\"MassGen Logo\" width=\"360\" />\n</p>\n\n<p align=\"center\">\n <a href=\"https://www.python.org/downloads/\">\n <img src=\"https://img.shields.io/badge/python-3.10+-blue.svg\" alt=\"Python 3.10+\" style=\"margin-right: 5px;\">\n </a>\n <a href=\"LICENSE\">\n <img src=\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\" alt=\"License\" style=\"margin-right: 5px;\">\n </a>\n <a href=\"https://discord.massgen.ai\">\n <img src=\"https://img.shields.io/discord/1153072414184452236?color=7289da&label=chat&logo=discord&style=flat-square\" alt=\"Join our Discord\">\n </a>\n</p>\n\n<h1 align=\"center\">\ud83d\ude80 MassGen: Multi-Agent Scaling System for GenAI</h1>\n\n<p align=\"center\">\n <i>MassGen is a cutting-edge multi-agent system that leverages the power of collaborative AI to solve complex tasks.</i>\n</p>\n\n<p align=\"center\">\n <a href=\"https://youtu.be/Dp2oldJJImw\">\n <img src=\"https://img.youtube.com/vi/Dp2oldJJImw/0.jpg\" alt=\"MassGen Demo Video\" width=\"600\">\n </a>\n</p>\n\n<p align=\"center\">\n <i>Multi-agent scaling through intelligent collaboration in Grok Heavy style</i>\n</p>\n\nMassGen is a cutting-edge multi-agent system that leverages the power of collaborative AI to solve complex tasks. It assigns a task to multiple AI agents who work in parallel, observe each other's progress, and refine their approaches to converge on the best solution to deliver a comprehensive and high-quality result. The power of this \"parallel study group\" approach is exemplified by advanced systems like xAI's Grok Heavy and Google DeepMind's Gemini Deep Think.\nThis project started with the \"threads of thought\" and \"iterative refinement\" ideas presented in [The Myth of Reasoning](https://docs.ag2.ai/latest/docs/blog/2025/04/16/Reasoning/), and extends the classic \"multi-agent conversation\" idea in [AG2](https://github.com/ag2ai/ag2). Here is a [video recording](https://www.youtube.com/watch?v=xM2Uguw1UsQ) of the background context introduction presented at the Berkeley Agentic AI Summit 2025.\n\n---\n\n## \ud83d\udccb Table of Contents\n\n<details open>\n<summary><h3>\u2728 Key Features</h3></summary>\n\n- [Cross-Model/Agent Synergy](#-key-features-1)\n- [Parallel Processing](#-key-features-1) \n- [Intelligence Sharing](#-key-features-1)\n- [Consensus Building](#-key-features-1)\n- [Live Visualization](#-key-features-1)\n</details>\n\n<details open>\n<summary><h3>\ud83c\udfd7\ufe0f System Design</h3></summary>\n\n- [System Architecture](#%EF%B8%8F-system-design-1)\n- [Parallel Processing](#%EF%B8%8F-system-design-1)\n- [Real-time Collaboration](#%EF%B8%8F-system-design-1)\n- [Convergence Detection](#%EF%B8%8F-system-design-1)\n- [Adaptive Coordination](#%EF%B8%8F-system-design-1)\n</details>\n\n<details open>\n<summary><h3>\ud83d\ude80 Quick Start</h3></summary>\n\n- [\ud83d\udce5 Installation](#1--installation)\n- [\ud83d\udd10 API Configuration](#2--api-configuration)\n- [\ud83e\udde9 Supported Models and Tools](#3--supported-models-and-tools)\n - [Models](#models)\n - [Tools](#tools)\n- [\ud83c\udfc3 Run MassGen](#4--run-massgen)\n - [Quick Test with A Single Model](#quick-test-with-a-single-model)\n - [Multiple Agents from Config](#multiple-agents-from-config)\n - [CLI Configuration Parameters](#cli-configuration-parameters)\n - [Configuration File Format](#configuration-file-format)\n - [Interactive Multi-Turn Mode](#interactive-multi-turn-mode)\n- [\ud83d\udcca View Results](#5--view-results)\n - [Real-time Display](#real-time-display)\n - [Comprehensive Logging](#comprehensive-logging)\n</details>\n\n<details open>\n<summary><h3>\ud83d\udca1 Examples</h3></summary>\n\n- [\ud83d\udcda Case Studies](#case-studies)\n- [\u2753 Question Answering](#1--question-answering)\n- [\ud83e\udde0 Creative Writing](#2--creative-writing)\n- [\ud83d\udd2c Research](#3-research)\n</details>\n\n<details open>\n<summary><h3>\ud83d\uddfa\ufe0f Roadmap</h3></summary>\n\n- [Key Future Enhancements](#key-future-enhancements)\n - Advanced Agent Collaboration\n - Expanded Model, Tool & Agent Integration\n - Improved Performance & Scalability\n - Enhanced Developer Experience\n - Web Interface\n- [v0.0.4 Roadmap](#v004-roadmap)\n</details>\n\n<details open>\n<summary><h3>\ud83d\udcda Additional Resources</h3></summary>\n\n- [\ud83e\udd1d Contributing](#-contributing)\n- [\ud83d\udcc4 License](#-license)\n- [\u2b50 Star History](#-star-history)\n</details>\n\n---\n\n## \u2728 Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **\ud83e\udd1d Cross-Model/Agent Synergy** | Harness strengths from diverse frontier model-powered agents |\n| **\u26a1 Parallel Processing** | Multiple agents tackle problems simultaneously |\n| **\ud83d\udc65 Intelligence Sharing** | Agents share and learn from each other's work |\n| **\ud83d\udd04 Consensus Building** | Natural convergence through collaborative refinement |\n| **\ud83d\udcca Live Visualization** | See agents' working processes in real-time |\n\n---\n\n## \ud83c\udfd7\ufe0f System Design\n\nMassGen operates through an architecture designed for **seamless multi-agent collaboration**:\n\n```mermaid\ngraph TB\n O[\ud83d\ude80 MassGen Orchestrator<br/>\ud83d\udccb Task Distribution & Coordination]\n\n subgraph Collaborative Agents\n A1[Agent 1<br/>\ud83c\udfd7\ufe0f Anthropic/Claude + Tools]\n A2[Agent 2<br/>\ud83c\udf1f Google/Gemini + Tools]\n A3[Agent 3<br/>\ud83e\udd16 OpenAI/GPT/O + Tools]\n A4[Agent 4<br/>\u26a1 xAI/Grok + Tools]\n end\n\n H[\ud83d\udd04 Shared Collaboration Hub<br/>\ud83d\udce1 Real-time Notification & Consensus]\n\n O --> A1 & A2 & A3 & A4\n A1 & A2 & A3 & A4 <--> H\n\n classDef orchestrator fill:#e1f5fe,stroke:#0288d1,stroke-width:3px\n classDef agent fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px\n classDef hub fill:#e8f5e8,stroke:#388e3c,stroke-width:2px\n\n class O orchestrator\n class A1,A2,A3,A4 agent\n class H hub\n```\n\nThe system's workflow is defined by the following key principles:\n\n**Parallel Processing** - Multiple agents tackle the same task simultaneously, each leveraging their unique capabilities (different models, tools, and specialized approaches).\n\n**Real-time Collaboration** - Agents continuously share their working summaries and insights through a notification system, allowing them to learn from each other's approaches and build upon collective knowledge.\n\n**Convergence Detection** - The system intelligently monitors when agents have reached stability in their solutions and achieved consensus through natural collaboration rather than forced agreement.\n\n**Adaptive Coordination** - Agents can restart and refine their work when they receive new insights from others, creating a dynamic and responsive problem-solving environment.\n\nThis collaborative approach ensures that the final output leverages collective intelligence from multiple AI systems, leading to more robust and well-rounded results than any single agent could achieve alone.\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### 1. \ud83d\udce5 Installation\n\n```bash\ngit clone https://github.com/Leezekun/MassGen.git\ncd MassGen\npip install uv\nuv venv\n```\n\n### 2. \ud83d\udd10 API Configuration\n\nCreate a `.env` file in the `massgen` directory with your API keys:\n\n```bash\n# Copy example configuration\ncp .env.example .env\n\n# Edit with your API keys\nANTHROPIC_API_KEY=your-anthropic-key-here\nGEMINI_API_KEY=your-gemini-key-here\nOPENAI_API_KEY=your-openai-key-here\nXAI_API_KEY=your-xai-key-here\n```\n\nMake sure you set up the API key for the model you want to use.\n\n**Useful links to get API keys:**\n - [Claude](https://docs.anthropic.com/en/api/overview)\n - [Gemini](https://ai.google.dev/gemini-api/docs)\n - [Grok](https://docs.x.ai/docs/overview)\n - [OpenAI](https://platform.openai.com/api-keys)\n\n### 3. \ud83e\udde9 Supported Models and Tools\n\n#### Models\n\nThe system currently supports four model providers with advanced reasoning capabilities: **Anthropic Claude**, **Google Gemini**, **OpenAI**, **xAI Grok**. \nMore providers and local inference of open-weight models (using vllm or sglang) are welcome to be added.\n\n#### Tools\n\nMassGen agents can leverage various tools to enhance their problem-solving capabilities. `Claude`, `Gemini`, and `OpenAI` models support built-in web search and code execution. `Grok` supports web search as well, but it does not currently offer native code execution at the model level.\n\n**Supported Built-in Tools by Models:**\n\n| Backend | Live Search | Code Execution |\n|---------|:-----------:|:--------------:|\n| **Claude** | \u2705 | \u2705 |\n| **OpenAI** | \u2705 | \u2705 |\n| **Grok** | \u2705 | \u274c |\n| **Gemini** | \u2705 | \u2705 |\n\n### 4. \ud83c\udfc3 Run MassGen\n\n#### Quick Test with A Single Model\n\n```bash\nuv run python -m massgen.cli --model gemini-2.5-flash \"Which AI won IMO in 2025?\"\nuv run python -m massgen.cli --model gpt-4o-mini \"Which AI won IMO in 2025?\"\nuv run python -m massgen.cli --model grok-3-mini \"Which AI won IMO in 2025?\"\n```\n\nAll supported models can be found [here](massgen/utils.py).\n\n#### Multiple Agents from Config\n```bash\n# Use configuration file\nuv run python -m massgen.cli --config three_agents_default.yaml \"Compare different approaches to renewable energy\"\n```\n\nAll available quick configuration files can be found [here](massgen/configs).\n\n#### CLI Configuration Parameters\n\n| Parameter | Description |\n|-------------------|-------------|\n| `--config` | Path to YAML configuration file with agent definitions, model parameters, backend parameters and UI settings |\n| `--backend` | Backend type for quick setup without a config file (`claude`, `gemini`, `grok` or `openai`). Optional because we can infer backend type through model.|\n| `--model` | Model name for quick setup (e.g., `gpt-4o-mini`, `claude-sonnet-4-20250514`, ...). See all [supported models](massgen/utils.py). `--config` and `--model` are mutually exclusive - use one or the other. |\n| `--system-message` | System prompt for the agent in quick setup mode. If `--config` is provided, `--system-message` is omitted. |\n| `--no-display` | Disable real-time streaming UI coordination display (fallback to simple text output).|\n| `--no-logs` | Disable real-time logging.|\n| `\"<your question>\"` | Optional single-question input; if omitted, MassGen enters interactive chat mode. |\n\n#### Configuration File Format\n\nMassGen supports YAML configuration files with the following structure (All available quick configuration files can be found [here](massgen/configs)):\n\n**Single Agent Configuration:**\n\nUse the `agent` field to define a single agent with its backend and settings:\n\n```yaml\nagent: \n id: \"<agent_name>\"\n backend:\n type: \"claude\" | \"gemini\" | \"grok\" | \"openai\" #Type of backend (Optional because we can infer backend type through model.)\n model: \"<model_name>\" # Model name\n api_key: \"<optional_key>\" # API key for backend. Uses env vars by default.\n system_message: \"...\" # System Message for Single Agent\n```\n\n**Multi-Agent Configuration:**\n\nUse the `agents` field to define multiple agents, each with its own backend and config:\n\n```yaml\nagents: # Multiple agents (alternative to 'agent')\n - id: \"<agent1 name>\"\n backend: \n type: \"claude\" | \"gemini\" | \"grok\" | \"openai\" #Type of backend (Optional because we can infer backend type through model.)\n model: \"<model_name>\" # Model name\n api_key: \"<optional_key>\" # API key for backend. Uses env vars by default.\n system_message: \"...\" # System Message for Single Agent\n - id: \"...\"\n backend:\n type: \"...\"\n model: \"...\"\n ...\n system_message: \"...\"\n```\n\n**Backend Configuration:**\n\nDetailed parameters for each agent's backend can be specified using the following configuration formats:\n\n#### Claude\n\n```yaml\nbackend:\n type: \"claude\"\n model: \"claude-sonnet-4-20250514\" # Model name\n api_key: \"<optional_key>\" # API key for backend. Uses env vars by default.\n temperature: 0.7 # Creativity vs consistency (0.0-1.0)\n max_tokens: 2500 # Maximum response length\n enable_web_search: true # Web search capability\n enable_code_execution: true # Code execution capability\n```\n\n#### Gemini\n\n```yaml\nbackend:\n type: \"gemini\"\n model: \"gemini-2.5-flash\" # Model name\n api_key: \"<optional_key>\" # API key for backend. Uses env vars by default.\n temperature: 0.7 # Creativity vs consistency (0.0-1.0)\n max_tokens: 2500 # Maximum response length\n enable_web_search: true # Web search capability\n enable_code_execution: true # Code execution capability\n```\n\n#### Grok\n\n```yaml\nbackend:\n type: \"grok\"\n model: \"grok-3-mini\" # Model name\n api_key: \"<optional_key>\" # API key for backend. Uses env vars by default.\n temperature: 0.7 # Creativity vs consistency (0.0-1.0)\n max_tokens: 2500 # Maximum response length\n enable_web_search: true # Web search capability\n return_citations: true # Include search result citations\n max_search_results: 10 # Maximum search results to use \n search_mode: \"auto\" # Search strategy: \"auto\", \"fast\", \"thorough\" \n```\n\n#### OpenAI\n\n```yaml\nbackend:\n type: \"openai\"\n model: \"gpt-4o\" # Model name\n api_key: \"<optional_key>\" # API key for backend. Uses env vars by default.\n temperature: 0.7 # Creativity vs consistency (0.0-1.0, o-series models don't support this)\n max_tokens: 2500 # Maximum response length (o-series models don't support this)\n enable_web_search: true # Web search capability\n enable_code_interpreter: true # Code interpreter capability\n```\n\n**UI Configuration:**\n\nConfigure how MassGen displays information and handles logging during execution:\n\n```yaml\nui:\n display_type: \"rich_terminal\" | \"terminal\" | \"simple\" # Display format for agent interactions\n logging_enabled: true | false # Enable/disable real-time logging \n```\n\n- `display_type`: Controls the visual presentation of agent interactions\n - `\"rich_terminal\"`: Full-featured display with multi-region layout, live status updates, and colored output\n - `\"terminal\"`: Standard terminal display with basic formatting and sequential output\n - `\"simple\"`: Plain text output without any formatting or special display features\n- `logging_enabled`: When `true`, saves detailed timestamp, agent outputs and system status\n\n**Advanced Parameters:**\n```yaml\n# Global backend parameters\nbackend_params:\n temperature: 0.7\n max_tokens: 2000\n enable_web_search: true # Web search capability (all backends)\n enable_code_interpreter: true # OpenAI only\n enable_code_execution: true # Gemini/Claude only\n```\n\n#### Interactive Multi-Turn Mode\n\nMassGen supports an interactive mode where you can have ongoing conversations with the system:\n\n```bash\n# Start interactive mode with a single agent\nuv run python -m massgen.cli --model gpt-4o-mini\n\n# Start interactive mode with configuration file\nuv run python -m massgen.cli --config three_agents_default.yaml\n```\n\n**Interactive Mode Features:**\n- **Multi-turn conversations**: Multiple agents collaborate to chat with you in an ongoing conversation\n- **Real-time feedback**: Displays real-time agent and system status\n- **Clear conversation history**: Type `/clear` to reset the conversation and start fresh\n- **Easy exit**: Type `/quit`, `/exit`, `/q`, or press `Ctrl+C` to stop\n\n**Watch the recorded demo:**\n\n[](https://www.youtube.com/watch?v=h1R7fxFJ0Zc)\n\n### 5. \ud83d\udcca View Results\n\nThe system provides multiple ways to view and analyze results:\n\n#### Real-time Display\n- **Live Collaboration View**: See agents working in parallel through a multi-region terminal display\n- **Status Updates**: Real-time phase transitions, voting progress, and consensus building\n- **Streaming Output**: Watch agents' reasoning and responses as they develop\n\n**Watch an example here:**\n\n[](https://www.youtube.com/watch?v=Dp2oldJJImw)\n\n#### Comprehensive Logging\nAll sessions are automatically logged with detailed information. The file can be viewed throught the interaction with UI.\n\n```bash\nagent_outputs/\n \u251c\u2500\u2500 agent_1.txt # The full logs by agent 1\n \u251c\u2500\u2500 agent_2.txt # The full logs by agent 2\n \u251c\u2500\u2500 agent_3.txt # The full logs by agent 3\n \u251c\u2500\u2500 system_status.txt # The full logs of system status\n```\n---\n\n## \ud83d\udca1 Examples\n\nHere are a few examples of how you can use MassGen for different tasks:\n\n### Case Studies\n\nTo see how MassGen works in practice, check out these detailed case studies based on real session logs:\n\n- [**MassGen Case Studies**](docs/case_studies/index.md)\n\n<!-- Uncomment when we add coding agent support -->\n<!-- ### 1. \ud83d\udcdd Code Generation\n\n```bash\nuv run python cli.py --config examples/fast_config.yaml \"Design a logo for MassGen (multi-agent scaling system for GenAI) GitHub README\"\n``` -->\n\n### 1. \u2753 Question Answering\n\n```bash\n# Ask a question about a complex topic\nuv run python -m massgen.cli --config massgen/configs/gemini_4o_claude.yaml \"what's best to do in Stockholm in October 2025\"\n\nuv run python -m massgen.cli --config massgen/configs/gemini_4o_claude.yaml \"give me all the talks on agent frameworks in Berkeley Agentic AI Summit 2025, note, the sources must include the word Berkeley, don't include talks from any other agentic AI summits\"\n```\n\n### 2. \ud83e\udde0 Creative Writing\n\n```bash\n# Generate a short story\nuv run python -m massgen.cli --config massgen/configs/gemini_4o_claude.yaml \"Write a short story about a robot who discovers music.\"\n```\n\n### 3. Research\n```bash\nuv run python -m massgen.cli --config massgen/configs/gemini_4o_claude.yaml \"How much does it cost to run HLE benchmark with Grok-4\"\n```\n\n---\n\n## \ud83d\uddfa\ufe0f Roadmap\n\nMassGen is currently in its foundational stage, with a focus on parallel, asynchronous multi-agent collaboration and orchestration. Our roadmap is centered on transforming this foundation into a highly robust, intelligent, and user-friendly system, while enabling frontier research and exploration. An earlier version of MassGen can be found [here](./massgen/v1).\n\n\u26a0\ufe0f **Early Stage Notice:** As MassGen is in active development, please expect upcoming breaking architecture changes as we continue to refine and improve the system.\n\n### Key Future Enhancements:\n\n- **Advanced Agent Collaboration:** Exploring improved communication patterns and consensus-building protocols to improve agent synergy.\n- **Expanded Model, Tool & Agent Integration:** Adding support for more models/tools/agents, including a wider range of tools like MCP Servers, and coding agents.\n- **Improved Performance & Scalability:** Optimizing the streaming and logging mechanisms for better performance and resource management.\n- **Enhanced Developer Experience:** Introducing a more modular agent design and a comprehensive benchmarking framework for easier extension and evaluation.\n- **Web Interface:** Developing a web-based UI for better visualization and interaction with the agent ecosystem.\n\nWe welcome community contributions to help us achieve these goals.\n\n### v0.0.4 Roadmap\n\nVersion 0.0.4 focuses primarily on **Coding Agent Integration**, introducing Claude Code CLI and Gemini CLI as powerful coding agents. Key enhancements include:\n\n- **Coding Agent Integration** (Required): Seamless integration of Claude Code CLI and Gemini CLI with coding-specific tools and workflows\n- **Enhanced Backend Features** (Optional): Improved error handling, health monitoring, and support for additional model providers\n- **Advanced CLI Features** (Optional): Conversation save/load functionality, templates, export formats, and better multi-turn display\n\nFor detailed milestones and technical specifications, see the [full v0.0.4 roadmap](ROADMAP_v0.0.4.md).\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n---\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n---\n\n<div align=\"center\">\n\n**\u2b50 Star this repo if you find it useful! \u2b50**\n\nMade with \u2764\ufe0f by the MassGen team\n\n</div>\n\n## \u2b50 Star History\n\n[](https://www.star-history.com/#Leezekun/MassGen&Date)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Multi-Agent Scaling System - A powerful framework for collaborative AI",
"version": "0.0.3",
"project_urls": {
"Bug Reports": "https://github.com/Leezekun/MassGen/issues",
"Documentation": "https://github.com/Leezekun/MassGen/blob/main/README.md",
"Homepage": "https://github.com/Leezekun/MassGen",
"Repository": "https://github.com/Leezekun/MassGen",
"Source": "https://github.com/Leezekun/MassGen"
},
"split_keywords": [
"ai",
" multi-agent",
" collaboration",
" orchestration",
" llm",
" claude",
" gemini",
" gpt",
" xai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "17cc15000c2270c685bb9656c55d19bbee199b44c7c4603e8e8ccc35f1ece5b1",
"md5": "efa3bc2ce7cb2fa2a15ff70c6911c239",
"sha256": "e2ced7febe0597eda04b3ed2895516c79d2d18c250b460a0d2c1b8857db1b00f"
},
"downloads": -1,
"filename": "massgen-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "efa3bc2ce7cb2fa2a15ff70c6911c239",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 244100,
"upload_time": "2025-08-05T05:09:42",
"upload_time_iso_8601": "2025-08-05T05:09:42.690723Z",
"url": "https://files.pythonhosted.org/packages/17/cc/15000c2270c685bb9656c55d19bbee199b44c7c4603e8e8ccc35f1ece5b1/massgen-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d8ab7d31da7f6476218cfe520704af2d94e73f86278e46ede494ea18f534c897",
"md5": "dacab17937737fbb7925b9788208dfd7",
"sha256": "574a75c4582736c4507b2cb9115cf814daee676aaed4fe61cc8c08b21c7fe201"
},
"downloads": -1,
"filename": "massgen-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "dacab17937737fbb7925b9788208dfd7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 215333,
"upload_time": "2025-08-05T05:09:43",
"upload_time_iso_8601": "2025-08-05T05:09:43.860841Z",
"url": "https://files.pythonhosted.org/packages/d8/ab/7d31da7f6476218cfe520704af2d94e73f86278e46ede494ea18f534c897/massgen-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 05:09:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Leezekun",
"github_project": "MassGen",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "datasets",
"specs": [
[
"==",
"3.2.0"
]
]
},
{
"name": "openai",
"specs": [
[
"==",
"1.71.0"
]
]
},
{
"name": "xai-sdk",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "anthropic",
"specs": [
[
"==",
"0.49.0"
]
]
},
{
"name": "nest-asyncio",
"specs": [
[
"==",
"1.6.0"
]
]
},
{
"name": "wcwidth",
"specs": [
[
">=",
"0.2.5"
]
]
},
{
"name": "google-genai",
"specs": [
[
">=",
"1.27.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "rich",
"specs": [
[
"==",
"13.7.0"
]
]
}
],
"lcname": "massgen"
}
JSON
