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

massgen/memory/examples.py

@@ -0,0 +1,237 @@
+# -*- coding: utf-8 -*-
+"""
+Usage examples for MassGen memory system.
+
+These examples demonstrate how to use conversation and persistent memory
+in your MassGen agents.
+"""
+
+import asyncio
+
+
+async def example_conversation_memory():
+    """Example: Using ConversationMemory for short-term dialogue."""
+    from massgen.memory import ConversationMemory
+
+    print("=" * 60)
+    print("Example 1: Conversation Memory (Short-term)")
+    print("=" * 60)
+
+    memory = ConversationMemory()
+
+    # Simulate a conversation
+    conversation = [
+        {"role": "user", "content": "Hello! My name is Alice."},
+        {"role": "assistant", "content": "Hi Alice! How can I help you today?"},
+        {"role": "user", "content": "I'm interested in learning about Python."},
+        {
+            "role": "assistant",
+            "content": "Great! Python is a versatile programming language...",
+        },
+    ]
+
+    # Add messages one by one
+    for msg in conversation:
+        await memory.add(msg)
+        print(f"Added: {msg['role']} - {msg['content'][:50]}...")
+
+    # Get all messages
+    await memory.get_messages()
+    print(f"\nTotal messages: {await memory.size()}")
+
+    # Get last message
+    last = await memory.get_last_message()
+    print(f"Last message role: {last['role']}")
+
+    # Filter by role
+    user_messages = await memory.get_messages_by_role("user")
+    print(f"User messages: {len(user_messages)}")
+
+    # Truncate to keep only recent messages
+    await memory.truncate_to_size(2)
+    print(f"After truncation: {await memory.size()} messages")
+
+    # Save and restore state
+    state = memory.state_dict()
+    print(f"\nState saved: {len(state['messages'])} messages")
+
+    # Create new memory from state
+    restored_memory = ConversationMemory()
+    restored_memory.load_state_dict(state)
+    print(f"State restored: {await restored_memory.size()} messages")
+
+    print("\n✅ Conversation memory example completed!\n")
+
+
+async def example_persistent_memory():
+    """
+    Example: Using PersistentMemory for long-term storage.
+
+    Note: This requires mem0 to be installed and proper backends configured.
+    This is a conceptual example - adjust backends as needed.
+    """
+    print("=" * 60)
+    print("Example 2: Persistent Memory (Long-term)")
+    print("=" * 60)
+
+    # NOTE: This is a conceptual example
+    # In practice, you need to provide actual MassGen backends
+    print("\n⚠️  This example requires actual LLM and embedding backends.")
+    print("     Uncomment and configure backends to run this example.\n")
+
+    # Conceptual usage:
+    """
+    from massgen.memory import PersistentMemory
+    from massgen.backend import OpenAIBackend  # Or your backend
+
+    # Initialize backends
+    llm_backend = OpenAIBackend(model="gpt-4")
+    embedding_backend = OpenAIBackend(model="text-embedding-3-small")
+
+    # Create persistent memory
+    memory = PersistentMemory(
+        agent_name="learning_assistant",
+        user_name="alice",
+        llm_backend=llm_backend,
+        embedding_backend=embedding_backend,
+        on_disk=True
+    )
+
+    # Record a conversation
+    await memory.record([
+        {"role": "user", "content": "I love Python programming"},
+        {"role": "assistant", "content": "That's great! Python is very versatile."}
+    ])
+    print("✓ Recorded conversation to long-term memory")
+
+    # Retrieve relevant memories
+    query = "What programming languages does the user like?"
+    relevant = await memory.retrieve(query)
+    print(f"Retrieved: {relevant}")
+
+    # Agent-controlled memory saving
+    result = await memory.save_to_memory(
+        thinking="User expressed interest in a topic",
+        content=["User likes Python", "User is a beginner"]
+    )
+    print(f"Save result: {result}")
+
+    # Agent-controlled memory recall
+    result = await memory.recall_from_memory(
+        keywords=["programming", "Python"],
+        limit=3
+    )
+    print(f"Recalled {result['count']} memories")
+    for mem in result['memories']:
+        print(f"  - {mem}")
+    """
+
+    print("✅ Persistent memory example completed!\n")
+
+
+async def example_combined_usage():
+    """Example: Using both memory types together."""
+    print("=" * 60)
+    print("Example 3: Combined Memory Usage")
+    print("=" * 60)
+
+    from massgen.memory import ConversationMemory
+
+    # Short-term memory for active conversation
+    short_term = ConversationMemory()
+
+    # Simulate ongoing conversation
+    messages = [
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "What's the weather like?"},
+        {"role": "assistant", "content": "I can help you check the weather!"},
+    ]
+
+    for msg in messages:
+        await short_term.add(msg)
+
+    print(f"Short-term memory: {await short_term.size()} messages")
+
+    # In a real agent, you would:
+    # 1. Retrieve relevant long-term memories based on current message
+    # 2. Inject them into the conversation context
+    # 3. Generate response
+    # 4. Add response to short-term memory
+    # 5. Optionally save important parts to long-term memory
+
+    print("\n💡 In production, this would be integrated with:")
+    print("   - LLM backend for generating responses")
+    print("   - Persistent memory for cross-session knowledge")
+    print("   - Tool system for agent-controlled memory")
+
+    print("\n✅ Combined usage example completed!\n")
+
+
+async def example_memory_management():
+    """Example: Memory management best practices."""
+    print("=" * 60)
+    print("Example 4: Memory Management")
+    print("=" * 60)
+
+    from massgen.memory import ConversationMemory
+
+    memory = ConversationMemory()
+
+    # Add many messages to simulate long conversation
+    for i in range(100):
+        await memory.add(
+            {
+                "role": "user" if i % 2 == 0 else "assistant",
+                "content": f"Message {i}",
+            },
+        )
+
+    print(f"Added {await memory.size()} messages")
+
+    # Best practice 1: Regular truncation
+    await memory.truncate_to_size(50)
+    print(f"After truncation: {await memory.size()} messages")
+
+    # Best practice 2: Get only recent messages
+    recent = await memory.get_messages(limit=10)
+    print(f"Retrieved last {len(recent)} messages")
+
+    # Best practice 3: Periodic cleanup
+    user_msgs = await memory.get_messages_by_role("user")
+    print(f"User sent {len(user_msgs)} messages")
+
+    # Best practice 4: Clear when starting new topic
+    await memory.clear()
+    print(f"After clearing: {await memory.size()} messages")
+
+    # Best practice 5: State persistence for crash recovery
+    await memory.add({"role": "user", "content": "Important message"})
+    state = memory.state_dict()
+    print(f"State saved with {len(state['messages'])} messages")
+
+    print("\n💾 Save this state to disk for persistence across restarts!")
+    print("\n✅ Memory management example completed!\n")
+
+
+async def main():
+    """Run all examples."""
+    print("\n🚀 MassGen Memory System Examples\n")
+
+    await example_conversation_memory()
+    await example_persistent_memory()
+    await example_combined_usage()
+    await example_memory_management()
+
+    print("=" * 60)
+    print("All examples completed! 🎉")
+    print("=" * 60)
+    print("\nNext steps:")
+    print("1. Install mem0: pip install mem0ai")
+    print("2. Configure your LLM and embedding backends")
+    print("3. Try persistent memory with real backends")
+    print("4. Integrate into your MassGen agents")
+    print("\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

massgen/message_templates.py

@@ -302,6 +302,8 @@ IMPORTANT: You are responding to the latest message in an ongoing conversation.
         original_system_message: Optional[str] = None,
         enable_image_generation: bool = False,
         enable_audio_generation: bool = False,
+        enable_file_generation: bool = False,
+        enable_video_generation: bool = False,
         has_irreversible_actions: bool = False,
         enable_command_execution: bool = False,
     ) -> str:
@@ -311,6 +313,8 @@ IMPORTANT: You are responding to the latest message in an ongoing conversation.
             original_system_message: The agent's original system message to preserve
             enable_image_generation: Whether image generation is enabled
             enable_audio_generation: Whether audio generation is enabled
+            enable_file_generation: Whether file generation is enabled
+            enable_video_generation: Whether video generation is enabled
             has_irreversible_actions: Whether agent has write access to context paths (requires actual file delivery)
             enable_command_execution: Whether command execution is enabled for this agent
         """
@@ -335,21 +339,165 @@ Present the best possible coordinated answer by combining the strengths from all
         # Add image generation instructions only if enabled
         if enable_image_generation:
             presentation_instructions += """For image generation tasks:
-- Extract image paths from the existing answer and resolve them in the shared reference.
-- Gather all agent-produced images (ignore non-existent files).
-- MUST call the generate-image tool with these input images to synthesize one final image combining their strengths.
-- MUST save the final outputand output the saved path.
-"""
+
+  **MANDATORY WORKFLOW - You MUST follow these steps in order:**
+
+  Step 1: **Check for existing images (REQUIRED)**
+  - First, list all files in the Shared Reference directory (temp_workspaces) to find ALL images from EVERY agent
+  - Look for image files (.png, .jpg, .jpeg, .gif, .webp, etc.) in each agent's workspace subdirectory
+
+  Step 2: **Understand ALL existing images (REQUIRED if images exist)**
+  - For EACH image file you found, you MUST call the **understand_image** tool to extract its key visual elements, composition, style, and quality
+  - Do this for images from yourself AND from other agents - analyze ALL images found
+  - DO NOT skip this step even if you think you know the content
+
+  Step 3: **Synthesize and generate final image (REQUIRED)**
+  - If existing images were found and analyzed:
+    * Synthesize ALL image analyses into a single, detailed, combined prompt
+    * The combined prompt should capture the best visual elements, composition, style, and quality from all analyzed images
+    * Call **image_to_image_generation** with this synthesized prompt and ALL images to create the final unified image
+  - If NO existing images were found:
+    * Generate a new image based directly on the original task requirements
+    * Call **text_to_image_generation** with a prompt derived from the original task
+
+  Step 4: **Save and report (REQUIRED)**
+  - Save the final generated image in your workspace
+  - Report the saved path in your final answer
+
+  **CRITICAL**: You MUST complete Steps 1-4 in order. Do not skip checking for existing images. Do not skip calling
+  understand_image on found images. This is a mandatory synthesis workflow.
+  """
+        #             presentation_instructions += """For image generation tasks:
+        # - Extract image paths from the existing answer and resolve them in the shared reference.
+        # - Gather all agent-produced images (ignore non-existent files).
+        # - IMPORTANT: If you find ANY existing images (from yourself or other agents), you MUST call the understand_image tool
+        #   to analyze EACH image and extract their key visual elements, composition, style, and quality.
+        # - IMPORTANT: Synthesize insights from all analyzed images into a detailed, combined prompt that captures the best elements.
+        # - IMPORTANT: Call text_to_image_generation with this synthesized prompt to generate the final image.
+        # - IMPORTANT: Save the final output in your workspace and output the saved path.
+        # - If no existing images are found, generate based on the original task requirements.
+        # """
         # Add audio generation instructions only if enabled
         if enable_audio_generation:
             presentation_instructions += """For audio generation tasks:
-- Extract audio paths from the existing answer and resolve them in the shared reference.
-- Gather ALL audio files produced by EVERY agent (ignore non-existent files).
-  IMPORTANT: You MUST call the generate_text_with_input_audio tool to obtain transcriptions
-  for EACH AND EVERY audio file from ALL agents - no audio should be skipped or overlooked.
-- MUST combine the strengths of all transcriptions into one final detailed transcription that captures the best elements from each.
-- MUST use the convert_text_to_audio tool to convert this final transcription to a new audio file and save it, then output the saved path.
-"""
+
+  **MANDATORY WORKFLOW - You MUST follow these steps in order:**
+
+  Step 1: **Check for existing audios (REQUIRED)**
+  - First, list all files in the Shared Reference directory (temp_workspaces) to find ALL audio files from EVERY agent
+  - Look for audio files (.mp3, .wav, .flac, etc.) in each agent's workspace subdirectory
+
+  Step 2: **Understand ALL existing audios (REQUIRED if audios exist)**
+  - For EACH audio file you found, you MUST call the **understand_audio** tool to extract its transcription
+  - Do this for audios from yourself AND from other agents - analyze ALL audios found
+  - DO NOT skip this step even if you think you know the content
+
+  Step 3: **Synthesize and generate final audio (REQUIRED)**
+  - If existing audios were found and analyzed:
+    * Synthesize ALL audio transcriptions into a single, detailed, combined transcription
+    * The combined transcription should capture the best content from all analyzed audios
+    * Call **text_to_speech_transcription_generation** with this synthesized transcription to create the final unified audio
+  - If NO existing audios were found:
+    * Generate a new audio based directly on the original task requirements
+    * Call **text_to_speech_transcription_generation** with a transcription derived from the original task
+
+  Step 4: **Save and report (REQUIRED)**
+  - Save the final generated audio in your workspace
+  - Report the saved path in your final answer
+
+  **CRITICAL**: You MUST complete Steps 1-4 in order. Do not skip checking for existing audios. Do not skip calling
+  understand_audio on found audios. This is a mandatory synthesis workflow.
+  """
+        #                         presentation_instructions += """For audio generation tasks:
+        # - Extract audio paths from the existing answer and resolve them in the shared reference.
+        # - Gather ALL audio files produced by EVERY agent (ignore non-existent files).
+        # - IMPORTANT: If you find ANY existing audios (from yourself or other agents), you MUST call the **understand_audio** tool to extract each audio's transcription.
+        # - IMPORTANT: Synthesize transcriptions from all audios into a detailed, combined transcription.
+        # - IMPORTANT: You MUST call the **text_to_speech_transcription_generation** tool with this synthesized transcription to generate the final audio.
+        # - IMPORTANT: Save the final output in your workspace and output the saved path.
+        # - If no existing audios are found, generate based on the original task requirements.
+        # """
+        # Add file generation instructions only if enabled
+        if enable_file_generation:
+            presentation_instructions += """For file generation tasks:
+
+  **MANDATORY WORKFLOW - You MUST follow these steps in order:**
+
+  Step 1: **Check for existing files (REQUIRED)**
+  - First, list all files in the Shared Reference directory (temp_workspaces) to find ALL files from EVERY agent
+  - Look for files of the requested type in each agent's workspace subdirectory
+
+  Step 2: **Understand ALL existing files (REQUIRED if files exist)**
+  - For EACH file you found, you MUST call the **understand_file** tool to extract its content, structure, and key elements
+  - Do this for files from yourself AND from other agents - analyze ALL files found
+  - DO NOT skip this step even if you think you know the content
+
+  Step 3: **Synthesize and generate final file (REQUIRED)**
+  - If existing files were found and analyzed:
+    * Synthesize ALL file contents into a single, detailed, combined content
+    * The combined content should capture the best elements, structure, and information from all analyzed files
+    * Call **text_to_file_generation** with this synthesized content to generate the final unified file
+  - If NO existing files were found:
+    * Generate a new file based directly on the original task requirements
+    * Call **text_to_file_generation** with content derived from the original task
+
+  Step 4: **Save and report (REQUIRED)**
+  - Save the final generated file in your workspace
+  - Report the saved path in your final answer
+
+  **CRITICAL**: You MUST complete Steps 1-4 in order. Do not skip checking for existing files. Do not skip calling
+  understand_file on found files. This is a mandatory synthesis workflow.
+  """
+        #             presentation_instructions += """For file generation tasks:
+        # - Extract file paths from the existing answer and resolve them in the shared reference.
+        # - Gather ALL files produced by EVERY agent (ignore non-existent files).
+        # - IMPORTANT: If you find ANY existing files (from yourself or other agents), you MUST call the **understand_file** tool to extract each file's content.
+        # - IMPORTANT: Synthesize contents from all files into a detailed, combined content.
+        # - IMPORTANT: You MUST call the **text_to_file_generation** tool with this synthesized content to generate the final file.
+        # - IMPORTANT: Save the final output in your workspace and output the saved path.
+        # - If no existing files are found, generate based on the original task requirements.
+        # """
+        # Add video generation instructions only if enabled
+        if enable_video_generation:
+            presentation_instructions += """For video generation tasks:
+
+  **MANDATORY WORKFLOW - You MUST follow these steps in order:**
+
+  Step 1: **Check for existing videos (REQUIRED)**
+  - First, list all files in the Shared Reference directory (temp_workspaces) to find ALL videos from EVERY agent
+  - Look for video files (.mp4, .avi, .mov, etc.) in each agent's workspace subdirectory
+
+  Step 2: **Understand ALL existing videos (REQUIRED if videos exist)**
+  - For EACH video file you found, you MUST call the **understand_video** tool to extract its description, visual features, and
+  key elements
+  - Do this for videos from yourself AND from other agents - analyze ALL videos found
+  - DO NOT skip this step even if you think you know the content
+
+  Step 3: **Synthesize and generate final video (REQUIRED)**
+  - If existing videos were found and analyzed:
+    * Synthesize ALL video descriptions into a single, detailed, combined prompt
+    * The combined prompt should capture the best visual elements, composition, motion, and style from all analyzed videos
+    * Call **text_to_video_generation** with this synthesized prompt to create the final unified video
+  - If NO existing videos were found:
+    * Generate a new video based directly on the original task requirements
+    * Call **text_to_video_generation** with a prompt derived from the original task
+
+  Step 4: **Save and report (REQUIRED)**
+  - Save the final generated video in your workspace
+  - Report the saved path in your final answer
+
+  **CRITICAL**: You MUST complete Steps 1-4 in order. Do not skip checking for existing videos. Do not skip calling
+  understand_video on found videos. This is a mandatory synthesis workflow.
+  """
+        #             presentation_instructions += """For video generation tasks:
+        # - Extract video paths from the existing answer and resolve them in the shared reference.
+        # - Gather ALL videos produced by EVERY agent (ignore non-existent files).
+        # - IMPORTANT: If you find ANY existing videos (from yourself or other agents), you MUST call the **understand_video** tool to extract each video's description and key features.
+        # - IMPORTANT: Synthesize descriptions from all videos into a detailed, combined prompt capturing the best elements.
+        # - IMPORTANT: You MUST call the **text_to_video_generation** tool with this synthesized prompt to generate the final video.
+        # - IMPORTANT: Save the final output in your workspace and output the saved path.
+        # - If no existing videos are found, generate based on the original task requirements.
+        # """
 
         # Add irreversible actions reminder if needed
         # TODO: Integrate more general irreversible actions handling in future (i.e., not just for context file delivery)