============
Installation
============

Prerequisites
=============

MassGen requires **Python 3.11 or higher**. You can check your Python version with:

.. code-block:: bash

   python --version

If you need to install or upgrade Python, visit `python.org/downloads <https://www.python.org/downloads/>`_.

Quick Start Installation
========================

**Method 1: PyPI Installation** (Recommended)
----------------------------------------------

The easiest way to get started with MassGen is via pip or uv:

.. code-block:: bash

   # Install MassGen with uv (recommended - faster)
   uv pip install massgen

   # Or with pip
   pip install massgen

Getting Started - Complete First-Run Flow
------------------------------------------

**Quickstart Setup** (Fastest way to get running):

.. code-block:: bash

   # Step 1: Set up API keys, Docker, and skills
   uv run massgen --setup

   # Step 2: Create a simple config and start
   uv run massgen --quickstart

**What ``--setup`` does:**

* Configures your API keys (OpenAI, Anthropic, Google, xAI)
* Offers to set up Docker images for code execution
* Offers to install skills (openskills, Anthropic collection)

**What ``--quickstart`` does:**

* Asks how many agents you want (1-5, default 3)
* Asks which backend/model for each agent (or same for all)
* Auto-detects Docker availability and configures execution mode
* Creates a ready-to-use config and launches into interactive mode

**After first-run setup:**

.. code-block:: bash

   # Start conversation with your default config
   massgen

   # Or run a single query
   massgen "Your question here"

.. tip::
   **The entire flow takes 1-2 minutes.** You'll be in an interactive conversation with your agents immediately after setup!

**Alternative: Full Setup Wizard**

For more control over configuration, use the full wizard:

.. code-block:: bash

   massgen --init

This guides you through:

1. **Choose Your Configuration**

   * **📦 Browse ready-to-use configs/examples** - Select from 100+ pre-built configurations
   * **Build from template** - Create custom agents with guided setup (Simple Q&A, Research & Analysis, Code & Files, etc.)

2. **Save as Default** (optional)

   * When browsing existing configs or examples, you'll be asked: "Save this as your default config?"
   * Choose **Yes** to use it automatically on future ``massgen`` runs
   * Choose **No** to try it once without saving

3. **Start Chatting Immediately**

   * After selection, you're **launched directly into interactive mode**
   * Multi-turn conversation with your chosen configuration

Supported API Key Providers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Main backends:**

* OpenAI, Anthropic (Claude), Google Gemini, xAI (Grok)
* Azure OpenAI

**ChatCompletion providers:**

* Cerebras AI, Together AI, Fireworks AI, Groq, Nebius AI Studio, OpenRouter
* ZAI (Zhipu.ai), Kimi/Moonshot AI, POE, Qwen (Alibaba)

.. note::
   You can skip all providers if you're using local models (vLLM, Ollama, etc.) which don't require API keys.

Manual API Key Setup (Optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you prefer to set up API keys manually before running MassGen:

.. code-block:: bash

   # Unix/Mac: Create the .env file
   mkdir -p ~/.config/massgen
   vim ~/.config/massgen/.env

   # Windows: Create the .env file
   mkdir %USERPROFILE%\.config\massgen
   notepad %USERPROFILE%\.config\massgen\.env

   # Add your API keys (same format for all platforms)
   OPENAI_API_KEY=sk-your-key-here
   ANTHROPIC_API_KEY=sk-ant-your-key
   GEMINI_API_KEY=your-gemini-key
   XAI_API_KEY=xai-your-key

**Complete API Key Reference:**

.. code-block:: bash

   # Main backends
   OPENAI_API_KEY=sk-...
   ANTHROPIC_API_KEY=sk-ant-...
   GEMINI_API_KEY=...
   XAI_API_KEY=xai-...

   # Azure
   AZURE_OPENAI_API_KEY=...
   AZURE_OPENAI_ENDPOINT=...

   # ChatCompletion providers
   CEREBRAS_API_KEY=...
   TOGETHER_API_KEY=...
   FIREWORKS_API_KEY=...
   GROQ_API_KEY=...
   NEBIUS_API_KEY=...
   OPENROUTER_API_KEY=...
   ZAI_API_KEY=...
   MOONSHOT_API_KEY=...        # Also accepts KIMI_API_KEY
   POE_API_KEY=...
   QWEN_API_KEY=...

MassGen API Key Lookup Order
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

MassGen looks for API keys in this order:

1. Environment variables (``OPENAI_API_KEY``, ``ANTHROPIC_API_KEY``, etc.)
2. ``~/.config/massgen/.env`` (user config - recommended)
3. Project-specific ``.env`` file in current directory (highest priority)

Reconfiguring API Keys
~~~~~~~~~~~~~~~~~~~~~~~

You can re-run the API key wizard anytime:

.. code-block:: bash

   # Launch API key setup
   massgen --setup

First-Run Setup Flow Walkthrough
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When you run ``massgen`` for the first time, here's what you'll see:

.. code-block:: text

   ╔══════════════════════════════════════════════════════════╗
   ║             👋  Welcome to MassGen!                      ║
   ╚══════════════════════════════════════════════════════════╝

   ✅ API keys detected

   Let's set up your default configuration...

   Step 1 of 4: Select Your Use Case

   Browse ready-to-use configs, or pick a template to build your own.

 » 📦  Browse ready-to-use configs / examples

   ─ or build from template ─

   ⚙️  Custom Configuration           [Choose your own tools]
   💬  Simple Q&A                     [Basic chat (no special tools)]
   🔍  Research & Analysis            [Web search enabled]
   💻  Code & Files                   [File ops + code execution]
   🐳  Code & Files (Docker)          [File ops + isolated Docker execution]
   📊  Data Analysis                  [Files + code + image analysis]
   🎨  Multimodal Analysis            [Images, audio, video understanding]

**Option 1: Browse Ready-to-Use Configs** (Fastest)

Select this to browse 100+ pre-built configurations organized by category:

.. code-block:: text

   📦  Browse ready-to-use configs / examples

   ┌─────────────────────────────────────────────────────────┐
   │ 👤 Your Configs                    1                    │
   │ 📂 Project Configs                 0                    │
   │ 📂 Current Directory               2                    │
   │ 📦 Package Examples                107                  │
   └─────────────────────────────────────────────────────────┘

   Select a configuration:
   » three_agents_default.yaml  (3 agents, diverse perspectives)
     research_team.yaml          (Web search + analysis)
     coding_assistant.yaml       (File ops + code execution)

After selecting, you'll be asked:

.. code-block:: text

   📦 You selected a package example
      /path/to/massgen/configs/basic/multi/three_agents_default.yaml

   Save this as your default config? [y/N]:

* Choose **y** to save and use automatically on future runs
* Choose **n** to try it once without saving

Then immediately launches into interactive mode! 🚀

**Option 2: Build from Template** (Customized)

Select a template to create a custom configuration with guided setup:

.. code-block:: text

   🔍  Research & Analysis            [Web search enabled]

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     Step 2 of 4: Agent Setup
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

   Available providers:
   • ✅ OpenAI - gpt-5, gpt-5-mini, gpt-5-nano...
   • ✅ Claude - claude-sonnet-4, claude-opus-4...
   • ✅ Gemini - gemini-2.5-flash, gemini-2.5-pro...

   How many agents? 3 agents (recommended)
   Select provider: OpenAI
   Select models: gpt-5-mini, gpt-5-mini, gpt-5-mini

   ✅ Configuration saved to: ~/.config/massgen/config.yaml

   🚀 Launching interactive mode...

Your configuration is saved to ``~/.config/massgen/config.yaml`` and will be used for all future runs.

Available Build Templates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The wizard offers several **preset configurations** that auto-configure tools and capabilities for common use cases:

**Custom Configuration**
  Full flexibility to choose any combination of agents, models, and tools. You'll configure everything manually.
  * Choose your own tools
  * Use for: Specialized workflows with specific requirements

**Simple Q&A**
  Basic question answering with multiple perspectives. No special tools configured.
  * Multiple agents provide diverse perspectives and cross-verification
  * Use for: General questions, discussions, brainstorming

**Research & Analysis** *(Auto-configured)*
  * ✓ **Web Search**: Real-time internet search for current information, fact-checking, and source verification
  * ✓ **Multi-Agent Collaboration**: 3 agents recommended for diverse perspectives and cross-verification
  * Available for: OpenAI, Claude, Gemini, Grok
  * Use for: Research queries, current events, fact-checking, comparative analysis

**Code & Files** *(Auto-configured)*
  * ✓ **Filesystem Access**: File read/write operations in isolated workspace
  * ✓ **Code Execution**: OpenAI Code Interpreter or Claude/Gemini native code execution
  * Claude Code recommended for best filesystem support
  * Use for: Code generation, refactoring, testing, file operations

**Code & Files (Docker)** *(Auto-configured)*
  * ✓ **Filesystem Access**: File read/write operations
  * ✓ **Code Execution**: Backend-native code execution
  * ✓ **Docker Isolation**: Fully isolated container execution via MCP, persistent packages, network controls
  * ⚠️ **Setup Required**: Docker Engine 28.0.0+, docker Python library, and massgen-executor image (see massgen/docker/README.md)
  * Use for: Secure code execution with full isolation and persistent dependencies

**Data Analysis** *(Auto-configured)*
  * ✓ **Filesystem Access**: Read/write data files (CSV, JSON, etc.), save visualizations
  * ✓ **Code Execution**: Data processing, transformation, statistical analysis, visualization generation
  * ✓ **Image Understanding**: Analyze charts, graphs, and visualizations; extract data from images
  * Available for: OpenAI, Claude Code, Gemini, Azure OpenAI
  * Use for: Data analysis, chart interpretation, statistical processing, visualization

**Multimodal Analysis** *(Auto-configured)*
  * ✓ **Image Understanding**: Analyze images, screenshots, charts; OCR and text extraction
    * Available for: OpenAI, Claude Code, Gemini, Azure OpenAI
  * ✓ **Audio Understanding**: Transcribe and analyze audio (where supported)
    * Available for: Claude, ChatCompletion
  * ✓ **Video Understanding**: Analyze video content (where supported)
    * Available for: Claude, ChatCompletion, OpenAI
  * Note: Different backends support different modalities
  * Use for: Image analysis, screenshot interpretation, multimedia content analysis

.. note::
   Presets marked *(Auto-configured)* automatically enable specific tools and capabilities during setup. You can still customize further if needed.

Quick Usage Examples
~~~~~~~~~~~~~~~~~~~

After setup, using MassGen is simple:

.. code-block:: bash

   # Use your default configuration
   massgen "What is quantum computing?"

   # Override with a specific model for this query
   massgen --model gpt-5-mini "Quick question"

   # Use a pre-built example configuration
   massgen --config @examples/basic/multi/three_agents_default "Compare renewable energy sources"

   # Start interactive multi-turn mode
   massgen

Example Configurations
~~~~~~~~~~~~~~~~~~~~~~

MassGen ships with ready-to-use example configurations:

.. code-block:: bash

   # List all available examples
   massgen --list-examples

   # Use an example configuration
   massgen --config @examples/basic/single/single_gpt5nano "Your question"
   massgen --config @examples/research_team "Research query"

   # Copy an example to customize
   massgen --example basic_multi > my-config.yaml

See :doc:`configuration` for more details on customizing configurations.

**Method 2: Development Installation** (For Developers)
-------------------------------------------------------

If you want to contribute to MassGen or customize the source code:

.. code-block:: bash

   # Clone the repository
   git clone https://github.com/Leezekun/MassGen.git
   cd MassGen

   # Install in editable mode
   pip install -e .

   # Or with uv (faster)
   pip install uv
   uv pip install -e .

**Automated Development Setup** (Unix/Linux/macOS)

For a complete development environment setup including dependencies, skills, and Docker images:

.. code-block:: bash

   # Full automated setup
   ./scripts/init.sh

   # Or just install skills (Anthropic + Crawl4AI)
   ./scripts/init_skills.sh

The ``init.sh`` script will:

- ✓ Check system requirements (Python 3.11+, Node.js, Docker)
- ✓ Install uv package manager
- ✓ Install Python dependencies (``uv sync``)
- ✓ Install npm global packages (openskills, semtools, Claude Code CLI, Gemini CLI)
- ✓ Install skills (Anthropic collection + Crawl4AI)
- ✓ Build Docker runtime images (standard + sudo variants)
- ✓ Setup ``.env`` file from template
- ✓ Verify installation

**Script Options:**

.. code-block:: bash

   # Skip Docker builds (saves time)
   ./scripts/init.sh --skip-docker

   # Skip skills installation
   ./scripts/init.sh --skip-skills

   # Skip npm package installation
   ./scripts/init.sh --skip-npm

   # Show help
   ./scripts/init.sh --help

.. note::
   **Windows Support:** Windows support for init scripts is planned for a future release. Windows users should follow the manual installation steps for each component listed above.

Development installation gives you:

- 🔄 **Live changes**: Edits are immediately reflected
- 🛠️ **Full source access**: Modify any part of MassGen
- 📦 **All features**: Same as pip install, but with source code

**Using uv tool for Multi-Turn Sessions**

For the best experience with multi-turn conversations and working across different project directories, install MassGen as a uv tool:

.. code-block:: bash

   # Install as a global uv tool (from MassGen directory)
   cd MassGen
   uv tool install -e .

   # Now you can use massgen from anywhere
   cd ~/your-project
   massgen  # Start interactive multi-turn session

   # Sessions are saved to .massgen/sessions/ in your current directory
   # Context is preserved across turns automatically

**Benefits of uv tool for multi-turn:**

- 🌍 **Global Access**: Run ``massgen`` from any directory
- 💬 **Session Isolation**: Each project gets its own ``.massgen/sessions/`` directory
- 📁 **Clean Workspaces**: Sessions and workspaces stay organized per-project
- 🔄 **Live Updates**: Changes to MassGen source are immediately available (editable mode)

See :doc:`../user_guide/multi_turn_mode` for complete multi-turn conversation documentation.

Using MassGen After Installation
=================================

After installing via either method, you can use MassGen in several ways:

Command Line Interface
----------------------

.. code-block:: bash

   # Single query with default config
   massgen "Your question"

   # Interactive multi-turn mode
   massgen

   # Quick single-agent mode
   massgen --model gemini-2.5-flash "Quick question"

   # Use example configuration
   massgen --config @examples/basic/multi/three_agents_default "Complex question"

   # Use custom configuration file
   massgen --config ./my-agents.yaml "Your question"

Python API
----------

MassGen provides a simple async Python API:

.. code-block:: python

   import asyncio
   import massgen

   # Quick single-agent query
   result = await massgen.run(
       query="What is machine learning?",
       model="gpt-5-mini"
   )
   print(result['final_answer'])

   # Multi-agent with configuration
   result = await massgen.run(
       query="Analyze climate change trends",
       config="@examples/research_team"
   )

   # Or from sync code
   result = asyncio.run(
       massgen.run("Question", model="gemini-2.5-flash")
   )

See :doc:`../reference/python_api` for complete API documentation.

Configuration Management
========================

Configuration Files Location
----------------------------

MassGen uses the following directory structure:

.. code-block:: text

   ~/.config/massgen/                        # Windows: %USERPROFILE%\.config\massgen\
   ├── config.yaml              # Your default configuration (from wizard)
   ├── agents/                  # Your custom named configurations
   │   ├── research-team.yaml
   │   └── coding-agents.yaml
   └── .env                     # API keys (optional)

The ``config.yaml`` file is created by the setup wizard and used by default when you run ``massgen`` without specifying a config.

Reconfiguring MassGen
----------------------

You can re-run the setup wizard anytime:

.. code-block:: bash

   # Launch configuration wizard
   massgen --init

   # This will:
   # - Let you create a new default config (overwrites existing)
   # - Or save as a named config in ~/.config/massgen/agents/ (Windows: %USERPROFILE%\.config\massgen\agents\)

Understanding the .massgen Directory
=====================================

MassGen organizes all its working files in a ``.massgen/`` directory within your project. This keeps your project clean and makes it easy to exclude MassGen files from version control by adding ``.massgen/`` to your ``.gitignore``.

**What's inside?**

- ``sessions/`` - Multi-turn conversation history
- ``workspaces/`` - Agent working directories for file operations
- ``snapshots/`` - Workspace snapshots shared between agents
- ``temp_workspaces/`` - Previous turn results for context

**When is it created?**

The ``.massgen/`` directory is automatically created when you use multi-turn mode, file operations, or workspace features. Simple single-agent queries don't create it.

.. seealso::
   For a complete explanation of workspace management and directory structure, see :doc:`../user_guide/concepts` (State Management & .massgen Directory section)

Optional Dependencies
=====================

AG2 Framework Integration
--------------------------

If you want to use AG2 agents alongside native MassGen agents:

.. code-block:: bash

   pip install massgen[external]

This is **only required** if you plan to use AG2 configuration files.

Docker Image Setup
==================

MassGen uses Docker containers for secure code execution. The Docker images provide a sandboxed environment where agents can safely run code, install packages, and execute shell commands.

Install Docker Images via CLI
------------------------------

The easiest way to set up Docker images is using the built-in command:

.. code-block:: bash

   # Pull Docker images from GitHub Container Registry
   uv run massgen --setup-docker

This will pull:

- **ghcr.io/massgen/mcp-runtime:latest** - Standard runtime image
- **ghcr.io/massgen/mcp-runtime-sudo:latest** - Runtime with sudo support

.. note::
   The ``--setup`` command will offer to run ``--setup-docker`` for you automatically.

**Prerequisites:**

- Docker Desktop or Docker Engine must be installed and running
- On macOS/Linux: ``docker info`` should work without sudo
- On Windows: Docker Desktop must be running

**Verifying Docker Setup:**

.. code-block:: bash

   # Check Docker is running
   docker info

   # Check MassGen images are available
   docker images | grep massgen

You should see both ``mcp-runtime`` and ``mcp-runtime-sudo`` images listed.

**When is Docker needed?**

Docker is required when using:

- ``command_line_execution_mode: docker`` in your config
- Code-based tools with Docker isolation
- The ``--quickstart`` command with Docker execution mode

If Docker isn't available, ``--quickstart`` will automatically configure local execution mode (more restricted but still functional).

Skills Installation
===================

Skills enhance MassGen with additional capabilities like semantic search, LSP-based code understanding, and web scraping. You can install skills after setting up MassGen.

Install Skills via CLI (Recommended)
-------------------------------------

The easiest way to install skills is using the built-in command (works on all platforms):

.. code-block:: bash

   # Install skills automatically
   massgen --setup-skills

This will install:

- **openskills CLI** - npm package for managing skills
- **Anthropic skills collection** - Official Claude Code and Gemini CLI skills
- **Crawl4AI skill** - Web scraping and content extraction

The command works on **Windows, macOS, and Linux** and handles all dependencies automatically.

Manual Skills Installation
---------------------------

If you prefer to install skills manually or need specific skills:

.. code-block:: bash

   # Install openskills CLI
   npm install -g openskills

   # Install Anthropic skills collection
   openskills install anthropics/skills --universal -y

   # Skills are installed to ~/.agent/skills/

Development Scripts (Unix/macOS/Linux)
---------------------------------------

For development installations, bash scripts are available that provide additional setup:

.. code-block:: bash

   # Full development setup (dependencies, skills, Docker)
   ./scripts/init.sh

   # Just install skills
   ./scripts/init_skills.sh

   # With options
   ./scripts/init.sh --skip-docker  # Skip Docker image builds
   ./scripts/init.sh --help         # Show all options

.. note::
   The bash scripts are Unix-only. Windows users should use ``massgen --setup-skills`` instead.

Verifying Skills Installation
------------------------------

Check that skills are installed correctly:

.. code-block:: bash

   # List installed skills
   ls ~/.agent/skills/

   # On Windows
   dir %USERPROFILE%\.agent\skills\

You should see directories for each installed skill (e.g., ``pdf``, ``xlsx``, ``crawl4ai``).

Optional CLI Tools
==================

Enhanced Capabilities
---------------------

Install these optional tools for enhanced MassGen capabilities:

Claude Code CLI
~~~~~~~~~~~~~~~

Advanced coding assistant with comprehensive development tools:

.. code-block:: bash

   npm install -g @anthropic-ai/claude-code

LM Studio
~~~~~~~~~

Local model inference for running open-weight models:

**For MacOS/Linux:**

.. code-block:: bash

   sudo ~/.lmstudio/bin/lms bootstrap

**For Windows:**

.. code-block:: bash

   cmd /c %USERPROFILE%\.lmstudio\bin\lms.exe bootstrap

Verification Steps
==================

After installation, verify MassGen is correctly installed:

.. code-block:: bash

   # Check MassGen is available
   massgen --help

You should see the MassGen CLI help message with all available options.

Quick Test
----------

Try a simple query to verify everything works:

.. code-block:: bash

   # Single agent mode (no config needed)
   massgen --model gemini-2.5-flash "What is MassGen?"

   # Or run the wizard and try your default config
   massgen "Tell me about multi-agent systems"

Next Steps
==========

**Great! You've installed MassGen. Here's your learning path:**

✅ **You are here:** Installation complete

⬜ **Next:** :doc:`running-massgen` - Run your first command and see MassGen in action

⬜ **Then:** :doc:`configuration` - Learn how to customize agent teams

⬜ **Advanced:** :doc:`../user_guide/multi_turn_mode` - Explore interactive conversations

**Quick jump:** Want to dive into examples? Check out :doc:`../examples/basic_examples` for copy-paste configurations.

Troubleshooting
===============

Setup Wizard Not Appearing
---------------------------

If the wizard doesn't appear on first run:

.. code-block:: bash

   # Manually trigger the setup wizard
   massgen --init

   # Or check if a config already exists (Unix/Mac)
   ls ~/.config/massgen/config.yaml

   # Windows
   dir %USERPROFILE%\.config\massgen\config.yaml

To start fresh, remove the existing config and run again.

Python Version Issues
---------------------

If you encounter Python version errors:

.. code-block:: bash

   # Check your Python version
   python --version

   # If below 3.11, install a newer version from python.org
   # Then reinstall MassGen
   pip install --upgrade massgen

Missing Example Configurations
-------------------------------

If ``--list-examples`` shows no results:

.. code-block:: bash

   # Reinstall MassGen to ensure package data is included
   pip install --force-reinstall massgen

   # Verify installation
   massgen --list-examples

API Key Errors
--------------

If you see "API key not found" errors:

1. Check your ``.env`` file exists:

   * Unix/Mac: ``~/.config/massgen/.env``
   * Windows: ``%USERPROFILE%\.config\massgen\.env``

2. Verify the key is correctly named (e.g., ``OPENAI_API_KEY``)
3. Re-run the wizard: ``massgen --init``

For more help, visit our `GitHub Issues <https://github.com/Leezekun/MassGen/issues>`_ or join our community.

.. note::
   **Existing MassGen users:** If you previously used MassGen via git clone, all your existing workflows continue to work. See :doc:`running-massgen` (Backwards Compatibility section) for details on command syntax and migration.