massgen 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

massgen/configs/README.md

@@ -227,7 +227,101 @@ Most configurations use environment variables for API keys:so
 
 ## Release History & Examples
 
-### v0.1.4 - Latest
+### v0.1.6 - Latest
+**New Features:** Framework Interoperability & Backend Refactoring
+
+**Configuration Files:**
+- `ag2_lesson_planner_example.yaml` - AG2 nested chat as custom tool (supports streaming)
+- `langgraph_lesson_planner_example.yaml` - LangGraph workflows integrated as tools
+- `agentscope_lesson_planner_example.yaml` - AgentScope agent system integration
+- `openai_assistant_lesson_planner_example.yaml` - OpenAI Assistants as tools
+- `smolagent_lesson_planner_example.yaml` - HuggingFace SmoLAgent integration
+- `ag2_and_langgraph_lesson_planner.yaml` - Multi-framework collaboration (AG2 + LangGraph)
+- `ag2_and_openai_assistant_lesson_planner.yaml` - AG2 + OpenAI Assistants combination
+- `two_models_with_tools_example.yaml` - Multiple models with custom tools
+
+**Key Features:**
+- **Framework Interoperability**: Use agents from external frameworks (AG2, LangGraph, AgentScope, OpenAI Assistants, SmoLAgent) as MassGen tools
+- **Streaming Support**: AG2 supports streaming; other frameworks return complete results
+- **Configuration Validator**: Pre-flight YAML validation with detailed error messages
+- **Unified Tool Execution**: ToolExecutionConfig dataclass for consistent tool handling
+- **Gemini Simplification**: Major backend cleanup reducing codebase by 1,598 lines
+
+**Try It:**
+```bash
+# Use AG2 agents for lesson planning (supports streaming)
+# Requirements: pip install pyautogen, OPENAI_API_KEY must be set
+massgen --config massgen/configs/tools/custom_tools/ag2_lesson_planner_example.yaml "Create a lesson plan for photosynthesis"
+
+# Use LangGraph workflows as tools
+# Requirements: pip install langgraph langchain-openai langchain-core, OPENAI_API_KEY must be set
+massgen --config massgen/configs/tools/custom_tools/langgraph_lesson_planner_example.yaml "Create a lesson plan for photosynthesis"
+
+# Use AgentScope multi-agent framework as tools
+# Requirements: pip install agentscope, OPENAI_API_KEY must be set
+massgen --config massgen/configs/tools/custom_tools/agentscope_lesson_planner_example.yaml "Create a lesson plan for photosynthesis"
+
+# Use OpenAI Assistants API as tools
+# Requirements: pip install openai, OPENAI_API_KEY must be set
+massgen --config massgen/configs/tools/custom_tools/openai_assistant_lesson_planner_example.yaml "Create a lesson plan for photosynthesis"
+
+# Use SmolAgent (HuggingFace) as tools
+# Requirements: pip install smolagents, OPENAI_API_KEY must be set
+massgen --config massgen/configs/tools/custom_tools/smolagent_lesson_planner_example.yaml "Create a lesson plan for photosynthesis"
+
+# Combine multiple frameworks
+# Requirements: pip install pyautogen langgraph langchain-openai langchain-core, OPENAI_API_KEY must be set
+massgen --config massgen/configs/tools/custom_tools/ag2_and_langgraph_lesson_planner.yaml "Create a lesson plan for photosynthesis"
+```
+
+### v0.1.5
+**New Features:** Memory System with Semantic Retrieval
+
+**Configuration Files:**
+- `gpt5mini_gemini_context_window_management.yaml` - Multi-agent with automatic context compression
+- `gpt5mini_gemini_research_to_implementation.yaml` - Research-to-implementation workflow (featured in case study)
+- `gpt5mini_high_reasoning_gemini.yaml` - High reasoning agents with memory integration
+- `gpt5mini_gemini_baseline_research_to_implementation.yaml` - Baseline research workflow
+- `single_agent_compression_test.yaml` - Testing context compression behavior
+
+**Key Features:**
+- **Long-Term Memory**: Semantic storage via mem0 with vector database integration
+- **Context Compression**: Automatic compression when approaching token limits
+- **Cross-Agent Sharing**: Agents learn from each other's experiences
+- **Session Management**: Memory persistence across conversations
+
+**Try it:**
+```bash
+# Install or upgrade
+pip install --upgrade massgen
+
+# 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
+
+# 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
+
+```bash
+# 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."
+```
+
+### v0.1.4
 **New Features:** Multimodal Generation Tools, Binary File Protection, Crawl4AI Integration
 
 **Configuration Files:**
@@ -237,12 +331,6 @@ Most configurations use environment variables for API keys:so
 - `text_to_file_generation_single.yaml` / `text_to_file_generation_multi.yaml` - Document generation
 - `crawl4ai_example.yaml` - Web scraping configuration
 
-**Documentation:**
-- `README_PYPI.md` - Standalone PyPI package documentation
-- `docs/dev_notes/release_checklist.md` - Release workflow guide
-- `docs/source/user_guide/protected_paths.rst` - Binary file protection documentation
-- `.github/workflows/docs-automation.yml` - Documentation CI/CD automation
-
 **Key Features:**
 - **Generation Tools**: Create images, videos, audio, and documents using OpenAI APIs
 - **Binary File Protection**: Automatic blocking prevents text tools from reading 40+ binary file types
@@ -251,9 +339,6 @@ Most configurations use environment variables for API keys:so
 
 **Try it:**
 ```bash
-# Install or upgrade
-pip install --upgrade massgen
-
 # Generate an image from text
 massgen --config @examples/tools/custom_tools/multimodal_tools/text_to_image_generation_single \
   "Please generate an image of a cat in space."

massgen/configs/memory/gpt5mini_gemini_baseline_research_to_implementation.yaml

@@ -0,0 +1,94 @@
+# Example Configuration: Memory-Enhanced Research-to-Implementation Workflow
+#
+# Use Case: Demonstrates how memory enables strategic self-improvement
+#
+# This configuration demonstrates MassGen's self-evolution capabilities:
+# - Session 1: Research multi-agent AI papers using crawl4ai
+# - Session 2: Apply research findings to improve MassGen itself
+# - Memory: Bridges research phase to implementation analysis
+# - Self-improvement: Agents use external research to enhance their own architecture
+#
+# Prerequisites:
+# 1. Start Qdrant server:
+#    docker run -d -p 6333:6333 -p 6334:6334 -v $(pwd)/.massgen/qdrant_storage:/qdrant/storage:z qdrant/qdrant
+#
+# 2. Start crawl4ai Docker container:
+#    docker pull unclecode/crawl4ai:latest
+#    docker run -d -p 11235:11235 --name crawl4ai --shm-size=1g unclecode/crawl4ai:latest
+#
+# 3. Verify both containers are running:
+#    docker ps | grep -E "qdrant|crawl4ai"
+#
+# Run Session 1 (Research Phase):
+#   uv run massgen --config @examples/memory/gpt5mini_gemini_baseline_research_to_implementation.yaml "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."
+#
+# Run Session 2 (Implementation Analysis) - Same session:
+#   uv run massgen --config @examples/memory/gpt5mini_gemini_baseline_research_to_implementation.yaml "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."
+#
+# Or in a new session (still accesses memories from Session 1):
+#   Change session_name in config or run interactively to continue
+
+# ====================
+# AGENT DEFINITIONS
+# ====================
+agents:
+  - id: "agent_a"
+    backend:
+      type: "openai"
+      model: "gpt-5-mini"
+      text:
+        verbosity: "medium"
+      reasoning:
+        effort: "medium"
+        summary: "auto"
+      cwd: "workspace1"
+
+      # Register crawl4ai custom tools for web scraping
+      custom_tools:
+        - name: ["crawl4ai_md", "crawl4ai_html", "crawl4ai_screenshot", "crawl4ai_pdf", "crawl4ai_execute_js", "crawl4ai_crawl"]
+          category: "web_scraping"
+          path: "massgen/tool/_web_tools/crawl4ai_tool.py"
+          function: ["crawl4ai_md", "crawl4ai_html", "crawl4ai_screenshot", "crawl4ai_pdf", "crawl4ai_execute_js", "crawl4ai_crawl"]
+
+  - id: "agent_b"
+    backend:
+      type: "gemini"
+      model: "gemini-2.5-flash"
+      cwd: "workspace2"
+
+      # Register crawl4ai custom tools for web scraping
+      custom_tools:
+        - name: ["crawl4ai_md", "crawl4ai_html", "crawl4ai_screenshot", "crawl4ai_pdf", "crawl4ai_execute_js", "crawl4ai_crawl"]
+          category: "web_scraping"
+          path: "massgen/tool/_web_tools/crawl4ai_tool.py"
+          function: ["crawl4ai_md", "crawl4ai_html", "crawl4ai_screenshot", "crawl4ai_pdf", "crawl4ai_execute_js", "crawl4ai_crawl"]
+
+
+# ====================
+# MEMORY CONFIGURATION
+# ====================
+memory:
+  enabled: false
+
+# ====================
+# ORCHESTRATOR CONFIGURATION
+# ====================
+orchestrator:
+  # Multi-turn mode for interactive research sessions
+  session_storage: "research_sessions"
+  agent_temporary_workspace: "research_workspaces"
+  snapshot_storage: "research_snapshots"
+
+  # Give agents read access to MassGen codebase for Phase 2
+  context_paths:
+    - path: "massgen"
+      permission: "read"
+    - path: "docs"
+      permission: "read"
+
+# ====================
+# UI CONFIGURATION
+# ====================
+ui:
+  display_type: "rich_terminal"
+  logging_enabled: true

massgen/configs/memory/gpt5mini_gemini_context_window_management.yaml

@@ -0,0 +1,187 @@
+# Example Configuration: Context Window Management with Memory
+#
+# Use Case: Demonstrates automatic context compression when approaching token limits
+#
+# This configuration demonstrates:
+# - Automatic context window monitoring and compression
+# - Token-aware conversation management (75% threshold, 40% target)
+# - Persistent memory integration for long-term knowledge retention
+# - Graceful handling when context window fills up
+# - Multi-agent collaboration with shared context management
+#
+# Run with:
+# uv run massgen --config @examples/memory/gpt5mini_gemini_context_window_management.yaml "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."
+
+# ====================
+# AGENT DEFINITIONS
+# ====================
+agents:
+  - id: "agent_a"
+    backend:
+      # Use GPT-5-mini with medium reasoning
+      type: "openai"
+      model: "gpt-5-mini"
+      text:
+        verbosity: "medium"
+      reasoning:
+        effort: "medium"
+        summary: "auto"
+      cwd: "workspace1"
+
+  - id: "agent_b"
+    backend:
+      # Use Gemini 2.5 Flash for cost-effective testing
+      type: "gemini"
+      model: "gemini-2.5-flash"
+      cwd: "workspace2"
+
+# ====================
+# MEMORY CONFIGURATION
+# ====================
+memory:
+  # Enable/disable persistent memory (default: true)
+  enabled: true
+
+  # Memory configuration
+  conversation_memory:
+    enabled: true  # Short-term conversation tracking (recommended: always true)
+
+  persistent_memory:
+    enabled: true  # Long-term knowledge storage (set to false to disable)
+    on_disk: true  # Persist across restarts
+    # session_name: "test_session"  # Optional - if not specified, auto-generates unique ID
+                                     # Format: agent_storyteller_20251023_143022_a1b2c3
+                                     # Specify to continue a specific session
+
+    # Vector store backend (default: qdrant)
+    vector_store: "qdrant"
+
+    # LLM configuration for memory operations (fact extraction)
+    # RECOMMENDED: Use mem0's native LLMs (no adapter overhead, no async complexity)
+    llm:
+      provider: "openai"  # Options: openai, anthropic, groq, together, etc.
+      model: "gpt-4.1-nano-2025-04-14"  # Fast and cheap model for memory ops (mem0's default)
+
+    # Embedding configuration (uses mem0's native embedders)
+    # RECOMMENDED: Specify provider and model for clarity
+    embedding:
+      provider: "openai"  # Options: openai, together, azure_openai, gemini, huggingface, etc.
+      model: "text-embedding-3-small"  # OpenAI's efficient embedding model
+
+    # Qdrant client configuration
+    # IMPORTANT: For multi-agent setups, use server mode to avoid concurrent access errors
+    qdrant:
+      mode: "server"  # Options: "server" (recommended for multi-agent) or "local" (single agent only)
+      host: "localhost"  # Qdrant server host (default: localhost)
+      port: 6333         # Qdrant server port (default: 6333)
+      # For local mode (single agent only):
+      # mode: "local"
+      # path: ".massgen/qdrant"  # Local storage path
+
+  # Context window management thresholds
+  compression:
+    trigger_threshold: 0.25  # Compress when context usage exceeds 25%
+    target_ratio: 0.10       # Target 10% of context after compression
+
+  # Memory retrieval configuration
+  retrieval:
+    limit: 5              # Number of memory facts to retrieve from mem0 (default: 5)
+    exclude_recent: true  # Only retrieve after compression to avoid duplicates (default: true)
+
+# Memory system behavior when enabled:
+# - ConversationMemory: Tracks short-term conversation history (verbatim messages)
+# - PersistentMemory: Stores long-term knowledge in vector database (extracted facts via mem0)
+# - Automatic compression: Triggers at threshold, removes old messages from conversation_memory
+# - Smart retrieval: Only retrieves from persistent_memory AFTER compression
+#   - Before compression: All context in conversation_memory, no retrieval (avoids duplicates)
+#   - After compression: Retrieves relevant facts from compressed messages
+# - Each agent gets separate memory: agent_name defaults to agent ID (agent_a, agent_b)
+#
+# How mem0 works:
+# - When recording: mem0's LLM extracts key facts from conversations
+# - When retrieving: Returns extracted facts (e.g., "User explored Mars", not full conversation)
+# - retrieval.limit controls how many facts to retrieve (each fact is ~1 sentence)
+#
+# Session management (UNIFIED):
+# - Each agent gets separate memory (agent_name = agent ID: agent_a, agent_b)
+# - Session ID is unified between orchestrator and memory system:
+#   - Interactive mode: session_YYYYMMDD_HHMMSS (created at start, shared by all turns)
+#   - Single question: temp_YYYYMMDD_HHMMSS (created per run, isolated)
+# - Memories are isolated per session: agent_a in session_1 can't access session_2 memories
+# - To continue a previous session: Specify session_name in YAML (overrides auto-generation)
+# - For cross-session memory: Remove session_name from YAML or set to null
+# - Qdrant database: Shared at .massgen/qdrant, filtered by agent_id + session_id
+#
+# To disable persistent memory for testing, set:
+#   memory.persistent_memory.enabled: false
+#
+# See massgen/memory/docs/ for detailed documentation.
+
+# ====================
+# ORCHESTRATOR CONFIGURATION
+# ====================
+orchestrator:
+  # Multi-turn mode to enable interactive storytelling
+  session_storage: "memory_test_sessions"
+
+  # Agent workspace for any file operations
+  agent_temporary_workspace: "memory_test_workspaces"
+  snapshot_storage: "memory_test_snapshots"
+
+  # Additional context paths
+  context_paths:
+    - path: "massgen"
+      permission: "read"
+
+# ====================
+# UI CONFIGURATION
+# ====================
+ui:
+  display_type: "rich_terminal"
+  logging_enabled: true
+
+# ====================
+# EXECUTION FLOW
+# ====================
+# What happens:
+# 1. User starts an interactive story with the agent
+# 2. Agent responds with detailed narrative (400-600 words per turn)
+# 3. As conversation continues, token usage is monitored automatically
+# 4. When context usage reaches 75% of model's limit:
+#    - System logs: "📊 Context usage: X / Y tokens (Z%) - compressing old context"
+#    - Old messages are compressed into persistent memory (if configured)
+#    - Recent messages (fitting in 40% of context window) are kept
+#    - Compression details logged: "📦 Compressed N messages (X tokens) into long-term memory"
+# 5. Agent continues seamlessly with compressed context
+# 6. Story maintains consistency by referencing persistent memories
+# 7. Process repeats as needed for very long conversations
+#
+# Expected logs with persistent memory:
+#
+# Turn 1-10 (Before compression):
+#   📊 Context Window (Turn 5): 45,000 / 128,000 tokens (35%)
+#   ⏭️  Skipping retrieval (no compression yet, all context in conversation_memory)
+#
+# Turn 11 (Compression triggers):
+#   ⚠️  Context Window (Turn 11): 96,000 / 128,000 tokens (75%) - Approaching limit!
+#   🔄 Attempting compression (96,000 → 51,200 tokens)
+#   📦 Context compressed: Removed 15 old messages (44,800 tokens).
+#      Kept 8 recent messages (51,200 tokens).
+#      Old messages remain accessible via semantic search.
+#   ✅ Conversation history updated after compression: 8 messages
+#
+# Turn 12+ (After compression):
+#   🔍 Retrieving compressed memories (limit=5, compressed=True)...
+#   💭 Retrieved 3 memory fact(s) from mem0
+#   [Agent sees: retrieved facts + recent 8 messages - no duplication!]
+#
+# Expected output WITHOUT persistent memory:
+#   📦 Context compressed: Removed 15 messages (44,800 tokens).
+#      No persistent memory - old messages NOT retrievable.
+#
+# Token Budget Allocation (after compression):
+# - Conversation history: 40% (kept in active context)
+# - Retrieved memories: ~5 facts (~100-250 tokens)
+# - New user messages: varies
+# - System prompt overhead: varies
+# - Response generation: varies

massgen/configs/memory/gpt5mini_gemini_research_to_implementation.yaml

@@ -0,0 +1,127 @@
+# Example Configuration: Memory-Enhanced Research-to-Implementation Workflow
+#
+# Use Case: Demonstrates how memory enables strategic self-improvement
+#
+# This configuration demonstrates MassGen's self-evolution capabilities:
+# - Session 1: Research multi-agent AI papers using crawl4ai
+# - Session 2: Apply research findings to say how to improve MassGen itself
+# - Memory: Bridges research phase to implementation analysis
+# - Self-improvement: Agents use external research to enhance their own architecture
+#
+# Prerequisites:
+# 1. Start Qdrant server:
+#    docker run -d -p 6333:6333 -p 6334:6334 -v $(pwd)/.massgen/qdrant_storage:/qdrant/storage:z qdrant/qdrant
+#
+# 2. Start crawl4ai Docker container:
+#    docker pull unclecode/crawl4ai:latest
+#    docker run -d -p 11235:11235 --name crawl4ai --shm-size=1g unclecode/crawl4ai:latest
+#
+# 3. Verify both containers are running:
+#    docker ps | grep -E "qdrant|crawl4ai"
+#
+# Run Session 1 (Research Phase):
+#   uv run massgen --config @examples/memory/gpt5mini_gemini_research_to_implementation.yaml "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."
+#
+# Run Session 2 (Implementation Analysis) - 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."
+#
+
+# ====================
+# AGENT DEFINITIONS
+# ====================
+agents:
+  - id: "agent_a"
+    backend:
+      type: "openai"
+      model: "gpt-5-mini"
+      text:
+        verbosity: "medium"
+      reasoning:
+        effort: "medium"
+        summary: "auto"
+      cwd: "workspace1"
+
+      # Register crawl4ai custom tools for web scraping
+      custom_tools:
+        - name: ["crawl4ai_md", "crawl4ai_html", "crawl4ai_screenshot", "crawl4ai_pdf", "crawl4ai_execute_js", "crawl4ai_crawl"]
+          category: "web_scraping"
+          path: "massgen/tool/_web_tools/crawl4ai_tool.py"
+          function: ["crawl4ai_md", "crawl4ai_html", "crawl4ai_screenshot", "crawl4ai_pdf", "crawl4ai_execute_js", "crawl4ai_crawl"]
+
+  - id: "agent_b"
+    backend:
+      type: "gemini"
+      model: "gemini-2.5-flash"
+      cwd: "workspace2"
+
+      # Register crawl4ai custom tools for web scraping
+      custom_tools:
+        - name: ["crawl4ai_md", "crawl4ai_html", "crawl4ai_screenshot", "crawl4ai_pdf", "crawl4ai_execute_js", "crawl4ai_crawl"]
+          category: "web_scraping"
+          path: "massgen/tool/_web_tools/crawl4ai_tool.py"
+          function: ["crawl4ai_md", "crawl4ai_html", "crawl4ai_screenshot", "crawl4ai_pdf", "crawl4ai_execute_js", "crawl4ai_crawl"]
+
+
+# ====================
+# MEMORY CONFIGURATION
+# ====================
+memory:
+  enabled: true
+
+  conversation_memory:
+    enabled: true
+
+  persistent_memory:
+    enabled: true
+    on_disk: true
+    session_name: "research_to_implementation"  # Same session for both phases
+    vector_store: "qdrant"
+
+    # LLM configuration for memory operations
+    llm:
+      provider: "openai"
+      model: "gpt-4.1-nano-2025-04-14"
+
+    # Embedding configuration
+    embedding:
+      provider: "openai"
+      model: "text-embedding-3-small"
+
+    # Qdrant server configuration (required for multi-agent)
+    qdrant:
+      mode: "server"
+      host: "localhost"
+      port: 6333
+
+  # Context window management
+  compression:
+    trigger_threshold: 0.75  # Compress at 75%
+    target_ratio: 0.40       # Keep 40% after compression
+
+  # Memory retrieval configuration
+  retrieval:
+    limit: 10             # Get more facts for cross-phase synthesis
+    exclude_recent: true  # Only retrieve after compression
+
+# ====================
+# ORCHESTRATOR CONFIGURATION
+# ====================
+orchestrator:
+  # Multi-turn mode for interactive research sessions
+  session_storage: "research_sessions"
+  agent_temporary_workspace: "research_workspaces"
+  snapshot_storage: "research_snapshots"
+
+  # Give agents read access to MassGen codebase for Phase 2
+  context_paths:
+    - path: "massgen"
+      permission: "read"
+    - path: "docs"
+      permission: "read"
+
+# ====================
+# UI CONFIGURATION
+# ====================
+ui:
+  display_type: "rich_terminal"
+  logging_enabled: true

massgen/configs/memory/gpt5mini_high_reasoning_gemini.yaml

@@ -0,0 +1,107 @@
+# Example Configuration: Context Window Management with Memory
+#
+# Use Case: Demonstrates automatic context compression when approaching token limits
+#
+# This configuration demonstrates:
+# - Automatic context window monitoring and compression
+# - Token-aware conversation management (75% threshold, 40% target)
+# - Persistent memory integration for long-term knowledge retention
+# - Graceful handling when context window fills up
+# - Multi-agent collaboration with shared context management
+#
+# Run with:
+# uv run massgen --config @examples/memory/gpt5mini_high_reasoning_gemini.yaml "Analyze the pros and cons of using LLMs in commercial applications."
+
+# ====================
+# AGENT DEFINITIONS
+# ====================
+agents:
+  - id: "agent_a"
+    backend:
+      # Use GPT-5-mini with medium reasoning
+      type: "openai"
+      model: "gpt-5-mini"
+      text:
+        verbosity: "medium"
+      reasoning:
+        effort: "high"
+        summary: "auto"
+      enable_web_search: true
+
+  - id: "agent_b"
+    backend:
+      # Use Gemini 2.5 Flash for cost-effective testing
+      type: "gemini"
+      model: "gemini-2.5-flash"
+      enable_web_search: true
+
+# ====================
+# MEMORY CONFIGURATION
+# ====================
+memory:
+  # Enable/disable persistent memory (default: true)
+  enabled: true
+
+  # Memory configuration
+  conversation_memory:
+    enabled: true  # Short-term conversation tracking (recommended: always true)
+
+  persistent_memory:
+    enabled: true  # Long-term knowledge storage (set to false to disable)
+    on_disk: true  # Persist across restarts
+    # session_name: "test_session"  # Optional - if not specified, auto-generates unique ID
+                                     # Format: agent_storyteller_20251023_143022_a1b2c3
+                                     # Specify to continue a specific session
+
+    # Vector store backend (default: qdrant)
+    vector_store: "qdrant"
+
+    # LLM configuration for memory operations (fact extraction)
+    # RECOMMENDED: Use mem0's native LLMs (no adapter overhead, no async complexity)
+    llm:
+      provider: "openai"  # Options: openai, anthropic, groq, together, etc.
+      model: "gpt-4.1-nano-2025-04-14"  # Fast and cheap model for memory ops (mem0's default)
+
+    # Embedding configuration (uses mem0's native embedders)
+    # RECOMMENDED: Specify provider and model for clarity
+    embedding:
+      provider: "openai"  # Options: openai, together, azure_openai, gemini, huggingface, etc.
+      model: "text-embedding-3-small"  # OpenAI's efficient embedding model
+
+    # Qdrant client configuration
+    # IMPORTANT: For multi-agent setups, use server mode to avoid concurrent access errors
+    qdrant:
+      mode: "server"  # Options: "server" (recommended for multi-agent) or "local" (single agent only)
+      host: "localhost"  # Qdrant server host (default: localhost)
+      port: 6333         # Qdrant server port (default: 6333)
+      # For local mode (single agent only):
+      # mode: "local"
+      # path: ".massgen/qdrant"  # Local storage path
+
+  # Context window management thresholds
+  compression:
+    trigger_threshold: 0.25  # Compress when context usage exceeds 25%
+    target_ratio: 0.10       # Target 10% of context after compression
+
+  # Memory retrieval configuration
+  retrieval:
+    limit: 5              # Number of memory facts to retrieve from mem0 (default: 5)
+    exclude_recent: true  # Only retrieve after compression to avoid duplicates (default: true)
+
+# ====================
+# ORCHESTRATOR CONFIGURATION
+# ====================
+orchestrator:
+  # Multi-turn mode to enable interactive storytelling
+  session_storage: "memory_test_sessions"
+
+  # Agent workspace for any file operations
+  agent_temporary_workspace: "memory_test_workspaces"
+  snapshot_storage: "memory_test_snapshots"
+
+# ====================
+# UI CONFIGURATION
+# ====================
+ui:
+  display_type: "rich_terminal"
+  logging_enabled: true