massgen 0.0.3__py3-none-any.whl → 0.1.0a1__py3-none-any.whl

massgen/configs/README.md

@@ -1,293 +1,636 @@
-# MassGen Configuration Examples
+# MassGen Configuration Guide
 
-This directory contains sample configuration files for MassGen CLI usage. Each configuration is optimized for specific use cases and demonstrates different agent collaboration patterns.
+This guide explains the organization and usage of MassGen configuration files.
 
-## 📁 Available Configurations
+## Directory Structure
 
-### 🤖 Single Agent Configurations
+```
+massgen/configs/
+├── basic/                 # Simple configs to get started
+│   ├── single/           # Single agent examples
+│   └── multi/            # Multi-agent examples
+├── tools/                 # Tool-enabled configurations
+│   ├── mcp/              # MCP server integrations
+│   ├── web-search/       # Web search enabled configs
+│   ├── code-execution/   # Code interpreter/execution
+│   └── filesystem/       # File operations & workspace
+├── providers/             # Provider-specific examples
+│   ├── openai/           # GPT-5 series configs
+│   ├── claude/           # Claude API configs
+│   ├── gemini/           # Gemini configs
+│   ├── azure/            # Azure OpenAI
+│   ├── local/            # LMStudio, local models
+│   └── others/           # Cerebras, Grok, Qwen, ZAI
+├── teams/                # Pre-configured specialized teams
+│   ├── creative/         # Creative writing teams
+│   ├── research/         # Research & analysis
+│   └── development/      # Coding teams
+└── docs/                 # Setup guides and documentation
+```
 
-- **`single_agent.yaml`** - Basic single agent setup with Gemini
-  - Uses Gemini 2.5 Flash model
-  - Web search enabled for current information
-  - Rich terminal display with token usage tracking
+## CLI Command Line Arguments
 
-### 👥 Multi-Agent Configurations
+| 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`, `claude_code`, `gemini`, `grok`, `openai`, `azure_openai`, `zai`). Optional for [models with default backends](../utils.py).|
+| `--model`          | Model name for quick setup (e.g., `gemini-2.5-flash`, `gpt-5-nano`, ...). `--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.|
+| `--debug`          | Enable debug mode with verbose logging (NEW in v0.0.13). Shows detailed orchestrator activities, agent messages, backend operations, and tool calls. Debug logs are saved to `agent_outputs/log_{time}/massgen_debug.log`. |
+| `"<your question>"`         | Optional single-question input; if omitted, MassGen enters interactive chat mode. |
 
-#### General Purpose Teams
+## Quick Start Examples
 
-- **`three_agents_default.yaml`** - Default three-agent setup with frontier models
-  - **Gemini 2.5 Flash**: Web search enabled
-  - **GPT-4o-mini**: Web search and code interpreter enabled
-  - **Grok-3-mini**: Web search with citations
-  - Best for general questions requiring diverse perspectives
+### 🌟 Recommended Showcase Example
 
-- **`gemini_4o_claude.yaml`** - Premium three-agent configuration
-  - **Gemini 2.5 Flash**: Web search enabled
-  - **GPT-4o**: Full GPT-4o with web search and code interpreter
-  - **Claude 3.5 Haiku**: Web search with citations
-  - Higher quality responses for complex tasks
+**Best starting point for multi-agent collaboration:**
+```bash
+# Three powerful agents (Gemini, GPT-5, Grok) with enhanced workspace tools
+uv run python -m massgen.cli --config massgen/configs/basic/multi/three_agents_default.yaml "Your complex task"
+```
 
-- **`two_agents.yaml`** - Focused two-agent collaboration
-  - **Primary Agent (GPT-4o)**: Comprehensive research and analysis
-  - **Secondary Agent (GPT-4o-mini)**: Review and refinement
-  - Efficient for tasks needing depth with validation
+This configuration combines:
+- **Gemini 2.5 Flash** - Fast, versatile with web search
+- **GPT-5 Nano** - Advanced reasoning with code interpreter
+- **Grok-3 Mini** - Efficient with real-time web search
 
-#### Specialized Teams
+### Quick Setup Without Config Files
 
-- **`research_team.yaml`** - Academic/technical research configuration
-  - **Information Gatherer (Grok)**: Web search specialist
-  - **Domain Expert (GPT-4o)**: Deep analysis with code interpreter
-  - **Synthesizer (GPT-4o-mini)**: Integration and summarization
-  - Low temperature (0.3) for accuracy
+**Single agent with model name only:**
+```bash
+# Quick test with any supported model - no configuration needed
+uv run python -m massgen.cli --model claude-3-5-sonnet-latest "What is machine learning?"
+uv run python -m massgen.cli --model gemini-2.5-flash "Explain quantum computing"
+uv run python -m massgen.cli --model gpt-5-nano "Summarize the latest AI developments"
+```
 
-- **`creative_team.yaml`** - Creative writing and storytelling
-  - **Storyteller (GPT-4o)**: Narrative creation
-  - **Editor (GPT-4o-mini)**: Structure and flow refinement
-  - **Critic (Grok-3-mini)**: Literary analysis
-  - High temperature (0.8) for creativity
+**Interactive Mode:**
+```bash
+# Start interactive chat (no initial question)
+uv run python -m massgen.cli --config massgen/configs/basic/multi/three_agents_default.yaml
 
-- **`news_analysis.yaml`** - Current events and news synthesis
-  - **News Gatherer (GPT-4o)**: Finding current events
-  - **Trend Analyst (Grok-3-mini)**: Pattern identification
-  - **News Synthesizer (GPT-4o-mini)**: Balanced summaries
-  - Medium temperature (0.4) for balanced analysis
+# Debug mode for troubleshooting
+uv run python -m massgen.cli --config massgen/configs/basic/multi/three_agents_default.yaml --debug "Your question"
+```
 
-- **`technical_analysis.yaml`** - Technical queries and cost estimation
-  - **Technical Researcher (GPT-4o)**: Specifications and documentation
-  - **Cost Analyst (Grok-3-mini)**: Pricing and cost calculations
-  - **Technical Advisor (GPT-4o-mini)**: Practical recommendations
-  - Low temperature (0.2) for precision
+### Basic Usage
 
-- **`travel_planning.yaml`** - Travel recommendations and planning
-  - **Travel Researcher (GPT-4o)**: Destination information
-  - **Local Expert (Grok-3-mini)**: Insider knowledge
-  - **Travel Planner (GPT-4o-mini)**: Itinerary organization
-  - Medium temperature (0.6) for balanced suggestions
+For simple single-agent setups:
+```bash
+uv run python -m massgen.cli --config massgen/configs/basic/single/single_agent.yaml "Your question"
+```
 
-## 🚀 Usage Examples
+### Tool-Enabled Configurations
 
-### Single Agent Mode
+#### MCP (Model Context Protocol) Servers
+MCP enables agents to use external tools and services:
 ```bash
-# Using configuration file
-uv run python -m massgen.cli --config single_agent.yaml "What is machine learning?"
+# Weather queries
+uv run python -m massgen.cli --config massgen/configs/tools/mcp/gemini_mcp_example.yaml "What's the weather in Tokyo?"
 
-# Quick setup without config file
-uv run python -m massgen.cli --model gemini-2.5-flash "Explain quantum computing"
+# Discord integration
+uv run python -m massgen.cli --config massgen/configs/tools/mcp/claude_code_discord_mcp_example.yaml "Extract latest messages"
+```
+
+#### Web Search
+For agents with web search capabilities:
+```bash
+uv run python -m massgen.cli --config massgen/configs/tools/web-search/claude_streamable_http_test.yaml "Search for latest news"
 ```
 
-### Multi-Agent Mode
+#### Code Execution
+For code interpretation and execution:
 ```bash
-# Default three agents for general questions
-uv run python -m massgen.cli --config three_agents_default.yaml "Compare renewable energy technologies"
+uv run python -m massgen.cli --config massgen/configs/tools/code-execution/multi_agent_playwright_automation.yaml "Browse three issues in https://github.com/Leezekun/MassGen and suggest documentation improvements. Include screenshots and suggestions in a website."
+```
 
-# Premium agents for complex analysis
-uv run python -m massgen.cli --config gemini_4o_claude.yaml "Analyze the implications of quantum computing on cryptography"
+#### Filesystem Operations
+For file manipulation, workspace management, and copy tools:
+```bash
+# Single agent with enhanced file operations
+uv run python -m massgen.cli --config massgen/configs/tools/filesystem/claude_code_single.yaml "Analyze this codebase"
 
-# Specialized teams for specific tasks
-uv run python -m massgen.cli --config research_team.yaml "Latest developments in CRISPR gene editing"
-uv run python -m massgen.cli --config creative_team.yaml "Write a short story about AI consciousness"
-uv run python -m massgen.cli --config news_analysis.yaml "What happened in tech news this week?"
-uv run python -m massgen.cli --config technical_analysis.yaml "Cost analysis for running LLMs at scale"
-uv run python -m massgen.cli --config travel_planning.yaml "Plan a 5-day trip to Tokyo in spring"
+# Multi-agent workspace collaboration with copy tools (NEW in v0.0.22)
+uv run python -m massgen.cli --config massgen/configs/tools/filesystem/claude_code_context_sharing.yaml "Create shared workspace files"
 ```
 
-### Interactive Mode
+### Provider-Specific Examples
+
+Each provider has unique features and capabilities:
+
+#### OpenAI (GPT-5 Series)
 ```bash
-# Start interactive session with any configuration
-uv run python -m massgen.cli --config gemini_4o_claude.yaml
+uv run python -m massgen.cli --config massgen/configs/providers/openai/gpt5.yaml "Complex reasoning task"
+```
 
-# Commands in interactive mode:
-# /clear - Clear conversation history
-# /quit, /exit, /q - Exit the session
+#### Claude
+```bash
+uv run python -m massgen.cli --config massgen/configs/providers/claude/claude_mcp_example.yaml "Creative writing task"
 ```
 
-## 📋 Configuration Structure
+#### Gemini
+```bash
+uv run python -m massgen.cli --config massgen/configs/providers/gemini/gemini_mcp_example.yaml "Research task"
+```
 
-**Single Agent Configuration:**
+#### Local Models
+```bash
+uv run python -m massgen.cli --config massgen/configs/providers/local/lmstudio.yaml "Run with local model"
+```
 
-Use the `agent` field to define a single agent with its backend and settings:
+### Pre-Configured Teams
 
-```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
+Teams are specialized multi-agent setups for specific domains:
+
+#### Creative Teams
+```bash
+uv run python -m massgen.cli --config massgen/configs/teams/creative/creative_team.yaml "Write a story"
 ```
 
-**Multi-Agent Configuration:**
+#### Research Teams
+```bash
+uv run python -m massgen.cli --config massgen/configs/teams/research/research_team.yaml "Analyze market trends"
+```
 
-Use the `agents` field to define multiple agents, each with its own backend and config:
+#### Development Teams
+```bash
+uv run python -m massgen.cli --config massgen/configs/teams/development/zai_coding_team.yaml "Build a web app"
+```
+
+## Configuration File Format
 
+### Single Agent
 ```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: "..."
+agent:
+  id: "agent_name"
+  backend:
+    type: "provider_type"
+    model: "model_name"
+    # Additional backend settings
+  system_message: "Agent instructions"
+
+ui:
+  display_type: "rich_terminal"
+  logging_enabled: true
 ```
 
-**Backend Configuration:**
+### Multi-Agent
+```yaml
+agents:
+  - id: "agent1"
+    backend:
+      type: "provider1"
+      model: "model1"
+    system_message: "Agent 1 role"
 
-Detailed parameters for each agent's backend can be specified using the following configuration formats:
+  - id: "agent2"
+    backend:
+      type: "provider2"
+      model: "model2"
+    system_message: "Agent 2 role"
 
-#### Claude
+ui:
+  display_type: "rich_terminal"
+  logging_enabled: true
+```
 
+### MCP Server Configuration
 ```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
+  type: "provider"
+  model: "model_name"
+  mcp_servers:
+    server_name:
+      type: "stdio"
+      command: "command"
+      args: ["arg1", "arg2"]
+      env:
+        KEY: "${ENV_VAR}"
 ```
 
-#### Gemini
+## Finding the Right Configuration
 
-```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
+1. **New Users**: Start with `basic/single/` or `basic/multi/`
+2. **Need Tools**: Check `tools/` subdirectories for specific capabilities
+3. **Specific Provider**: Look in `providers/` for your provider
+4. **Complex Tasks**: Use pre-configured `teams/`
+
+## Environment Variables
+
+Most configurations use environment variables for API keys:
+- Set up your `.env` file based on `.env.example`
+- Provider-specific keys: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.
+- MCP server keys: `DISCORD_BOT_TOKEN`, `BRAVE_API_KEY`, etc.
+
+## Release History & Examples
+
+### v0.0.32 - Latest
+**New Features:** Docker Execution Mode, MCP Architecture Refactoring, Claude Code Docker Integration
+
+**Configuration Files:**
+- `massgen/configs/tools/code-execution/docker_simple.yaml` - Basic single-agent Docker execution
+- `massgen/configs/tools/code-execution/docker_multi_agent.yaml` - Multi-agent Docker deployment with isolated containers
+- `massgen/configs/tools/code-execution/docker_with_resource_limits.yaml` - Resource-constrained Docker setup with CPU/memory limits
+- `massgen/configs/tools/code-execution/docker_claude_code.yaml` - Claude Code with Docker execution and automatic tool management
+- `massgen/configs/debug/code_execution/docker_verification.yaml` - Docker setup verification configuration
+
+**Key Features:**
+- Docker-based command execution with container isolation preventing host filesystem access
+- Persistent state across conversation turns (packages stay installed)
+- Multi-agent support with dedicated containers per agent
+- Resource limits (CPU, memory) and network isolation modes (none/bridge/host)
+- Simplified MCP architecture with MCPClient (renamed from MultiMCPClient)
+- Claude Code automatic Bash tool disablement in Docker mode
+
+**Try it:**
+```bash
+# Docker isolated execution - secure command execution in containers
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/code-execution/docker_simple.yaml \
+  "Write a factorial function and test it"
+
+# Multi-agent Docker deployment - each agent in isolated container
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/code-execution/docker_multi_agent.yaml \
+  "Build a Flask website about Bob Dylan"
+
+# Claude Code with Docker - automatic tool management
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/code-execution/docker_claude_code.yaml \
+  "Build a Flask website about Bob Dylan"
+
+# Resource-limited Docker execution - production-ready setup
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/code-execution/docker_with_resource_limits.yaml \
+  "Fetch data from an API and analyze it"
 ```
 
-#### Grok
+### v0.0.31
+**New Features:** Universal Code Execution, AG2 Group Chat Integration, Audio & Video Generation Tools
+
+**Configuration Files:**
+- `massgen/configs/tools/code-execution/basic_command_execution.yaml` - Universal command execution across all backends
+- `massgen/configs/debug/code_execution/command_filtering_whitelist.yaml` - Command execution with whitelist filtering
+- `massgen/configs/debug/code_execution/command_filtering_blacklist.yaml` - Command execution with blacklist filtering
+- `massgen/configs/tools/code-execution/code_execution_use_case_simple.yaml` - Multi-agent web automation with code execution
+- `massgen/configs/ag2/ag2_groupchat.yaml` - Native AG2 group chat with multi-agent conversations
+- `massgen/configs/ag2/ag2_groupchat_gpt.yaml` - Mixed MassGen and AG2 agents (GPT-5-nano + AG2 team)
+- `massgen/configs/basic/single/single_gpt4o_audio_generation.yaml` - Single agent audio generation with GPT-4o
+- `massgen/configs/basic/multi/gpt4o_audio_generation.yaml` - Multi-agent audio generation with GPT-4o
+- `massgen/configs/basic/single/single_gpt4o_video_generation.yaml` - Video generation with OpenAI Sora-2
+
+**Key Features:**
+- Universal `execute_command` tool works across Claude, Gemini, OpenAI (Response API), and Chat Completions providers (Grok, ZAI, etc.)
+- AG2 group chat integration with speaker selection modes (auto, round-robin, manual)
+- Audio tools: text-to-speech, audio transcription, audio generation
+- Video tools: text-to-video generation via Sora-2 API
+- Code execution in planning mode for safer coordination
+- Enhanced file operation tracking and path permission management
+
+**Try it:**
+```bash
+# Universal code execution - works with any backend
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/code-execution/basic_command_execution.yaml \
+  "Write a Python function to calculate factorial and test it"
+
+# AG2 group chat - multi-agent conversations
+uv run python -m massgen.cli \
+  --config massgen/configs/ag2/ag2_groupchat.yaml \
+  "Write a Python function to calculate factorial."
+
+# Mixed MassGen + AG2 agents - GPT-5-nano collaborating with AG2 team
+uv run python -m massgen.cli \
+  --config massgen/configs/ag2/ag2_groupchat_gpt.yaml \
+  "Write a Python function to calculate factorial."
+
+# Audio generation
+uv run python -m massgen.cli \
+  --config massgen/configs/basic/single/single_gpt4o_audio_generation.yaml \
+  "I want to you tell me a very short introduction about Sherlock Homes in one sentence, and I want you to use emotion voice to read it out loud."
+
+# Video generation with Sora-2
+uv run python -m massgen.cli \
+  --config massgen/configs/basic/single/single_gpt4o_video_generation.yaml \
+  "Generate a 4 seconds video with neon-lit alley at night, light rain, slow push-in, cinematic."
+```
 
-```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" 
+### v0.0.30
+**New Features:** Multimodal Audio and Video Support, Claude Agent SDK Update, Qwen API Integration
+- `massgen/configs/basic/single/single_openrouter_audio_understanding.yaml` - Audio understanding with OpenRouter
+- `massgen/configs/basic/single/single_qwen_video_understanding.yaml` - Video understanding with Qwen API
+- `massgen/configs/basic/single/single_gemini2.5pro.yaml` - Gemini 2.5 Pro single agent setup
+- `massgen/configs/tools/filesystem/cc_gpt5_gemini_filesystem.yaml` - Claude Code, GPT-5, and Gemini filesystem collaboration
+- `massgen/configs/ag2/ag2_case_study.yaml` - AG2 framework integration case study
+- `massgen/configs/debug/test_sdk_migration.yaml` - Claude Code SDK migration testing
+- Updated from `claude-code-sdk>=0.0.19` to `claude-agent-sdk>=0.0.22`
+- Audio/video multimodal support for Chat Completions and Claude backends
+- Qwen API provider integration with video understanding capabilities
+
+**Try it:**
+```bash
+# Audio understanding with OpenRouter
+uv run python -m massgen.cli \
+  --config massgen/configs/basic/single/single_openrouter_audio_understanding.yaml \
+  "What is in this recording?"
+
+# Video understanding with Qwen API
+uv run python -m massgen.cli \
+  --config massgen/configs/basic/single/single_qwen_video_understanding.yaml \
+  "Describe what happens in this video"
+
+# Multi-agent filesystem collaboration
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/filesystem/cc_gpt5_gemini_filesystem.yaml \
+  "Create a comprehensive project with documentation"
 ```
 
-#### OpenAI
+### v0.0.29
+**New Features:** MCP Planning Mode, File Operation Safety, Enhanced MCP Tool Filtering
+- `massgen/configs/tools/planning/five_agents_discord_mcp_planning_mode.yaml` - Five agents with Discord MCP in planning mode
+- `massgen/configs/tools/planning/five_agents_filesystem_mcp_planning_mode.yaml` - Five agents with filesystem MCP in planning mode
+- `massgen/configs/tools/planning/five_agents_notion_mcp_planning_mode.yaml` - Five agents with Notion MCP in planning mode
+- `massgen/configs/tools/planning/five_agents_twitter_mcp_planning_mode.yaml` - Five agents with Twitter MCP in planning mode
+- `massgen/configs/tools/planning/gpt5_mini_case_study_mcp_planning_mode.yaml` - Planning mode case study configuration
+- `massgen/configs/tools/mcp/five_agents_travel_mcp_test.yaml` - Five agents testing travel-related MCP tools
+- `massgen/configs/tools/mcp/five_agents_weather_mcp_test.yaml` - Five agents testing weather MCP tools
+- `massgen/configs/debug/skip_coordination_test.yaml` - Debug configuration for testing coordination skipping
+- New `CoordinationConfig` class with `enable_planning_mode` flag for safer MCP coordination
+- New `FileOperationTracker` class for read-before-delete enforcement
+- Enhanced PathPermissionManager with operation tracking methods
+
+**Case Study:** [MCP Planning Mode](../../docs/case_studies/mcp-planning-mode.md)
+
+**Try it:**
+```bash
+# Planning mode with filesystem operations
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/planning/five_agents_filesystem_mcp_planning_mode.yaml \
+  "Create a comprehensive project structure with documentation"
+
+# Multi-agent weather MCP testing
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/mcp/five_agents_weather_mcp_test.yaml \
+  "Compare weather forecasts for New York, London, and Tokyo"
+
+# Planning mode with Twitter integration
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/planning/five_agents_twitter_mcp_planning_mode.yaml \
+  "Draft and plan tweet series about AI advancements"
+```
 
-```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
+### v0.0.28
+**New Features:** AG2 Framework Integration, External Agent Backend, Code Execution Support
+- `massgen/configs/ag2/ag2_single_agent.yaml` - Basic single AG2 agent setup
+- `massgen/configs/ag2/ag2_coder.yaml` - AG2 agent with code execution capabilities
+- `massgen/configs/ag2/ag2_coder_case_study.yaml` - Multi-agent setup with AG2 and Gemini
+- `massgen/configs/ag2/ag2_gemini.yaml` - AG2-Gemini hybrid configuration
+- New `massgen/adapters/` module for external framework integration
+- New `ExternalAgentBackend` class bridging MassGen with external frameworks
+- Multiple code executor types: LocalCommandLineCodeExecutor, DockerCommandLineCodeExecutor, JupyterCodeExecutor, YepCodeCodeExecutor
+
+**Case Study:** [AG2 Framework Integration](../../docs/case_studies/ag2-framework-integration.md)
+
+**Try it:**
+```bash
+# AG2 single agent with code execution
+uv run python -m massgen.cli \
+  --config massgen/configs/ag2/ag2_coder.yaml \
+  "Create a factorial function and calculate the factorial of 8. Show the result?"
+
+# Mixed team: AG2 agent + Gemini agent
+uv run python -m massgen.cli \
+  --config massgen/configs/ag2/ag2_gemini.yaml \
+  "what is quantum computing?"
+
+# AG2 case study: Compare AG2 and MassGen (requires external dependency)
+uv pip install -e ".[external]"
+uv run python -m massgen.cli \
+  --config massgen/configs/ag2/ag2_coder_case_study.yaml \
+  "Output a summary comparing the differences between AG2 (https://github.com/ag2ai/ag2) and MassGen (https://github.com/Leezekun/MassGen) for LLM agents."
 ```
 
-**UI Configuration:**
+### v0.0.27
+**New Features:** Multimodal Support (Image Processing), File Upload and File Search, Claude Sonnet 4.5
+- `massgen/configs/basic/multi/gpt4o_image_generation.yaml` - Multi-agent image generation
+- `massgen/configs/basic/multi/gpt5nano_image_understanding.yaml` - Multi-agent image understanding
+- `massgen/configs/basic/single/single_gpt4o_image_generation.yaml` - Single agent image generation
+- `massgen/configs/basic/single/single_gpt5nano_image_understanding.yaml` - Single agent image understanding
+- `massgen/configs/basic/single/single_gpt5nano_file_search.yaml` - File search for document Q&A
+- New `stream_chunk` module for multimodal content architecture
+- Enhanced `read_multimodal_files` MCP tool for image processing
+
+**Try it:**
+```bash
+# Image generation with single agent
+uv run python -m massgen.cli \
+  --config massgen/configs/basic/single/single_gpt4o_image_generation.yaml \
+  "Generate an image of gray tabby cat hugging an otter with an orange scarf. Limit image size within 5kb."
+
+# Image understanding with multiple agents
+uv run python -m massgen.cli \
+  --config massgen/configs/basic/multi/gpt5nano_image_understanding.yaml \
+  "Please summarize the content in this image."
+
+# File search for document Q&A
+uv run python -m massgen.cli \
+  --config massgen/configs/basic/single/single_gpt5nano_file_search.yaml \
+  "What is humanity's last exam score for OpenAI Deep Research? Also, provide details about the other models mentioned in the PDF?"
+```
 
-Configure how MassGen displays information and handles logging during execution:
+### v0.0.26
+**New Features:** File Deletion, Protected Paths, File-Based Context Paths
+- `massgen/configs/tools/filesystem/gemini_gpt5nano_protected_paths.yaml` - Protected paths configuration
+- `massgen/configs/tools/filesystem/gemini_gpt5nano_file_context_path.yaml` - File-based context paths
+- `massgen/configs/tools/filesystem/grok4_gpt5_gemini_filesystem.yaml` - Multi-agent filesystem collaboration
+- New MCP tools: `delete_file`, `delete_files_batch`, `compare_directories`, `compare_files`
 
-```yaml
-ui:
-  display_type: "rich_terminal" | "terminal" | "simple"  # Display format for agent interactions
-  logging_enabled: true | false                          # Enable/disable real-time logging 
+**Try it:**
+```bash
+# Protected paths - keep reference files safe
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/filesystem/gemini_gpt5nano_protected_paths.yaml \
+  "Review the HTML and CSS files, then improve the styling"
+
+# File-based context paths - grant access to specific files
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/filesystem/gemini_gpt5nano_file_context_path.yaml \
+  "Analyze the CSS file and make modern improvements"
 ```
 
-- `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
+### v0.0.25
+**New Features:** Multi-Turn Filesystem Support, SGLang Backend Integration
+- `massgen/configs/tools/filesystem/multiturn/two_gemini_flash_filesystem_multiturn.yaml` - Multi-turn with Gemini agents
+- `massgen/configs/tools/filesystem/multiturn/grok4_gpt5_claude_code_filesystem_multiturn.yaml` - Three-agent multi-turn
+- `massgen/configs/basic/multi/two_qwen_vllm_sglang.yaml` - Mixed vLLM and SGLang deployment
+- Automatic `.massgen` directory management for persistent conversation context
+- Enhanced path permissions with `will_be_writable` flag and smart exclusion patterns
 
-**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
+**Case Study:** [Multi-Turn Filesystem Support](../../docs/case_studies/multi-turn-filesystem-support.md)
+```bash
+# Turn 1 - Initial creation
+Turn 1: Make a website about Bob Dylan
+# Creates workspace and saves state to .massgen/sessions/
+
+# Turn 2 - Enhancement based on Turn 1
+Turn 2: Can you (1) remove the image placeholder? we will not use image directly. (2) generally improve the appearance so it is more engaging, (3) make it longer and add an interactive element
+# Note: Unlike pre-v0.0.25, Turn 2 automatically loads Turn 1's workspace state
+# Agents can directly access and modify files from the previous turn
 ```
 
-## 🔧 Environment Variables
+### v0.0.24
+**New Features:** vLLM Backend Support, Backend Utility Modules
+- `massgen/configs/basic/multi/three_agents_vllm.yaml` - vLLM with Cerebras and ZAI backends
+- `massgen/configs/basic/multi/two_qwen_vllm.yaml` - Dual vLLM agents for testing
+- POE provider support for accessing multiple AI models through single platform
+- GPT-5-Codex model recognition for enhanced code generation capabilities
+
+**Try it:**
+```bash
+# Try vLLM backend with local models (requires vLLM server running)
+# First start vLLM server: python -m vllm.entrypoints.openai.api_server --model Qwen/Qwen3-0.6B --host 0.0.0.0 --port 8000
+uv run python -m massgen.cli \
+  --config massgen/configs/basic/multi/two_qwen_vllm.yaml \
+  "What is machine learning?"
+```
 
-Set these in your `.env` file:
+### v0.0.23
+**New Features:** Backend Architecture Refactoring, Formatter Module
+- Major code consolidation with new `base_with_mcp.py` class reducing ~1,932 lines across backends
+- Extracted message and tool formatting logic into dedicated `massgen/formatter/` module
+- Streamlined chat_completions.py, claude.py, and response.py for better maintainability
 
+### v0.0.22
+**New Features:** Workspace Copy Tools via MCP, Configuration Organization
+- All configs now organized by provider & use case (basic/, providers/, tools/, teams/)
+- Use same configs as v0.0.21 for compatibility, but now with improved performance
+
+**Case Study:** [Advanced Filesystem with User Context Path Support](../../docs/case_studies/v0.0.21-v0.0.22-filesystem-permissions.md)
 ```bash
-# API Keys
-ANTHROPIC_API_KEY="your-anthropic-key"
-GEMINI_API_KEY="your-gemini-key"
-OPENAI_API_KEY="your-openai-key"
-XAI_API_KEY="your-xai-key"
+# Multi-agent collaboration with granular filesystem permissions
+uv run python -m massgen.cli --config massgen/configs/tools/filesystem/gpt5mini_cc_fs_context_path.yaml "Enhance the website in massgen/configs/resources with: 1) A dark/light theme toggle with smooth transitions, 2) An interactive feature that helps users engage with the blog content (your choice - could be search, filtering by topic, reading time estimates, social sharing, reactions, etc.), and 3) Visual polish with CSS animations or transitions that make the site feel more modern and responsive. Use vanilla JavaScript and be creative with the implementation details."
 ```
 
-## 💡 Backend Capabilities
+### v0.0.21
+**New Features:** Advanced Filesystem Permissions, Grok MCP Integration
+- `massgen/configs/tools/mcp/grok3_mini_mcp_example.yaml` - Grok with MCP tools
+- `massgen/configs/tools/filesystem/fs_permissions_test.yaml` - Permission-controlled file sharing
+- `massgen/configs/tools/filesystem/claude_code_context_sharing.yaml` - Agent workspace sharing
 
-| Backend | Live Search | Code Execution |
-|---------|:-----------:|:--------------:|
-| **Claude** | ✅ | ✅ |
-| **OpenAI** | ✅ | ✅ |
-| **Grok** | ✅ | ❌ |
-| **Gemini** | ✅ | ✅ |
+**Try it:**
+```bash
+# Grok with MCP tools
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/mcp/grok3_mini_mcp_example.yaml \
+  "What's the weather in Tokyo?"
+```
 
-## 📚 Best Practices
+### v0.0.20
+**New Features:** Claude MCP Support with Recursive Execution
+- `massgen/configs/tools/mcp/claude_mcp_example.yaml` - Claude with MCP tools
+- `massgen/configs/tools/mcp/claude_mcp_test.yaml` - Testing Claude MCP capabilities
 
-1. **Choose the Right Configuration**
-   - Use `three_agents_default.yaml` for general questions
-   - Use specialized teams for domain-specific tasks
-   - Use `single_agent.yaml` for quick, simple queries
+**Try it:**
+```bash
+# Claude with MCP tools
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/mcp/claude_mcp_example.yaml \
+  "What's the current weather?"
+```
 
-2. **Temperature Settings**
-   - Low (0.1-0.3): Technical analysis, factual information
-   - Medium (0.4-0.6): Balanced tasks, general questions
-   - High (0.7-0.9): Creative writing, brainstorming
+### v0.0.17
+**New Features:** OpenAI MCP Integration
+- `massgen/configs/tools/mcp/gpt5_nano_mcp_example.yaml` - GPT-5 with MCP tools
+- `massgen/configs/tools/mcp/gpt5mini_claude_code_discord_mcp_example.yaml` - Multi-agent MCP
 
-3. **Cost Optimization**
-   - Use mini models (gpt-4o-mini, grok-3-mini) for routine tasks
-   - Reserve premium models (gpt-4o, claude-3-5-sonnet) for complex analysis
-   - Single agent mode is most cost-effective for simple queries
+**Try it:**
+```bash
+# Claude with MCP tools
+uv run python -m massgen.cli \
+  --config massgen/configs/tools/mcp/gpt5_nano_mcp_example.yaml \
+  "whats the weather of Tokyo?"
+```
 
-4. **Tool Usage**
-   - Enable web search for current events and real-time information
-   - Use code interpreter for data analysis and calculations
-   - Combine tools for comprehensive research tasks
 
-## 🛠️ Creating Custom Configurations
+### v0.0.16
+**New Features:** Unified Filesystem Support with MCP Integration
+**Case Study:** [Cross-Backend Collaboration with Gemini MCP Filesystem](../../docs/case_studies/unified-filesystem-mcp-integration.md)
+```bash
+# Gemini and Claude Code agents with unified filesystem via MCP
+uv run python -m massgen.cli --config massgen/configs/tools/mcp/gemini_mcp_filesystem_test_with_claude_code.yaml "Create a presentation that teaches a reinforcement learning algorithm and output it in LaTeX Beamer format. No figures should be added."
+```
 
-1. Copy an existing configuration as a template
-2. Modify agent roles and system messages for your use case
-3. Adjust temperature and max_tokens based on task requirements
-4. Enable/disable tools based on agent needs
-5. Test with sample queries to refine the configuration
+### v0.0.15
+**New Features:** Gemini MCP Integration
+- `massgen/configs/tools/mcp/gemini_mcp_example.yaml` - Gemini with weather MCP
+- `massgen/configs/tools/mcp/multimcp_gemini.yaml` - Multiple MCP servers
 
-Example custom configuration for code review:
-```yaml
-agents:
-  - id: "code_analyzer"
-    backend:
-      type: "openai"
-      model: "gpt-4o"
-      temperature: 0.2
-      enable_code_interpreter: true
-    system_message: "Analyze code for bugs, security issues, and best practices"
-    
-  - id: "refactoring_expert"
-    backend:
-      type: "claude"
-      model: "claude-3-5-sonnet-20250514"
-      temperature: 0.3
-    system_message: "Suggest code improvements and refactoring opportunities"
-```
+### v0.0.12 - v0.0.14
+**New Features:** Enhanced Logging and Workspace Management
+**Case Study:** [Claude Code Workspace Management with Comprehensive Logging](../../docs/case_studies/claude-code-workspace-management.md)
+```bash
+# Multi-agent Claude Code collaboration with enhanced workspace isolation
+uv run python -m massgen.cli --config massgen/configs/tools/filesystem/claude_code_context_sharing.yaml "Create a website about a diverse set of fun facts about LLMs, placing the output in one index.html file"
+```
+
+### v0.0.10
+**New Features:** Azure OpenAI Support
+- `massgen/configs/providers/azure/azure_openai_single.yaml` - Azure single agent
+- `massgen/configs/providers/azure/azure_openai_multi.yaml` - Azure multi-agent
+
+### v0.0.7
+**New Features:** Local Model Support with LM Studio
+- `massgen/configs/providers/local/lmstudio.yaml` - Local model inference
+
+### v0.0.5
+**New Features:** Claude Code Integration
+- `massgen/configs/tools/filesystem/claude_code_single.yaml` - Claude Code with dev tools
+- `massgen/configs/tools/filesystem/claude_code_flash2.5.yaml` - Multi-agent with Claude Code
+
+## Naming Convention
+
+To improve clarity and discoverability, we follow this naming pattern:
+
+**Format: `{agents}_{features}_{description}.yaml`**
+
+### 1. Agents (who's participating)
+- `single-{provider}` - Single agent (e.g., `single-claude`, `single-gemini`)
+- `{provider1}-{provider2}` - Two agents (e.g., `claude-gemini`, `gemini-gpt5`)
+- `three-mixed` - Three agents from different providers
+- `team-{type}` - Specialized teams (e.g., `team-creative`, `team-research`)
+
+### 2. Features (what tools/capabilities)
+- `basic` - No special tools, just conversation
+- `mcp` - MCP server integration
+- `mcp-{service}` - Specific MCP service (e.g., `mcp-discord`, `mcp-weather`)
+- `mcp-multi` - Multiple MCP servers
+- `websearch` - Web search enabled
+- `codeexec` - Code execution/interpreter
+- `filesystem` - File operations and workspace management
+
+### 3. Description (purpose/context - optional)
+- `showcase` - Demonstration/getting started example
+- `test` - Testing configuration
+- `research` - Research and analysis tasks
+- `dev` - Development and coding tasks
+- `collab` - Collaboration example
+
+### Examples
+```
+# Current → Suggested
+three_agents_default.yaml → three-mixed_basic_showcase.yaml
+grok3_mini_mcp_example.yaml → single-grok_mcp-weather_test.yaml
+claude_code_discord_mcp_example.yaml → single-claude_mcp-discord_demo.yaml
+gpt5mini_claude_code_discord_mcp_example.yaml → claude-gpt5_mcp-discord_collab.yaml
+```
+
+**Note:** Existing configs maintain their current names for compatibility. New configs should follow this convention.
+
+## Additional Documentation
+
+For detailed setup guides:
+- Discord MCP: `docs/DISCORD_MCP_SETUP.md`
+- Twitter MCP: `docs/TWITTER_MCP_ENESCINAR_SETUP.md`
+- Main README: See repository root for comprehensive documentation