massgen 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

{massgen-0.1.3.dist-info → massgen-0.1.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: massgen
-Version: 0.1.3
+Version: 0.1.5
 Summary: Multi-Agent Scaling System - A powerful framework for collaborative AI
 Author-email: MassGen Team <contact@massgen.dev>
 License: Apache-2.0
@@ -54,6 +54,8 @@ Requires-Dist: openpyxl>=3.1.5
 Requires-Dist: python-pptx>=1.0.2
 Requires-Dist: opencv-python>=4.12.0.88
 Requires-Dist: pypdf2>=3.0.1
+Requires-Dist: mem0ai>=1.0.0
+Requires-Dist: reportlab>=4.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -88,23 +90,29 @@ Provides-Extra: all
 Dynamic: license-file
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Leezekun/MassGen/main/assets/logo.png" alt="MassGen Logo" width="360" />
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Leezekun/MassGen/main/assets/logo-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Leezekun/MassGen/main/assets/logo.png">
+    <img src="https://raw.githubusercontent.com/Leezekun/MassGen/main/assets/logo.png" alt="MassGen Logo" width="360" />
+  </picture>
 </p>
 
-<p align="center">
-  <a href="https://www.python.org/downloads/">
-    <img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+" 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://docs.massgen.ai">
-    <img src="https://img.shields.io/badge/docs-massgen.ai-blue.svg" alt="Documentation" 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>
+<div align="center">
+
+[![Docs](https://img.shields.io/badge/docs-massgen.ai-blue?style=flat-square&logo=readthedocs&logoColor=white)](https://docs.massgen.ai)
+[![GitHub Stars](https://img.shields.io/github/stars/Leezekun/MassGen?style=flat-square&logo=github&color=181717&logoColor=white)](https://github.com/Leezekun/MassGen)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-green?style=flat-square)](LICENSE)
+
+</div>
+
+<div align="center">
+
+[![Follow on X](https://img.shields.io/badge/FOLLOW%20ON%20X-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.massgen.ai)
+[![Follow on LinkedIn](https://img.shields.io/badge/FOLLOW%20ON%20LINKEDIN-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/company/massgen-ai)
+[![Join our Discord](https://img.shields.io/badge/JOIN%20OUR%20DISCORD-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.massgen.ai)
+
+</div>
 
 <h1 align="center">🚀 MassGen: Multi-Agent Scaling System for GenAI</h1>
 
@@ -114,7 +122,7 @@ Dynamic: license-file
 
 <p align="center">
   <a href="https://www.youtube.com/watch?v=Dp2oldJJImw">
-    <img src="https://raw.githubusercontent.com/Leezekun/MassGen/main/assets/thumbnail.png" alt="MassGen case study -- Berkeley Agentic AI Summit Question" width="800">
+    <img src="docs/source/_static/images/thumbnail.png" alt="MassGen case study -- Berkeley Agentic AI Summit Question" width="800">
   </a>
 </p>
 
@@ -143,7 +151,7 @@ This project started with the "threads of thought" and "iterative refinement" id
 <details open>
 <summary><h3>🆕 Latest Features</h3></summary>
 
-- [v0.1.2 Features](#-latest-features-v012)
+- [v0.1.5 Features](#-latest-features-v015)
 </details>
 
 <details open>
@@ -188,15 +196,15 @@ This project started with the "threads of thought" and "iterative refinement" id
 <summary><h3>🗺️ Roadmap</h3></summary>
 
 - Recent Achievements
-  - [v0.1.2](#recent-achievements-v012)
-  - [v0.0.3 - v0.1.1](#previous-achievements-v003---v011)
+  - [v0.1.5](#recent-achievements-v015)
+  - [v0.0.3 - v0.1.4](#previous-achievements-v003---v014)
 - [Key Future Enhancements](#key-future-enhancements)
   - Bug Fixes & Backend Improvements
   - Advanced Agent Collaboration
   - Expanded Model, Tool & Agent Integrations
   - Improved Performance & Scalability
   - Enhanced Developer Experience
-- [v0.1.3 Roadmap](#v013-roadmap)
+- [v0.1.6 Roadmap](#v016-roadmap)
 </details>
 
 <details open>
@@ -221,36 +229,49 @@ This project started with the "threads of thought" and "iterative refinement" id
 
 ---
 
-## 🆕 Latest Features (v0.1.2)
+## 🆕 Latest Features (v0.1.5)
 
-**🎉 Released: October 22, 2025**
+**🎉 Released: October 2025**
 
-**What's New in v0.1.2:**
-- **🧠 Intelligent Planning Mode** - Automatic question analysis for safe MCP tool blocking
-- **🎭 Claude 4.5 Haiku Support** - Access to latest Claude Haiku model
-- **🔍 Grok Web Search Fix** - Improved web search functionality in Grok backend
+**What's New in v0.1.5:**
+- **🧠 Long-Term Memory System** - Semantic memory with retrieval across sessions
+- **🗜️ Automatic Context Compression** - Smart compression when approaching token limits
+- **🔄 Memory Sharing for Multi-Turn Conversations** - Agents access knowledge from previous turns
 
 **Key Improvements:**
-- Automatically determines if questions require irreversible operations
-- Read-only MCP operations allowed during coordination for better decisions
-- Write operations automatically blocked for safety
-- Zero configuration required - works transparently
-- Enhanced model support with latest Claude 4.5 Haiku
+- Persistent memory via mem0 integration with vector storage
+- Conversational memory for short-term context tracking
+- Context monitoring with real-time token usage tracking
+- Session management for memory isolation and continuation
+- Qdrant vector database integration for semantic search
 
-**Get Started with v0.1.2:**
+**Get Started with v0.1.5:**
 ```bash
 # Install or upgrade from PyPI
 pip install --upgrade massgen
 
-# Try intelligent planning mode with MCP tools
-# (Please read the YAML file for required API keys: DISCORD_TOKEN, OPENAI_API_KEY, etc.)
-massgen --config @examples/tools/planning/five_agents_discord_mcp_planning_mode \
-  "Check recent messages in our development channel, summarize the discussion, and post a helpful response about the current topic."
+# Multi-agent collaboration with context compression
+massgen --config @examples/memory/gpt5mini_gemini_context_window_management \
+  "Analyze the MassGen codebase comprehensively. Create an architecture document that explains: (1) Core components and their responsibilities, (2) How different modules interact, (3) Key design patterns used, (4) Main entry points and request flows. Read > 30 files to build a complete understanding."
+
+# Research-to-implementation workflow with memory persistence
+# Prerequisites: Start Qdrant and crawl4ai Docker containers
+docker run -d -p 6333:6333 -p 6334:6334 \
+  -v $(pwd)/.massgen/qdrant_storage:/qdrant/storage:z qdrant/qdrant
+docker run -d -p 11235:11235 --name crawl4ai --shm-size=1g unclecode/crawl4ai:latest
 
-# Use latest Claude 4.5 Haiku model
-# (Requires ANTHROPIC_API_KEY in .env)
-massgen --model claude-haiku-4-5-20251001 \
-  "Summarize the latest AI developments"
+# Session 1 - Research phase:
+massgen --config @examples/memory/gpt5mini_gemini_research_to_implementation \
+  "Use crawl4ai to research the latest multi-agent AI papers and techniques from 2025. Focus on: coordination mechanisms, voting strategies, tool-use patterns, and architectural innovations."
+
+# Session 2 - Implementation analysis (continue in same session):
+# "Based on the multi-agent research from earlier, which techniques should we implement in MassGen to make it more state-of-the-art? Consider MassGen's current architecture and what would be most impactful."
+
+→ See [Multi-Turn Persistent Memory Case Study](docs/source/examples/case_studies/multi-turn-persistent-memory.md) for detailed analysis
+
+# Test automatic context compression
+massgen --config @examples/memory/single_agent_compression_test \
+  "Analyze the MassGen codebase comprehensively. Create an architecture document that explains: (1) Core components and their responsibilities, (2) How different modules interact, (3) Key design patterns used, (4) Main entry points and request flows. Read > 30 files to build a complete understanding."
 ```
 
 → [See full release history and examples](massgen/configs/README.md#release-history--examples)
@@ -472,17 +493,20 @@ MassGen agents can leverage various tools to enhance their problem-solving capab
 
 **Supported Built-in Tools by Backend:**
 
-| Backend | Live Search | Code Execution | File Operations | MCP Support | Multimodal (Image/Audio/Video) | Advanced Features |
-|---------|:-----------:|:--------------:|:---------------:|:-----------:|:----------:|:-----------------|
-| **Azure OpenAI** (NEW in v0.0.10) | ❌ | ❌ | ❌ | ❌ | ❌ | Code interpreter, Azure deployment management |
-| **Claude API**  | ✅ | ✅ | ✅ | ✅ | ✅ | Web search, code interpreter, **MCP integration** |
-| **Claude Code** | ✅ | ✅ | ✅ | ✅ | ✅<br/>*Image* | **Native Claude Code SDK, comprehensive dev tools, MCP integration** |
-| **Gemini API** | ✅ | ✅ | ✅ | ✅ | ✅<br/>*Image* | Web search, code execution, **MCP integration**|
-| **Grok API** | ✅ | ❌ | ✅ | ✅ | ❌ | Web search, **MCP integration** |
-| **OpenAI API** | ✅ | ✅ | ✅ | ✅ | ✅<br/>*Image* | Web search, code interpreter, **MCP integration** |
-| **ZAI API** | ❌ | ❌ | ✅ | ✅ | ❌ | **MCP integration** |
-
-**Note:** Audio/video multimodal support (NEW in v0.0.30) is available through Chat Completions-based providers like OpenRouter and Qwen API. See configuration examples: [`single_openrouter_audio_understanding.yaml`](massgen/configs/basic/single/single_openrouter_audio_understanding.yaml), [`single_qwen_video_understanding.yaml`](massgen/configs/basic/single/single_qwen_video_understanding.yaml)
+| Backend | Live Search | Code Execution | File Operations | MCP Support | Multimodal Understanding | Multimodal Generation | Advanced Features |
+|---------|:-----------:|:--------------:|:---------------:|:-----------:|:------------------------:|:---------------------:|:-----------------|
+| **Azure OpenAI** (NEW in v0.0.10) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | Code interpreter, Azure deployment management |
+| **Claude API**  | ✅ | ✅ | ✅ | ✅ | ✅<br/>*via custom tools* | ✅<br/>*via custom tools* | Web search, code interpreter, **MCP integration** |
+| **Claude Code** | ✅ | ✅ | ✅ | ✅ | ✅<br/>*Image (native)*<br/>*Audio/Video/Docs (custom tools)* | ✅<br/>*via custom tools* | **Native Claude Code SDK, comprehensive dev tools, MCP integration** |
+| **Gemini API** | ✅ | ✅ | ✅ | ✅ | ✅<br/>*Image (native)*<br/>*Audio/Video/Docs (custom tools)* | ✅<br/>*via custom tools* | Web search, code execution, **MCP integration**|
+| **Grok API** | ✅ | ❌ | ✅ | ✅ | ✅<br/>*via custom tools* | ✅<br/>*via custom tools* | Web search, **MCP integration** |
+| **OpenAI API** | ✅ | ✅ | ✅ | ✅ | ✅<br/>*Image (native)*<br/>*Audio/Video/Docs (custom tools)* | ✅<br/>*via custom tools* | Web search, code interpreter, **MCP integration** |
+| **ZAI API** | ❌ | ❌ | ✅ | ✅ | ✅<br/>*via custom tools* | ✅<br/>*via custom tools* | **MCP integration** |
+
+**Notes:**
+- **Multimodal Understanding** (NEW in v0.1.3): Analyze images, audio, video, and documents via custom tools using OpenAI GPT-4.1 - works with any backend
+- **Multimodal Generation** (NEW in v0.1.4): Generate images, videos, audio, and documents via custom tools using OpenAI APIs - works with any backend
+- See custom tool configurations: [`understand_image.yaml`](massgen/configs/tools/custom_tools/multimodal_tools/understand_image.yaml), [`text_to_image_generation_single.yaml`](massgen/configs/tools/custom_tools/multimodal_tools/text_to_image_generation_single.yaml)
 
 → For detailed backend capabilities and tool integration guides, see [User Guide - Backends](https://docs.massgen.ai/en/latest/user_guide/backends.html)
 
@@ -954,7 +978,7 @@ massgen --config @examples/tools/code-execution/multi_agent_playwright_automatio
   "Navigate to https://news.ycombinator.com, extract the top 10 stories, and create a summary report"
 ```
 
-→ [**See detailed case studies**](docs/case_studies/README.md) with real session logs and outcomes
+→ [**See detailed case studies**](docs/source/examples/case_studies/README.md) with real session logs and outcomes
 
 #### Interactive Mode & Advanced Usage
 
@@ -1075,7 +1099,11 @@ All sessions are automatically logged with detailed information for debugging an
 
 To see how MassGen works in practice, check out these detailed case studies based on real session logs:
 
-- [**MassGen Case Studies**](docs/case_studies/README.md)
+**Featured:**
+- [**Multi-Turn Persistent Memory**](docs/source/examples/case_studies/multi-turn-persistent-memory.md) - Research-to-implementation workflow demonstrating memory system (v0.1.5) | [📹 Watch Demo](https://youtu.be/wWxxFgyw40Y)
+
+**All Case Studies:**
+- [**MassGen Case Studies**](docs/source/examples/case_studies/README.md)
 - [**Case Studies Documentation**](https://docs.massgen.ai/en/latest/examples/case_studies.html) - Browse case studies online
 
 ---
@@ -1083,37 +1111,67 @@ To see how MassGen works in practice, check out these detailed case studies base
 
 ## 🗺️ 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).
+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.
 
 ⚠️ **Early Stage Notice:** As MassGen is in active development, please expect upcoming breaking architecture changes as we continue to refine and improve the system.
 
-### Recent Achievements (v0.1.2)
+### Recent Achievements (v0.1.5)
+
+**🎉 Released: October 2025**
+
+#### Memory System
+- **PersistentMemory**: Long-term semantic memory storage via mem0 integration with fact extraction and retrieval across sessions
+- **ConversationMemory**: Short-term verbatim message tracking for active conversation context
+- **Automatic Context Compression**: Smart compression when approaching token limits with configurable thresholds (trigger_threshold, target_ratio)
+- **Cross-Agent Memory Sharing**: Agents share memory with turn-aware filtering to prevent temporal information leakage
+- **Context Monitoring**: Real-time token usage tracking with automatic compression triggers
+- **Session Management**: Memory isolation and continuation across runs with session naming support
+- **Qdrant Integration**: Vector database support for efficient semantic search in both server and local modes
+- **Configurable Memory Providers**: Support for OpenAI, Anthropic, Groq, and other mem0-compatible LLM and embedding providers
+
+#### Memory Configuration
+- **Global and Per-Agent Control**: Enable/disable memory at system or individual agent level
+- **Compression Settings**: Configurable trigger thresholds and target ratios for context window management
+- **Retrieval Configuration**: Customizable retrieval limits and smart filtering to exclude recent messages
+- **Memory Persistence**: Session continuation with named sessions for cross-session memory access
 
-**🎉 Released: October 22, 2025**
+#### Configuration Files
+- `gpt5mini_gemini_context_window_management.yaml` - Multi-agent with automatic context compression
+- `gpt5mini_gemini_research_to_implementation.yaml` - Research-to-implementation workflow with memory
+- `gpt5mini_high_reasoning_gemini.yaml` - High reasoning agents with memory integration
+- `gpt5mini_gemini_baseline_research_to_implementation.yaml` - Baseline research workflow for comparison
+- `single_agent_compression_test.yaml` - Single agent testing context compression behavior
 
-#### Intelligent Planning Mode
-- **Automatic Question Analysis**: New `_analyze_question_irreversibility()` method in orchestrator determines if MCP operations are reversible
-- **Selective Tool Blocking**: Granular control with `set_planning_mode_blocked_tools()`, `get_planning_mode_blocked_tools()`, and `is_mcp_tool_blocked()` methods
-- **Dynamic Behavior**: Read-only MCP operations allowed during coordination, write operations blocked for safety
-- **Zero Configuration**: Works transparently without setup
-- **Multi-Workspace Support**: Planning mode works across different workspaces without conflicts
-- **Test Coverage**: Comprehensive tests in `massgen/tests/test_intelligent_planning_mode.py`
-- **Documentation**: Complete guide in `docs/case_studies/INTELLIGENT_PLANNING_MODE.md`
+#### Documentation
+- Complete memory system user guide: `docs/source/user_guide/memory.rst`
+- Design decisions documentation explaining architectural choices
+- API reference for PersistentMemory, ConversationMemory, and ContextMonitor classes
+- Comprehensive troubleshooting guide and monitoring instructions
 
-#### Model Support & Improvements
-- **Claude 4.5 Haiku**: Added latest Claude Haiku model `claude-haiku-4-5-20251001`
-- **Model Priority Updates**: Reorganized Claude model list with updated defaults (`claude-sonnet-4-5-20250929`)
-- **Grok Web Search Fix**: Resolved `extra_body` parameter handling for Grok's Live Search API with new `_add_grok_search_params()` method
+#### Testing Infrastructure
+- Memory test suite: `test_agent_memory.py`, `test_conversation_memory.py`, `test_orchestrator_memory.py`, `test_persistent_memory.py`
 
-#### Configuration Updates
-- **Planning Mode Configs**: Updated 5 configurations in `massgen/configs/tools/planning/` with selective blocking examples
-- **Default Configuration**: Updated `three_agents_default.yaml` with Grok-4-fast model
+### Previous Achievements (v0.0.3 - v0.1.4)
 
-### Previous Achievements (v0.0.3 - v0.1.1)
+✅ **Multimodal Generation Tools (v0.1.4)**: Create images from text via DALL-E API, generate videos from descriptions, text-to-speech with audio transcription support, document generation for PDF/DOCX/XLSX/PPTX formats, image transformation capabilities for existing images
+
+✅ **Binary File Protection (v0.1.4)**: Automatic blocking prevents text tools from accessing 40+ binary file types including images, videos, audio, archives, and Office documents, intelligent error messages guide users to appropriate specialized tools for binary content
+
+✅ **Crawl4AI Integration (v0.1.4)**: Intelligent web scraping with LLM-powered content extraction and customizable extraction patterns for structured data retrieval from websites
+
+✅ **Post-Evaluation Workflow (v0.1.3)**: Winning agents evaluate their own answers before submission with submit and restart capabilities, supports answer confirmation and orchestration restart with feedback across all backends
+
+✅ **Multimodal Understanding Tools (v0.1.3)**: Analyze images, transcribe audio, extract video frames, and process documents (PDF/DOCX/XLSX/PPTX) with structured JSON output, works across all backends via OpenAI GPT-4.1 integration
+
+✅ **Docker Sudo Mode (v0.1.3)**: Privileged command execution in Docker containers for system-level operations requiring elevated permissions
+
+✅ **Intelligent Planning Mode (v0.1.2)**: Automatic question analysis determining operation irreversibility via `_analyze_question_irreversibility()` in orchestrator, selective tool blocking with `set_planning_mode_blocked_tools()` and `is_mcp_tool_blocked()` methods, read-only MCP operations during coordination with write operations blocked, zero-configuration transparent operation, multi-workspace support
+
+✅ **Model Updates (v0.1.2)**: Claude 4.5 Haiku model `claude-haiku-4-5-20251001`, reorganized Claude model priorities with `claude-sonnet-4-5-20250929` default, Grok web search fix with `_add_grok_search_params()` method for proper `extra_body` parameter handling
 
 ✅ **Custom Tools System (v0.1.1)**: User-defined Python function registration using `ToolManager` class in `massgen/tool/_manager.py`, cross-backend support alongside MCP servers, builtin/MCP/custom tool categories with automatic discovery, 40+ examples in `massgen/configs/tools/custom_tools/`, voting sensitivity controls with three-tier quality system (lenient/balanced/strict), answer novelty detection preventing duplicates
 
-✅ **Backend Enhancements (v0.1.1)**: Gemini architecture refactoring with extracted MCP management (`gemini_mcp_manager.py`), tracking (`gemini_trackers.py`), and utilities, new capabilities registry in `massgen/backend/capabilities.py` documenting feature support across backends
+✅ **Backend Enhancements (v0.1.1)**: Gemini architecture refactoring with extracted MCP management (`gemini_mcp_manager.py`), tracking (`gemini_trackers.py`), and utilities, new capabilities registry in `massgen/backend/capabilities.py` documenting feature support across all backends
 
 ✅ **PyPI Package Release (v0.1.0)**: Official distribution via `pip install massgen` with simplified installation, global `massgen` command accessible from any directory, comprehensive Sphinx documentation at [docs.massgen.ai](https://docs.massgen.ai/), interactive setup wizard with use case presets and API key management, enhanced CLI with `@examples/` prefix for built-in configurations
 
@@ -1213,19 +1271,21 @@ MassGen is currently in its foundational stage, with a focus on parallel, asynch
 
 We welcome community contributions to achieve these goals.
 
-### v0.1.3 Roadmap
+### v0.1.6 Roadmap
 
-Version 0.1.3 focuses on general interoperability and enterprise collaboration:
+Version 0.1.6 focuses on backend code refactoring for improved maintainability and developer experience:
 
-#### Required Features
-- **General Interoperability**: Enable MassGen to orchestrate agents from multiple external frameworks with unified interface
-- **Final Agent Submit/Restart Tools**: Enable final agent to decide whether to submit or restart orchestration
+#### Planned Features
+- **Backend Code Refactoring**: Major code refactoring for improved maintainability and developer experience with better code organization, modularity, and architectural improvements
 
 Key technical approach:
-- **Framework Integration**: Multi-agent coordination supporting external agent frameworks with specialized agent roles (researcher, analyst, critic, synthesizer)
-- **Submit/Restart**: Multi-step task verification with access to previous agents' responses and workspaces
+- **Code Architecture**: Enhanced code organization with improved modularity and separation of concerns
+- **Developer Experience**: Simplified backend extension points, improved API clarity, better error handling and debugging support
+- **Quality Assurance**: Comprehensive testing to ensure no functionality regressions
+
+**Target Release**: November 1, 2025 (Friday @ 9am PT)
 
-For detailed milestones and technical specifications, see the [full v0.1.3 roadmap](ROADMAP.md).
+For detailed milestones and technical specifications, see the [full v0.1.6 roadmap](ROADMAP_v0.1.6.md).
 
 ---