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

massgen/stream_chunk/__init__.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""
+Stream Chunk Module
+
+This module provides classes for handling streaming responses from LLM backends.
+It supports both text-based content (regular text, tool calls, reasoning) and
+multimodal content (images, audio, video, documents).
+
+Classes:
+    BaseStreamChunk: Abstract base class for all stream chunks
+    TextStreamChunk: Stream chunk for text-based content
+
+Enums:
+    ChunkType: Types of stream chunks
+
+Data Classes:
+    MediaMetadata: Metadata for media content
+"""
+
+from .base import BaseStreamChunk, ChunkType
+from .multimodal import MediaEncoding, MediaMetadata, MediaType, MultimodalStreamChunk
+from .text import TextStreamChunk
+
+__all__ = [
+    # Base classes
+    "BaseStreamChunk",
+    "ChunkType",
+    # Text chunks
+    "TextStreamChunk",
+    # Multimodal classes
+    "MediaType",
+    "MediaEncoding",
+    "MediaMetadata",
+    "MultimodalStreamChunk",
+]

massgen/stream_chunk/base.py

@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""
+Base classes for stream chunks.
+Provides abstract base class and enums for streaming responses.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class ChunkType(Enum):
+    """Enumeration of chunk types for streaming responses."""
+
+    # Text-based chunks
+    CONTENT = "content"
+    TOOL_CALLS = "tool_calls"
+    COMPLETE_MESSAGE = "complete_message"
+    COMPLETE_RESPONSE = "complete_response"
+    DONE = "done"
+    ERROR = "error"
+    AGENT_STATUS = "agent_status"
+    BACKEND_STATUS = "backend_status"
+
+    # Reasoning chunks (OpenAI Response API)
+    REASONING = "reasoning"
+    REASONING_DONE = "reasoning_done"
+    REASONING_SUMMARY = "reasoning_summary"
+    REASONING_SUMMARY_DONE = "reasoning_summary_done"
+
+    # MCP-related chunks
+    MCP_STATUS = "mcp_status"
+
+    # Multimodal chunks
+    MEDIA = "media"
+    MEDIA_PROGRESS = "media_progress"
+    ATTACHMENT = "attachment"
+    ATTACHMENT_COMPLETE = "attachment_complete"
+
+
+@dataclass
+class BaseStreamChunk(ABC):
+    """
+    Abstract base class for stream chunks.
+
+    All stream chunks must inherit from this class and implement
+    the required abstract methods for validation and serialization.
+
+    Attributes:
+        type: ChunkType enum value indicating the chunk type
+        source: Optional source identifier (e.g., agent_id, backend name)
+        timestamp: Optional timestamp when the chunk was created
+        sequence_number: Optional sequence number for ordering chunks
+    """
+
+    type: ChunkType
+    source: Optional[str] = None
+    timestamp: Optional[float] = None
+    sequence_number: Optional[int] = None
+
+    @abstractmethod
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert chunk to dictionary representation.
+
+        Returns:
+            Dictionary representation of the chunk, suitable for JSON serialization.
+        """
+
+    @abstractmethod
+    def validate(self) -> bool:
+        """
+        Validate chunk data integrity.
+
+        Returns:
+            True if the chunk data is valid, False otherwise.
+        """
+
+    def __post_init__(self):
+        """Post-initialization validation."""
+        # Ensure type is a ChunkType enum
+        if not isinstance(self.type, ChunkType):
+            # Try to convert string to ChunkType
+            if isinstance(self.type, str):
+                try:
+                    self.type = ChunkType(self.type)
+                except ValueError:
+                    raise ValueError(f"Invalid chunk type: {self.type}")
+            else:
+                raise TypeError(f"Chunk type must be ChunkType enum or string, got {type(self.type)}")

massgen/stream_chunk/multimodal.py

@@ -0,0 +1,237 @@
+# -*- coding: utf-8 -*-
+"""
+Multimodal stream chunk implementation.
+Handles media content including images, audio, video, and documents.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from .base import BaseStreamChunk, ChunkType
+
+
+class MediaType(Enum):
+    """Supported media types for multimodal content."""
+
+    IMAGE = "image"
+    AUDIO = "audio"
+    VIDEO = "video"
+    FILE = "file"
+    DOCUMENT = "document"
+
+
+class MediaEncoding(Enum):
+    """Media encoding types."""
+
+    BASE64 = "base64"
+    URL = "url"
+    FILE_PATH = "file_path"
+    FILE_ID = "file_id"
+    BINARY = "binary"
+
+
+@dataclass
+class MediaMetadata:
+    """
+    Metadata for media content.
+
+    Attributes:
+        mime_type: MIME type of the media (e.g., "image/jpeg", "audio/mp3")
+        size_bytes: Size of the media in bytes
+        width: Width in pixels (for images/video)
+        height: Height in pixels (for images/video)
+        duration_seconds: Duration in seconds (for audio/video)
+        filename: Original filename
+        checksum: Checksum for integrity verification (e.g., SHA-256)
+    """
+
+    mime_type: str
+    size_bytes: Optional[int] = None
+    width: Optional[int] = None
+    height: Optional[int] = None
+    duration_seconds: Optional[float] = None
+    filename: Optional[str] = None
+    checksum: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary, excluding None values."""
+        return {k: v for k, v in self.__dict__.items() if v is not None}
+
+
+@dataclass
+class MultimodalStreamChunk(BaseStreamChunk):
+    """
+    Stream chunk for multimodal content.
+
+    This class handles streaming of media content including:
+    - Images (JPEG, PNG, GIF, WebP)
+    - Audio files (MP3, WAV, etc.)
+    - Video files (MP4, WebM, etc.)
+    - Documents (PDF, etc.)
+    - Generic files
+
+    Supports both complete media and streaming/chunked media delivery.
+
+    Attributes:
+        type: ChunkType enum value (typically MEDIA or MEDIA_PROGRESS)
+        text_content: Optional text caption or description
+        media_type: Type of media (IMAGE, AUDIO, VIDEO, etc.)
+        media_encoding: How the media is encoded (BASE64, URL, etc.)
+        media_data: The actual media data (URL string, base64 string, bytes, or file_id)
+        media_metadata: Metadata about the media
+        attachments: List of multiple attachments (for batch processing)
+        progress_percentage: Progress percentage for large media (0-100)
+        bytes_transferred: Number of bytes transferred so far
+        total_bytes: Total bytes to transfer
+        is_partial: True if this is part of a larger media stream
+        chunk_index: Index of this chunk in the stream
+        total_chunks: Total number of expected chunks
+        source: Source identifier
+        timestamp: When the chunk was created
+        sequence_number: Sequence number for ordering
+    """
+
+    # Text content (optional caption/description)
+    text_content: Optional[str] = None
+
+    # Media fields
+    media_type: Optional[MediaType] = None
+    media_encoding: Optional[MediaEncoding] = None
+    media_data: Optional[Any] = None  # URL, base64 string, bytes, or file_id
+    media_metadata: Optional[MediaMetadata] = None
+
+    # Multiple attachments support
+    attachments: Optional[List[Dict[str, Any]]] = None
+
+    # Progress tracking for large media
+    progress_percentage: Optional[float] = None
+    bytes_transferred: Optional[int] = None
+    total_bytes: Optional[int] = None
+
+    # Streaming support
+    is_partial: bool = False
+    chunk_index: Optional[int] = None
+    total_chunks: Optional[int] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary with proper serialization.
+
+        Handles enum conversion and special types like bytes and MediaMetadata.
+
+        Returns:
+            Dictionary representation suitable for JSON serialization.
+        """
+        result = {}
+        for key, value in self.__dict__.items():
+            if value is not None:
+                if key == "type" and isinstance(value, ChunkType):
+                    result[key] = value.value
+                elif isinstance(value, (MediaType, MediaEncoding)):
+                    result[key] = value.value
+                elif isinstance(value, MediaMetadata):
+                    result[key] = value.to_dict()
+                elif isinstance(value, bytes):
+                    # Convert bytes to base64 for JSON serialization
+                    import base64
+
+                    result[key] = base64.b64encode(value).decode("utf-8")
+                else:
+                    result[key] = value
+        return result
+
+    def validate(self) -> bool:
+        """
+        Validate multimodal chunk integrity.
+
+        Checks that required fields are present based on chunk type.
+
+        Returns:
+            True if chunk is valid, False otherwise.
+        """
+        if self.type == ChunkType.MEDIA:
+            # Media chunks must have media_type, encoding, and data
+            return self.media_type is not None and self.media_encoding is not None and self.media_data is not None
+
+        elif self.type == ChunkType.MEDIA_PROGRESS:
+            # Progress chunks must have progress_percentage
+            return self.progress_percentage is not None
+
+        elif self.type == ChunkType.ATTACHMENT:
+            # Attachment chunks should have media data or attachments list
+            return self.media_data is not None or self.attachments is not None
+
+        elif self.type == ChunkType.ATTACHMENT_COMPLETE:
+            # Attachment complete chunks are always valid
+            return True
+
+        # Unknown chunk type or no specific validation
+        return True
+
+    def is_complete(self) -> bool:
+        """
+        Check if media streaming is complete.
+
+        For non-partial chunks, always returns True.
+        For partial chunks, checks if this is the last chunk.
+
+        Returns:
+            True if media is complete, False if more chunks expected.
+        """
+        if not self.is_partial:
+            return True
+
+        if self.chunk_index is not None and self.total_chunks is not None:
+            return self.chunk_index >= self.total_chunks - 1
+
+        return False
+
+    def get_progress(self) -> Optional[float]:
+        """
+        Get progress percentage.
+
+        Calculates progress from either:
+        - Explicit progress_percentage field
+        - bytes_transferred / total_bytes
+        - chunk_index / total_chunks
+
+        Returns:
+            Progress percentage (0-100) or None if not available.
+        """
+        if self.progress_percentage is not None:
+            return self.progress_percentage
+
+        if self.bytes_transferred is not None and self.total_bytes is not None and self.total_bytes > 0:
+            return (self.bytes_transferred / self.total_bytes) * 100
+
+        if self.chunk_index is not None and self.total_chunks is not None and self.total_chunks > 0:
+            return ((self.chunk_index + 1) / self.total_chunks) * 100
+
+        return None
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        parts = [f"MultimodalStreamChunk(type={self.type.value}"]
+
+        if self.media_type:
+            parts.append(f"media_type={self.media_type.value}")
+
+        if self.media_encoding:
+            parts.append(f"encoding={self.media_encoding.value}")
+
+        if self.text_content:
+            parts.append(f"text='{self.text_content[:30]}...'")
+
+        if self.is_partial:
+            parts.append(f"partial={self.chunk_index}/{self.total_chunks}")
+
+        progress = self.get_progress()
+        if progress is not None:
+            parts.append(f"progress={progress:.1f}%")
+
+        if self.source:
+            parts.append(f"source='{self.source}'")
+
+        return ", ".join(parts) + ")"

massgen/stream_chunk/text.py

@@ -0,0 +1,162 @@
+# -*- coding: utf-8 -*-
+"""
+Text stream chunk implementation.
+Handles text-based content including regular text, tool calls, and reasoning.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from .base import BaseStreamChunk, ChunkType
+
+
+@dataclass
+class TextStreamChunk(BaseStreamChunk):
+    """
+    Stream chunk for text-based content.
+
+    This class handles all text-based streaming content including:
+    - Regular text content
+    - Tool calls and function execution
+    - Reasoning text and summaries
+    - Status messages and errors
+    - Complete messages and responses
+
+    Attributes:
+        type: ChunkType enum value
+        content: Text content (for CONTENT, ERROR, STATUS chunks)
+        tool_calls: List of tool call dictionaries (for TOOL_CALLS chunks)
+        complete_message: Complete assistant message (for COMPLETE_MESSAGE chunks)
+        response: Raw API response (for COMPLETE_RESPONSE chunks)
+        error: Error message (for ERROR chunks)
+        status: Status message (for STATUS chunks)
+        reasoning_delta: Incremental reasoning text (for REASONING chunks)
+        reasoning_text: Complete reasoning text (for REASONING_DONE chunks)
+        reasoning_summary_delta: Incremental reasoning summary (for REASONING_SUMMARY chunks)
+        reasoning_summary_text: Complete reasoning summary (for REASONING_SUMMARY_DONE chunks)
+        item_id: Reasoning item identifier
+        content_index: Reasoning content index
+        summary_index: Reasoning summary index
+        source: Source identifier (e.g., agent_id, backend name)
+        timestamp: When the chunk was created
+        sequence_number: Sequence number for ordering
+    """
+
+    # Text content
+    content: Optional[str] = None
+
+    # Tool-related fields
+    tool_calls: Optional[List[Dict[str, Any]]] = None
+    complete_message: Optional[Dict[str, Any]] = None
+    response: Optional[Dict[str, Any]] = None
+
+    # Status fields
+    error: Optional[str] = None
+    status: Optional[str] = None
+
+    # Reasoning fields (OpenAI Response API)
+    reasoning_delta: Optional[str] = None
+    reasoning_text: Optional[str] = None
+    reasoning_summary_delta: Optional[str] = None
+    reasoning_summary_text: Optional[str] = None
+    item_id: Optional[str] = None
+    content_index: Optional[int] = None
+    summary_index: Optional[int] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary, excluding None values.
+
+        Returns:
+            Dictionary with all non-None fields, with ChunkType converted to string.
+        """
+        result = {}
+        for key, value in self.__dict__.items():
+            if value is not None:
+                if key == "type" and isinstance(value, ChunkType):
+                    result[key] = value.value
+                else:
+                    result[key] = value
+        return result
+
+    def validate(self) -> bool:
+        """
+        Validate text chunk integrity.
+
+        Checks that required fields are present based on chunk type.
+
+        Returns:
+            True if chunk is valid, False otherwise.
+        """
+        if self.type == ChunkType.CONTENT:
+            # Content chunks should have content (can be empty string)
+            return self.content is not None
+
+        elif self.type == ChunkType.TOOL_CALLS:
+            # Tool call chunks must have non-empty tool_calls list
+            return self.tool_calls is not None and len(self.tool_calls) > 0
+
+        elif self.type == ChunkType.COMPLETE_MESSAGE:
+            # Complete message chunks must have complete_message dict
+            return self.complete_message is not None
+
+        elif self.type == ChunkType.COMPLETE_RESPONSE:
+            # Complete response chunks must have response dict
+            return self.response is not None
+
+        elif self.type == ChunkType.ERROR:
+            # Error chunks must have error message
+            return self.error is not None or self.content is not None
+
+        elif self.type == ChunkType.REASONING:
+            # Reasoning chunks should have reasoning_delta
+            return self.reasoning_delta is not None
+
+        elif self.type == ChunkType.REASONING_DONE:
+            # Reasoning done chunks should have reasoning_text
+            return self.reasoning_text is not None
+
+        elif self.type == ChunkType.REASONING_SUMMARY:
+            # Reasoning summary chunks should have reasoning_summary_delta
+            return self.reasoning_summary_delta is not None
+
+        elif self.type == ChunkType.REASONING_SUMMARY_DONE:
+            # Reasoning summary done chunks should have reasoning_summary_text
+            return self.reasoning_summary_text is not None
+
+        elif self.type in [ChunkType.AGENT_STATUS, ChunkType.BACKEND_STATUS, ChunkType.MCP_STATUS]:
+            # Status chunks should have status or content
+            return self.status is not None or self.content is not None
+
+        elif self.type == ChunkType.DONE:
+            # Done chunks are always valid
+            return True
+
+        # Unknown chunk type or no specific validation
+        return True
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        parts = [f"TextStreamChunk(type={self.type.value}"]
+
+        if self.content:
+            content_preview = self.content[:50] + "..." if len(self.content) > 50 else self.content
+            parts.append(f"content='{content_preview}'")
+
+        if self.tool_calls:
+            parts.append(f"tool_calls={len(self.tool_calls)} calls")
+
+        if self.error:
+            parts.append(f"error='{self.error}'")
+
+        if self.status:
+            parts.append(f"status='{self.status}'")
+
+        if self.reasoning_delta:
+            parts.append(f"reasoning_delta='{self.reasoning_delta[:30]}...'")
+
+        if self.source:
+            parts.append(f"source='{self.source}'")
+
+        return ", ".join(parts) + ")"

massgen/tests/mcp_test_server.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Simple MCP test server for testing MCP integration.
+
+This server provides basic tools for testing MCP functionality.
+It implements the MCP protocol over stdio transport.
+"""
+
+import asyncio
+import json
+import sys
+from typing import Any, Dict
+
+
+class SimpleMCPServer:
+    """Simple MCP server implementation for testing."""
+
+    def __init__(self):
+        self.tools = {
+            "mcp_echo": {
+                "name": "mcp_echo",
+                "description": "Echo back the input text",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {"text": {"type": "string", "description": "Text to echo back"}},
+                    "required": ["text"],
+                },
+            },
+            "add_numbers": {
+                "name": "add_numbers",
+                "description": "Add two numbers together",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "a": {"type": "number", "description": "First number"},
+                        "b": {"type": "number", "description": "Second number"},
+                    },
+                    "required": ["a", "b"],
+                },
+            },
+            "get_current_time": {
+                "name": "get_current_time",
+                "description": "Get the current timestamp",
+                "inputSchema": {"type": "object", "properties": {}},
+            },
+        }
+
+    async def handle_initialize(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle initialize request."""
+        return {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {
+                "tools": {"listChanged": True},
+                "resources": {"subscribe": False, "listChanged": False},
+                "prompts": {"listChanged": False},
+            },
+            "serverInfo": {"name": "simple-test-server", "version": "1.0.0"},
+        }
+
+    async def handle_tools_list(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle tools/list request."""
+        return {"tools": list(self.tools.values())}
+
+    async def handle_tools_call(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle tools/call request."""
+        tool_name = params.get("name")
+        arguments = params.get("arguments", {})
+
+        if tool_name == "mcp_echo":
+            text = arguments.get("text", "")
+            return {"content": [{"type": "text", "text": f"Echo: {text}"}]}
+
+        elif tool_name == "add_numbers":
+            a = arguments.get("a", 0)
+            b = arguments.get("b", 0)
+            result = a + b
+            return {"content": [{"type": "text", "text": f"Result: {a} + {b} = {result}"}]}
+
+        elif tool_name == "get_current_time":
+            import datetime
+
+            now = datetime.datetime.now().isoformat()
+            return {"content": [{"type": "text", "text": f"Current time: {now}"}]}
+
+        else:
+            raise ValueError(f"Unknown tool: {tool_name}")
+
+    async def handle_request(self, request: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle incoming JSON-RPC request."""
+        method = request.get("method")
+        params = request.get("params", {})
+        request_id = request.get("id")
+
+        try:
+            if method == "initialize":
+                result = await self.handle_initialize(params)
+            elif method == "tools/list":
+                result = await self.handle_tools_list(params)
+            elif method == "tools/call":
+                result = await self.handle_tools_call(params)
+            else:
+                raise ValueError(f"Unknown method: {method}")
+
+            return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+        except Exception as e:
+            return {
+                "jsonrpc": "2.0",
+                "id": request_id,
+                "error": {"code": -32000, "message": str(e)},
+            }
+
+    async def run(self):
+        """Run the MCP server."""
+        while True:
+            try:
+                # Read line from stdin
+                line = sys.stdin.readline()
+                if not line:
+                    break
+
+                # Parse JSON-RPC request
+                request = json.loads(line.strip())
+
+                # Handle request
+                response = await self.handle_request(request)
+
+                # Send response to stdout
+                json.dump(response, sys.stdout)
+                sys.stdout.write("\n")
+                sys.stdout.flush()
+
+            except KeyboardInterrupt:
+                break
+            except Exception as e:
+                # Send error response
+                error_response = {
+                    "jsonrpc": "2.0",
+                    "id": None,
+                    "error": {"code": -32603, "message": f"Internal error: {str(e)}"},
+                }
+                json.dump(error_response, sys.stdout)
+                sys.stdout.write("\n")
+                sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    server = SimpleMCPServer()
+    asyncio.run(server.run())

massgen/tests/multi_turn_conversation_design.md

@@ -4,14 +4,6 @@
 
 This document outlines the design approach for implementing multi-turn conversations in the MassGen orchestrator, based on the proven approach used in MassGen v0.0.1.
 
-## Current State
-
-The current orchestrator has **partial multi-turn support**:
-- ✅ Accepts conversation history through `chat(messages)` interface
-- ✅ Maintains conversation history at orchestrator level
-- ❌ **Limited**: Only processes the last user message for coordination
-- ❌ **CLI Issue**: Multi-agent mode with history bypasses coordination UI display
-
 ## V0.0.1 Approach Analysis
 
 ### Key Innovation: Dynamic Context Reconstruction