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

massgen/formatter/__init__.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""
+Message formatting utilities.
+Provides utility classes for message formatting and conversion.
+"""
+from ._chat_completions_formatter import ChatCompletionsFormatter
+from ._claude_formatter import ClaudeFormatter
+from ._response_formatter import ResponseFormatter
+
+__all__ = ["ChatCompletionsFormatter", "ResponseFormatter", "ClaudeFormatter"]

massgen/formatter/_chat_completions_formatter.py

@@ -0,0 +1,284 @@
+# -*- coding: utf-8 -*-
+"""
+Chat Completions formatter implementation.
+Handles formatting for OpenAI Chat Completions API format.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List
+
+from ._formatter_base import FormatterBase
+
+
+class ChatCompletionsFormatter(FormatterBase):
+    """Formatter for Chat Completions API format."""
+
+    def format_messages(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Convert messages for Chat Completions API compatibility.
+
+        Chat Completions API expects tool call arguments as JSON strings in conversation history,
+        but they may be passed as objects from other parts of the system.
+        """
+        converted_messages = []
+
+        for message in messages:
+            # Create a copy to avoid modifying the original
+            converted_msg = dict(message)
+
+            # Normalize multimodal content (text/image/audio/video)
+            converted_msg = self._convert_multimodal_content(converted_msg)
+
+            # Convert tool_calls arguments from objects to JSON strings
+            if message.get("role") == "assistant" and "tool_calls" in message:
+                converted_tool_calls = []
+                for tool_call in message["tool_calls"]:
+                    converted_call = dict(tool_call)
+                    if "function" in converted_call:
+                        converted_function = dict(converted_call["function"])
+                        arguments = converted_function.get("arguments")
+
+                        # Convert arguments to JSON string if it's an object
+                        if isinstance(arguments, dict):
+                            converted_function["arguments"] = json.dumps(arguments)
+                        elif arguments is None:
+                            converted_function["arguments"] = "{}"
+                        elif not isinstance(arguments, str):
+                            # Handle other non-string types
+                            converted_function["arguments"] = self._serialize_tool_arguments(arguments)
+                        # If it's already a string, keep it as-is
+
+                        converted_call["function"] = converted_function
+                    converted_tool_calls.append(converted_call)
+                converted_msg["tool_calls"] = converted_tool_calls
+
+            converted_messages.append(converted_msg)
+
+        return converted_messages
+
+    def _convert_multimodal_content(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Convert multimodal content to Chat Completions API format.
+        """
+        content = message.get("content")
+
+        # If content is not a list, no conversion needed
+        if not isinstance(content, list):
+            return message
+
+        converted_content = []
+        for item in content:
+            if not isinstance(item, dict):
+                # If item is a string, treat as text
+                converted_content.append({"type": "text", "text": str(item)})
+                continue
+
+            item_type = item.get("type")
+
+            if item_type == "text":
+                # Text items pass through as-is
+                converted_content.append(item)
+
+            elif item_type == "image":
+                # Convert image item to image_url format
+                converted_item = self._convert_image_content(item)
+                if converted_item:
+                    converted_content.append(converted_item)
+
+            elif item_type == "audio":
+                # Convert audio item to input_audio format (base64)
+                converted_item = self._convert_audio_content(item)
+                if converted_item:
+                    converted_content.append(converted_item)
+
+            elif item_type == "video":
+                # Convert video item to video_url format (base64 data URL)
+                converted_item = self._convert_video_content(item)
+                if converted_item:
+                    converted_content.append(converted_item)
+
+            elif item_type == "video_url":
+                # Convert video URL to video_url format
+                converted_item = self._convert_video_url_content(item)
+                if converted_item:
+                    converted_content.append(converted_item)
+
+            elif item_type == "file_pending_upload":
+                continue
+            elif item_type in ["image_url", "input_audio", "video_url"]:
+                # Already in Chat Completions API format
+                converted_content.append(item)
+
+            else:
+                # Unknown type, pass through
+                converted_content.append(item)
+
+        message["content"] = converted_content
+        return message
+
+    def _convert_image_content(self, image_item: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Convert image content item to Chat Completions API format.
+
+        Supports:
+        - URL format: {"type": "image", "url": "https://..."}
+        - Base64 format: {"type": "image", "base64": "...", "mime_type": "image/jpeg"}
+
+        Returns Chat Completions format: {"type": "image_url", "image_url": {"url": "..."}}
+        """
+        # Handle URL format
+        if "url" in image_item:
+            return {
+                "type": "image_url",
+                "image_url": {"url": image_item["url"]},
+            }
+
+        # Handle base64 format
+        if "base64" in image_item:
+            mime_type = image_item.get("mime_type", "image/jpeg")
+            base64_data = image_item["base64"]
+
+            # Create data URL
+            data_url = f"data:{mime_type};base64,{base64_data}"
+            return {
+                "type": "image_url",
+                "image_url": {"url": data_url},
+            }
+
+        # No valid image data found
+        return None
+
+    def _convert_audio_content(self, audio_item: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Convert audio content item to Chat Completions API format.
+
+        Supports base64 format: {"type": "audio", "base64": "...", "mime_type": "audio/wav"}
+
+        Returns Chat Completions format: {"type": "input_audio", "input_audio": {"data": "...", "format": "wav"}}
+        """
+        if "base64" not in audio_item:
+            return None
+
+        base64_data = audio_item["base64"]
+        mime_type = audio_item.get("mime_type", "audio/wav")
+
+        # Extract format from MIME type (e.g., "audio/wav" → "wav")
+        audio_format = mime_type.split("/")[-1] if "/" in mime_type else "wav"
+
+        # Map common MIME types to OpenAI audio formats
+        format_mapping = {
+            "mpeg": "mp3",
+            "x-wav": "wav",
+            "wave": "wav",
+        }
+        audio_format = format_mapping.get(audio_format, audio_format)
+
+        return {
+            "type": "input_audio",
+            "input_audio": {
+                "data": base64_data,
+                "format": audio_format,
+            },
+        }
+
+    def _convert_video_content(self, video_item: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Convert video content item to Chat Completions API format.
+
+        Supports base64 format: {"type": "video", "base64": "...", "mime_type": "video/mp4"}
+
+        Returns format: {"type": "video_url", "video_url": {"url": "data:video/...;base64,..."}}
+        """
+        if "base64" not in video_item:
+            return None
+
+        base64_data = video_item["base64"]
+        mime_type = video_item.get("mime_type", "video/mp4")
+
+        # Create data URL
+        data_url = f"data:{mime_type};base64,{base64_data}"
+
+        return {
+            "type": "video_url",
+            "video_url": {"url": data_url},
+        }
+
+    def _convert_video_url_content(self, video_item: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Convert video URL content item to Chat Completions API format.
+
+        Supports URL format: {"type": "video_url", "url": "https://..."}
+
+        Returns format: {"type": "video_url", "video_url": {"url": "..."}}
+        """
+        if "url" not in video_item:
+            return None
+
+        return {
+            "type": "video_url",
+            "video_url": {"url": video_item["url"]},
+        }
+
+    def format_tools(self, tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Convert tools to Chat Completions format if needed.
+
+        Response API format: {"type": "function", "name": ..., "description": ..., "parameters": ...}
+        Chat Completions format: {"type": "function", "function": {"name": ..., "description": ..., "parameters": ...}}
+        """
+        if not tools:
+            return tools
+
+        converted_tools = []
+        for tool in tools:
+            if tool.get("type") == "function":
+                if "function" in tool:
+                    # Already in Chat Completions format
+                    converted_tools.append(tool)
+                elif "name" in tool and "description" in tool:
+                    # Response API format - convert to Chat Completions format
+                    converted_tools.append(
+                        {
+                            "type": "function",
+                            "function": {
+                                "name": tool["name"],
+                                "description": tool["description"],
+                                "parameters": tool.get("parameters", {}),
+                            },
+                        },
+                    )
+                else:
+                    # Unknown format - keep as-is
+                    converted_tools.append(tool)
+            else:
+                # Non-function tool - keep as-is
+                converted_tools.append(tool)
+
+        return converted_tools
+
+    def format_mcp_tools(self, mcp_functions: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Convert MCP tools to Chat Completions format."""
+        if not mcp_functions:
+            return []
+
+        converted_tools = []
+        for mcp_function in mcp_functions.values():
+            if hasattr(mcp_function, "to_chat_completions_format"):
+                tool = mcp_function.to_chat_completions_format()
+            elif hasattr(mcp_function, "to_openai_format"):
+                tool = mcp_function.to_openai_format()
+            else:
+                # Fallback format
+                tool = {
+                    "type": "function",
+                    "function": {
+                        "name": getattr(mcp_function, "name", "unknown"),
+                        "description": getattr(mcp_function, "description", ""),
+                        "parameters": getattr(mcp_function, "input_schema", {}),
+                    },
+                }
+            converted_tools.append(tool)
+
+        return converted_tools

massgen/formatter/_claude_formatter.py

@@ -0,0 +1,235 @@
+# -*- coding: utf-8 -*-
+"""
+Claude formatter implementation.
+Handles formatting for Anthropic Claude Messages API format.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Tuple
+
+from ._formatter_base import FormatterBase
+
+
+class ClaudeFormatter(FormatterBase):
+    """Formatter for Claude API format."""
+
+    def format_messages(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        formatted, _ = self.format_messages_and_system(messages)
+        return formatted
+
+    def format_messages_and_system(
+        self,
+        messages: List[Dict[str, Any]],
+    ) -> Tuple[List[Dict[str, Any]], str]:
+        """
+        Convert messages to Claude's expected format.
+
+        Handle different tool message formats and extract system message:
+        - Chat Completions tool message: {"role": "tool", "tool_call_id": "...", "content": "..."}
+        - Response API tool message: {"type": "function_call_output", "call_id": "...", "output": "..."}
+        - System messages: Extract and return separately for top-level system parameter
+
+        Returns:
+            tuple: (converted_messages, system_message)
+        """
+        converted_messages = []
+        system_message = ""
+
+        for message in messages:
+            if message.get("role") == "system":
+                # Extract system message for top-level parameter
+                system_message = message.get("content", "")
+            elif message.get("role") == "tool":
+                # Chat Completions tool message -> Claude tool result
+                converted_messages.append(
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "tool_result",
+                                "tool_use_id": message.get("tool_call_id"),
+                                "content": message.get("content", ""),
+                            },
+                        ],
+                    },
+                )
+            elif message.get("type") == "function_call_output":
+                # Response API tool message -> Claude tool result
+                converted_messages.append(
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "tool_result",
+                                "tool_use_id": message.get("call_id"),
+                                "content": message.get("output", ""),
+                            },
+                        ],
+                    },
+                )
+            elif message.get("role") == "assistant" and "tool_calls" in message:
+                # Assistant message with tool calls - convert to Claude format
+                content = []
+
+                # Add text content if present
+                if message.get("content"):
+                    content.append({"type": "text", "text": message["content"]})
+
+                # Convert tool calls to Claude tool use format
+                for tool_call in message["tool_calls"]:
+                    tool_name = self.extract_tool_name(tool_call)
+                    tool_args = self.extract_tool_arguments(tool_call)
+                    tool_id = self.extract_tool_call_id(tool_call)
+
+                    content.append(
+                        {
+                            "type": "tool_use",
+                            "id": tool_id,
+                            "name": tool_name,
+                            "input": tool_args,
+                        },
+                    )
+
+                converted_messages.append({"role": "assistant", "content": content})
+            elif message.get("role") in ["user", "assistant"]:
+                # Keep user and assistant messages, skip system
+                converted_message = dict(message)
+                if isinstance(converted_message.get("content"), str):
+                    # Claude expects content to be text for simple messages
+                    pass
+                elif isinstance(converted_message.get("content"), list):
+                    converted_message = self._convert_multimodal_content(converted_message)
+                converted_messages.append(converted_message)
+
+        return converted_messages, system_message
+
+    def _convert_multimodal_content(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Normalize multimodal content blocks to Claude's nested source structure."""
+
+        content = message.get("content")
+        if not isinstance(content, list):
+            return message
+
+        # Formatter handles generic multimodal content; upload_files-sourced items already preprocessed in backend.
+        converted_items: List[Dict[str, Any]] = []
+
+        for item in content:
+            if not isinstance(item, dict):
+                converted_items.append(item)
+                continue
+
+            item_type = item.get("type")
+
+            if item_type in {"tool_result", "tool_use", "text", "file_pending_upload"}:
+                converted_items.append(item)
+                continue
+
+            if item_type not in {"image", "document"}:
+                converted_items.append(item)
+                continue
+
+            if isinstance(item.get("source"), dict):
+                converted_items.append(item)
+                continue
+
+            if "file_id" in item:
+                normalized = {key: value for key, value in item.items() if key != "file_id"}
+                normalized["source"] = {
+                    "type": "file",
+                    "file_id": item["file_id"],
+                }
+                converted_items.append(normalized)
+                continue
+
+            if "base64" in item:
+                media_type = item.get("mime_type") or item.get("media_type")
+                normalized = {key: value for key, value in item.items() if key not in {"base64", "mime_type", "media_type"}}
+                normalized["source"] = {
+                    "type": "base64",
+                    "media_type": media_type,
+                    "data": item["base64"],
+                }
+                converted_items.append(normalized)
+                continue
+
+            if "url" in item:
+                normalized = {key: value for key, value in item.items() if key != "url"}
+                normalized["source"] = {
+                    "type": "url",
+                    "url": item["url"],
+                }
+                converted_items.append(normalized)
+                continue
+
+            converted_items.append(item)
+
+        message["content"] = converted_items
+        return message
+
+    def format_tools(self, tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Convert tools to Claude's expected format.
+
+        Input formats supported:
+        - Response API format: {"type": "function", "name": ..., "description": ..., "parameters": ...}
+        - Chat Completions format: {"type": "function", "function": {"name": ..., "description": ..., "parameters": ...}}
+
+        Claude format: {"type": "custom", "name": ..., "description": ..., "input_schema": ...}
+        """
+        if not tools:
+            return tools
+
+        converted_tools = []
+        for tool in tools:
+            if tool.get("type") == "function":
+                if "function" in tool:
+                    # Chat Completions format -> Claude custom tool
+                    func = tool["function"]
+                    converted_tools.append(
+                        {
+                            "type": "custom",
+                            "name": func["name"],
+                            "description": func["description"],
+                            "input_schema": func.get("parameters", {}),
+                        },
+                    )
+                elif "name" in tool and "description" in tool:
+                    # Response API format -> Claude custom tool
+                    converted_tools.append(
+                        {
+                            "type": "custom",
+                            "name": tool["name"],
+                            "description": tool["description"],
+                            "input_schema": tool.get("parameters", {}),
+                        },
+                    )
+                else:
+                    # Unknown format - keep as-is
+                    converted_tools.append(tool)
+            else:
+                # Non-function tool (builtin tools) - keep as-is
+                converted_tools.append(tool)
+
+        return converted_tools
+
+    def format_mcp_tools(self, mcp_functions: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Convert MCP tools to Claude's custom tool format."""
+        if not mcp_functions:
+            return []
+
+        converted_tools = []
+        for mcp_function in mcp_functions.values():
+            if hasattr(mcp_function, "to_claude_format"):
+                tool = mcp_function.to_claude_format()
+            else:
+                # Fallback format for Claude
+                tool = {
+                    "type": "custom",
+                    "name": getattr(mcp_function, "name", "unknown"),
+                    "description": getattr(mcp_function, "description", ""),
+                    "input_schema": getattr(mcp_function, "input_schema", {}),
+                }
+            converted_tools.append(tool)
+
+        return converted_tools

massgen/formatter/_formatter_base.py

@@ -0,0 +1,156 @@
+# -*- coding: utf-8 -*-
+"""
+Base class for API parameters handlers.
+Provides common functionality for building API parameters across different backends.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List
+
+
+class FormatterBase(ABC):
+    """Abstract base class for API parameter handlers."""
+
+    def __init__(self) -> None:
+        """Initialize the API params handler.
+
+        Args:
+            backend_instance: The backend instance containing necessary formatters and config
+        """
+        return None
+
+    @abstractmethod
+    def format_messages(
+        self,
+        messages: List[Dict[str, Any]],
+    ) -> List[Dict[str, Any]]:
+        pass
+
+    @abstractmethod
+    def format_tools(
+        self,
+        tools: List[Dict[str, Any]],
+    ) -> List[Dict[str, Any]]:
+        pass
+
+    @abstractmethod
+    def format_mcp_tools(
+        self,
+        mcp_functions: Dict[str, Any],
+    ) -> List[Dict[str, Any]]:
+        pass
+
+    @staticmethod
+    def extract_tool_name(tool_call: Dict[str, Any]) -> str:
+        """
+        Extract tool name from a tool call (handles multiple formats).
+
+        Supports:
+        - Chat Completions format: {"function": {"name": "...", ...}}
+        - Response API format: {"name": "..."}
+        - Claude native format: {"name": "..."}
+
+        Args:
+            tool_call: Tool call data structure from any backend
+
+        Returns:
+            Tool name string
+        """
+        # Chat Completions format
+        if "function" in tool_call:
+            return tool_call.get("function", {}).get("name", "unknown")
+        # Response API / Claude native format
+        elif "name" in tool_call:
+            return tool_call.get("name", "unknown")
+        # Fallback
+        return "unknown"
+
+    @staticmethod
+    def extract_tool_arguments(tool_call: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Extract tool arguments from a tool call (handles multiple formats).
+
+        Supports:
+        - Chat Completions format: {"function": {"arguments": ...}}
+        - Response API format: {"arguments": ...}
+        - Claude native format: {"input": ...}
+
+        Args:
+            tool_call: Tool call data structure from any backend
+
+        Returns:
+            Tool arguments dictionary (parsed from JSON string if needed)
+        """
+        import json
+
+        # Chat Completions format
+        if "function" in tool_call:
+            args = tool_call.get("function", {}).get("arguments", {})
+        # Claude native format
+        elif "input" in tool_call:
+            args = tool_call.get("input", {})
+        # Response API format
+        elif "arguments" in tool_call:
+            args = tool_call.get("arguments", {})
+        else:
+            args = {}
+
+        # Parse JSON string if needed
+        if isinstance(args, str):
+            try:
+                return json.loads(args) if args.strip() else {}
+            except (json.JSONDecodeError, ValueError):
+                return {}
+        return args if isinstance(args, dict) else {}
+
+    @staticmethod
+    def extract_tool_call_id(tool_call: Dict[str, Any]) -> str:
+        """
+        Extract tool call ID from a tool call (handles multiple formats).
+
+        Supports:
+        - Chat Completions format: {"id": "..."}
+        - Response API format: {"call_id": "..."}
+        - Claude native format: {"id": "..."}
+
+        Args:
+            tool_call: Tool call data structure from any backend
+
+        Returns:
+            Tool call ID string
+        """
+        # Try multiple possible ID fields
+        return tool_call.get("id") or tool_call.get("call_id") or ""
+
+    @staticmethod
+    def _serialize_tool_arguments(arguments) -> str:
+        """Safely serialize tool call arguments to JSON string.
+
+        Args:
+            arguments: Tool arguments (can be string, dict, or other types)
+
+        Returns:
+            JSON string representation of arguments
+        """
+        import json
+
+        if isinstance(arguments, str):
+            # If already a string, validate it's valid JSON
+            try:
+                json.loads(arguments)  # Validate JSON
+                return arguments
+            except (json.JSONDecodeError, ValueError):
+                # If not valid JSON, treat as plain string and wrap in quotes
+                return json.dumps(arguments)
+        elif arguments is None:
+            return "{}"
+        else:
+            # Convert to JSON string
+            try:
+                return json.dumps(arguments)
+            except (TypeError, ValueError) as e:
+                # Logger not imported at module level, use print for warning
+                print(f"Warning: Failed to serialize tool arguments: {e}, arguments: {arguments}")
+                return "{}"