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

massgen/agent_config.py

@@ -1,15 +1,48 @@
+# -*- coding: utf-8 -*-
 """
 Agent configuration for MassGen framework following input_cases_reference.md
 Simplified configuration focused on the proven binary decision approach.
+
+TODO: This file is outdated - check claude_code config and
+deprecated patterns. Update to reflect current backend architecture.
 """
 
+import warnings
 from dataclasses import dataclass, field
-from typing import Dict, Optional, Any, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, Dict, Optional
 
 if TYPE_CHECKING:
     from .message_templates import MessageTemplates
 
 
+@dataclass
+class TimeoutConfig:
+    """Configuration for timeout settings in MassGen.
+
+    Args:
+        orchestrator_timeout_seconds: Maximum time for orchestrator coordination (default: 1800s = 30min)
+    """
+
+    orchestrator_timeout_seconds: int = 1800  # 30 minutes
+
+
+@dataclass
+class CoordinationConfig:
+    """Configuration for coordination behavior in MassGen.
+
+    Args:
+        enable_planning_mode: If True, agents plan without executing actions during coordination.
+                             Only the winning agent executes actions during final presentation.
+                             If False, agents execute actions during coordination (default behavior).
+        planning_mode_instruction: Custom instruction to add when planning mode is enabled.
+    """
+
+    enable_planning_mode: bool = False
+    planning_mode_instruction: str = (
+        "During coordination, describe what you would do without actually executing actions. Only provide concrete implementation details without calling external APIs or tools."
+    )
+
+
 @dataclass
 class AgentConfig:
     """Configuration for MassGen agents using the proven binary decision framework.
@@ -22,6 +55,9 @@ class AgentConfig:
         message_templates: Custom message templates (None=default)
         agent_id: Optional agent identifier for this configuration
         custom_system_instruction: Additional system instruction prepended to evaluation message
+        timeout_config: Timeout and resource limit configuration
+        coordination_config: Coordination behavior configuration (e.g., planning mode)
+        skip_coordination_rounds: Debug/test mode - skip voting rounds and go straight to final presentation (default: False)
     """
 
     # Core backend configuration (includes tool enablement)
@@ -32,7 +68,78 @@ class AgentConfig:
 
     # Agent customization
     agent_id: Optional[str] = None
-    custom_system_instruction: Optional[str] = None
+    _custom_system_instruction: Optional[str] = field(default=None, init=False)
+
+    # Timeout and resource limits
+    timeout_config: TimeoutConfig = field(default_factory=TimeoutConfig)
+
+    # Coordination behavior configuration
+    coordination_config: CoordinationConfig = field(default_factory=CoordinationConfig)
+
+    # Debug/test mode - skip coordination rounds and go straight to final presentation
+    skip_coordination_rounds: bool = False
+
+    @property
+    def custom_system_instruction(self) -> Optional[str]:
+        """
+        DEPRECATED: Use backend-specific system prompt parameters instead.
+
+        For Claude Code: use append_system_prompt or system_prompt in backend_params
+        For other backends: use their respective system prompt parameters
+        """
+        if self._custom_system_instruction is not None:
+            warnings.warn(
+                "custom_system_instruction is deprecated. Use backend-specific " "system prompt parameters instead (e.g., append_system_prompt for Claude Code)",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return self._custom_system_instruction
+
+    @custom_system_instruction.setter
+    def custom_system_instruction(self, value: Optional[str]) -> None:
+        if value is not None:
+            warnings.warn(
+                "custom_system_instruction is deprecated. Use backend-specific " "system prompt parameters instead (e.g., append_system_prompt for Claude Code)",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        self._custom_system_instruction = value
+
+    @classmethod
+    def create_chatcompletion_config(
+        cls,
+        model: str = "gpt-oss-120b",
+        enable_web_search: bool = False,
+        enable_code_interpreter: bool = False,
+        **kwargs,
+    ) -> "AgentConfig":
+        """Create ChatCompletion configuration following proven patterns.
+
+        Args:
+            model: Opensource Model Name
+            enable_web_search: Enable web search via Responses API
+            enable_code_interpreter: Enable code execution for computational tasks
+            **kwargs: Additional backend parameters
+
+        Examples:
+            # Basic configuration
+            config = AgentConfig.create_chatcompletion_config("gpt-oss-120b")
+
+            # Research task with web search
+            config = AgentConfig.create_chatcompletion_config("gpt-oss-120b", enable_web_search=True)
+
+            # Computational task with code execution
+            config = AgentConfig.create_chatcompletion_config("gpt-oss-120b", enable_code_interpreter=True)
+        """
+        backend_params = {"model": model, **kwargs}
+
+        # Add tool enablement to backend_params
+        if enable_web_search:
+            backend_params["enable_web_search"] = True
+        if enable_code_interpreter:
+            backend_params["enable_code_interpreter"] = True
+
+        return cls(backend_params=backend_params)
 
     @classmethod
     def create_openai_config(
@@ -97,9 +204,7 @@ class AgentConfig:
         return cls(backend_params=backend_params)
 
     @classmethod
-    def create_grok_config(
-        cls, model: str = "grok-2-1212", enable_web_search: bool = False, **kwargs
-    ) -> "AgentConfig":
+    def create_grok_config(cls, model: str = "grok-2-1212", enable_web_search: bool = False, **kwargs) -> "AgentConfig":
         """Create xAI Grok configuration.
 
         Args:
@@ -115,6 +220,43 @@ class AgentConfig:
 
         return cls(backend_params=backend_params)
 
+    @classmethod
+    def create_lmstudio_config(
+        cls,
+        model: str = "gpt-4o-mini",
+        enable_web_search: bool = False,
+        **kwargs,
+    ) -> "AgentConfig":
+        """Create LM Studio configuration (OpenAI-compatible local server).
+
+        Args:
+            model: Local model name exposed by LM Studio
+            enable_web_search: No builtin web search; kept for interface parity
+            **kwargs: Additional backend parameters (e.g., base_url, api_key)
+        """
+        backend_params = {"model": model, **kwargs}
+        if enable_web_search:
+            backend_params["enable_web_search"] = True
+        return cls(backend_params=backend_params)
+
+    @classmethod
+    def create_vllm_config(cls, model: str | None = None, **kwargs) -> "AgentConfig":
+        """Create vLLM configuration (OpenAI-compatible local server)."""
+        backend_params = {"model": model, **kwargs}
+        if model is None:
+            raise ValueError("Model is required for vLLM configuration")
+
+        return cls(backend_params=backend_params)
+
+    @classmethod
+    def create_sglang_config(cls, model: str | None = None, **kwargs) -> "AgentConfig":
+        """Create SGLang configuration (OpenAI-compatible local server)."""
+        backend_params = {"model": model, **kwargs}
+        if model is None:
+            raise ValueError("Model is required for SGLang configuration")
+
+        return cls(backend_params=backend_params)
+
     @classmethod
     def create_gemini_config(
         cls,
@@ -141,6 +283,138 @@ class AgentConfig:
 
         return cls(backend_params=backend_params)
 
+    @classmethod
+    def create_zai_config(
+        cls,
+        model: str = "glm-4.5",
+        base_url: str = "https://api.z.ai/api/paas/v4/",
+        **kwargs,
+    ) -> "AgentConfig":
+        """Create ZAI configuration (OpenAI Chat Completions compatible).
+
+        Args:
+            model: ZAI model name (e.g., "glm-4.5")
+            base_url: ZAI OpenAI-compatible API base URL
+            **kwargs: Additional backend parameters (e.g., temperature, top_p)
+        """
+        backend_params = {"model": model, "base_url": base_url, **kwargs}
+
+        return cls(backend_params=backend_params)
+
+    @classmethod
+    def create_azure_openai_config(
+        cls,
+        deployment_name: str = "gpt-4",
+        endpoint: Optional[str] = None,
+        api_key: Optional[str] = None,
+        api_version: str = "2024-02-15-preview",
+        **kwargs,
+    ) -> "AgentConfig":
+        """Create Azure OpenAI configuration.
+
+        Args:
+            deployment_name: Azure OpenAI deployment name (e.g., "gpt-4", "gpt-35-turbo")
+            endpoint: Azure OpenAI endpoint URL (optional, uses AZURE_OPENAI_ENDPOINT env var)
+            api_key: Azure OpenAI API key (optional, uses AZURE_OPENAI_API_KEY env var)
+            api_version: Azure OpenAI API version (default: 2024-02-15-preview)
+            **kwargs: Additional backend parameters (e.g., temperature, max_tokens)
+
+        Examples:
+            Basic configuration using environment variables::
+
+                config = AgentConfig.create_azure_openai_config("gpt-4")
+
+            Custom endpoint and API key::
+
+                config = AgentConfig.create_azure_openai_config(
+                    deployment_name="gpt-4-turbo",
+                    endpoint="https://your-resource.openai.azure.com/",
+                    api_key="your-api-key"
+                )
+        """
+        backend_params = {
+            "type": "azure_openai",
+            "model": deployment_name,  # For Azure OpenAI, model is the deployment name
+            "api_version": api_version,
+            **kwargs,
+        }
+
+        # Add Azure-specific parameters if provided
+        if endpoint:
+            backend_params["base_url"] = endpoint
+        if api_key:
+            backend_params["api_key"] = api_key
+
+        return cls(backend_params=backend_params)
+
+    @classmethod
+    def create_claude_code_config(
+        cls,
+        model: str = "claude-sonnet-4-20250514",
+        system_prompt: Optional[str] = None,
+        allowed_tools: Optional[list] = None,  # Legacy support
+        disallowed_tools: Optional[list] = None,  # Preferred approach
+        max_thinking_tokens: int = 8000,
+        cwd: Optional[str] = None,
+        **kwargs,
+    ) -> "AgentConfig":
+        """Create Claude Code Stream configuration using claude-code-sdk.
+
+        This backend provides native integration with ALL Claude Code built-in tools
+        by default, with security enforced through disallowed_tools. This gives maximum
+        power while maintaining safety.
+
+        Args:
+            model: Claude model name (default: claude-sonnet-4-20250514)
+            system_prompt: Custom system prompt for the agent
+            allowed_tools: [LEGACY] List of allowed tools (use disallowed_tools instead)
+            disallowed_tools: List of dangerous operations to block
+                            (default: ["Bash(rm*)", "Bash(sudo*)", "Bash(su*)", "Bash(chmod*)", "Bash(chown*)"])
+            max_thinking_tokens: Maximum tokens for internal thinking (default: 8000)
+            cwd: Current working directory for file operations
+            **kwargs: Additional backend parameters
+
+        Examples:
+            Maximum power configuration (recommended)::
+
+                config = AgentConfig.create_claude_code_config()
+
+            Custom security restrictions::
+
+                config = AgentConfig.create_claude_code_config(
+                    disallowed_tools=["Bash(rm*)", "Bash(sudo*)", "WebSearch"]
+                )
+
+            Development task with custom directory::
+
+                config = AgentConfig.create_claude_code_config(
+                    cwd="/path/to/project",
+                    system_prompt="You are an expert developer assistant."
+                )
+
+            Legacy allowed_tools approach (not recommended)::
+
+                config = AgentConfig.create_claude_code_config(
+                    allowed_tools=["Read", "Write", "Edit", "Bash"]
+                )
+        """
+        backend_params = {"model": model, **kwargs}
+
+        # Claude Code Stream specific parameters
+        if system_prompt:
+            backend_params["system_prompt"] = system_prompt
+        if allowed_tools:
+            # Legacy support - warn that disallowed_tools is preferred
+            backend_params["allowed_tools"] = allowed_tools
+        if disallowed_tools:
+            backend_params["disallowed_tools"] = disallowed_tools
+        if max_thinking_tokens != 8000:  # Only set if different from default
+            backend_params["max_thinking_tokens"] = max_thinking_tokens
+        if cwd:
+            backend_params["cwd"] = cwd
+
+        return cls(backend_params=backend_params)
+
     # =============================================================================
     # AGENT CUSTOMIZATION
     # =============================================================================
@@ -166,9 +440,7 @@ class AgentConfig:
     # =============================================================================
 
     @classmethod
-    def for_research_task(
-        cls, model: str = "gpt-4o", backend: str = "openai"
-    ) -> "AgentConfig":
+    def for_research_task(cls, model: str = "gpt-4o", backend: str = "openai") -> "AgentConfig":
         """Create configuration optimized for research tasks.
 
         Based on econometrics test success patterns:
@@ -183,15 +455,14 @@ class AgentConfig:
             return cls.create_claude_config(model, enable_web_search=True)
         elif backend == "gemini":
             return cls.create_gemini_config(model, enable_web_search=True)
+        elif backend == "claude_code":
+            # Maximum power research config - all tools available
+            return cls.create_claude_code_config(model)
         else:
-            raise ValueError(
-                f"Research configuration not available for backend: {backend}"
-            )
+            raise ValueError(f"Research configuration not available for backend: {backend}")
 
     @classmethod
-    def for_computational_task(
-        cls, model: str = "gpt-4o", backend: str = "openai"
-    ) -> "AgentConfig":
+    def for_computational_task(cls, model: str = "gpt-4o", backend: str = "openai") -> "AgentConfig":
         """Create configuration optimized for computational tasks.
 
         Based on Tower of Hanoi test success patterns:
@@ -204,15 +475,14 @@ class AgentConfig:
             return cls.create_claude_config(model, enable_code_execution=True)
         elif backend == "gemini":
             return cls.create_gemini_config(model, enable_code_execution=True)
+        elif backend == "claude_code":
+            # Maximum power computational config - all tools available
+            return cls.create_claude_code_config(model)
         else:
-            raise ValueError(
-                f"Computational configuration not available for backend: {backend}"
-            )
+            raise ValueError(f"Computational configuration not available for backend: {backend}")
 
     @classmethod
-    def for_analytical_task(
-        cls, model: str = "gpt-4o-mini", backend: str = "openai"
-    ) -> "AgentConfig":
+    def for_analytical_task(cls, model: str = "gpt-4o-mini", backend: str = "openai") -> "AgentConfig":
         """Create configuration optimized for analytical tasks.
 
         Based on general reasoning test patterns:
@@ -227,10 +497,11 @@ class AgentConfig:
             return cls.create_grok_config(model)
         elif backend == "gemini":
             return cls.create_gemini_config(model)
+        elif backend == "claude_code":
+            # Maximum power analytical config - all tools available
+            return cls.create_claude_code_config(model)
         else:
-            raise ValueError(
-                f"Analytical configuration not available for backend: {backend}"
-            )
+            raise ValueError(f"Analytical configuration not available for backend: {backend}")
 
     @classmethod
     def for_expert_domain(
@@ -257,9 +528,7 @@ class AgentConfig:
         elif backend == "gemini":
             config = cls.create_gemini_config(model, enable_web_search=True)
         else:
-            raise ValueError(
-                f"Domain expert configuration not available for backend: {backend}"
-            )
+            raise ValueError(f"Domain expert configuration not available for backend: {backend}")
 
         config.custom_system_instruction = instruction
         return config
@@ -287,16 +556,12 @@ class AgentConfig:
         valid_agent_ids = list(agent_summaries.keys()) if agent_summaries else None
 
         # Build base conversation
-        conversation = templates.build_initial_conversation(
-            task=task, agent_summaries=agent_summaries, valid_agent_ids=valid_agent_ids
-        )
+        conversation = templates.build_initial_conversation(task=task, agent_summaries=agent_summaries, valid_agent_ids=valid_agent_ids)
 
         # Add custom system instruction if provided
         if self.custom_system_instruction:
             base_system = conversation["system_message"]
-            conversation["system_message"] = (
-                f"{self.custom_system_instruction}\n\n{base_system}"
-            )
+            conversation["system_message"] = f"{self.custom_system_instruction}\n\n{base_system}"
 
         # Add backend configuration
         conversation.update(
@@ -304,7 +569,7 @@ class AgentConfig:
                 "backend_params": self.get_backend_params(),
                 "session_id": session_id,
                 "agent_id": self.agent_id,
-            }
+            },
         )
 
         return conversation
@@ -354,7 +619,7 @@ class AgentConfig:
                     {
                         "role": additional_message_role,
                         "content": str(additional_message),
-                    }
+                    },
                 )
 
         # Add enforcement if requested (Case 3)
@@ -383,13 +648,9 @@ class AgentConfig:
         Returns:
             Conversation with enforcement message added
         """
-        return self.continue_conversation(
-            existing_messages=existing_messages, enforce_tools=True
-        )
+        return self.continue_conversation(existing_messages=existing_messages, enforce_tools=True)
 
-    def add_tool_result(
-        self, existing_messages: list, tool_call_id: str, result: str
-    ) -> Dict[str, Any]:
+    def add_tool_result(self, existing_messages: list, tool_call_id: str, result: str) -> Dict[str, Any]:
         """Add tool result to conversation.
 
         Args:
@@ -402,13 +663,9 @@ class AgentConfig:
         """
         tool_message = {"role": "tool", "tool_call_id": tool_call_id, "content": result}
 
-        return self.continue_conversation(
-            existing_messages=existing_messages, additional_message=tool_message
-        )
+        return self.continue_conversation(existing_messages=existing_messages, additional_message=tool_message)
 
-    def handle_case4_error_recovery(
-        self, existing_messages: list, clarification: str = None
-    ) -> Dict[str, Any]:
+    def handle_case4_error_recovery(self, existing_messages: list, clarification: Optional[str] = None) -> Dict[str, Any]:
         """Handle Case 4: Error recovery after tool failure.
 
         Args:
@@ -439,6 +696,15 @@ class AgentConfig:
             "backend_params": self.backend_params,
             "agent_id": self.agent_id,
             "custom_system_instruction": self.custom_system_instruction,
+            "timeout_config": {
+                "orchestrator_timeout_seconds": self.timeout_config.orchestrator_timeout_seconds,
+            },
+        }
+
+        # Handle coordination_config serialization
+        result["coordination_config"] = {
+            "enable_planning_mode": self.coordination_config.enable_planning_mode,
+            "planning_mode_instruction": self.coordination_config.planning_mode_instruction,
         }
 
         # Handle message_templates serialization
@@ -465,6 +731,18 @@ class AgentConfig:
         agent_id = data.get("agent_id")
         custom_system_instruction = data.get("custom_system_instruction")
 
+        # Handle timeout_config
+        timeout_config = TimeoutConfig()
+        timeout_data = data.get("timeout_config", {})
+        if timeout_data:
+            timeout_config = TimeoutConfig(**timeout_data)
+
+        # Handle coordination_config
+        coordination_config = CoordinationConfig()
+        coordination_data = data.get("coordination_config", {})
+        if coordination_data:
+            coordination_config = CoordinationConfig(**coordination_data)
+
         # Handle message_templates
         message_templates = None
         template_data = data.get("message_templates")
@@ -478,6 +756,8 @@ class AgentConfig:
             message_templates=message_templates,
             agent_id=agent_id,
             custom_system_instruction=custom_system_instruction,
+            timeout_config=timeout_config,
+            coordination_config=coordination_config,
         )
 
 
@@ -486,22 +766,16 @@ class AgentConfig:
 # =============================================================================
 
 
-def create_research_config(
-    model: str = "gpt-4o", backend: str = "openai"
-) -> AgentConfig:
+def create_research_config(model: str = "gpt-4o", backend: str = "openai") -> AgentConfig:
     """Create configuration for research tasks (web search enabled)."""
     return AgentConfig.for_research_task(model, backend)
 
 
-def create_computational_config(
-    model: str = "gpt-4o", backend: str = "openai"
-) -> AgentConfig:
+def create_computational_config(model: str = "gpt-4o", backend: str = "openai") -> AgentConfig:
     """Create configuration for computational tasks (code execution enabled)."""
     return AgentConfig.for_computational_task(model, backend)
 
 
-def create_analytical_config(
-    model: str = "gpt-4o-mini", backend: str = "openai"
-) -> AgentConfig:
+def create_analytical_config(model: str = "gpt-4o-mini", backend: str = "openai") -> AgentConfig:
     """Create configuration for analytical tasks (no special tools)."""
     return AgentConfig.for_analytical_task(model, backend)

massgen/api_params_handler/__init__.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""
+Message formatting utilities.
+Provides utility classes for message formatting and conversion.
+"""
+from ._chat_completions_api_params_handler import ChatCompletionsAPIParamsHandler
+from ._claude_api_params_handler import ClaudeAPIParamsHandler
+from ._response_api_params_handler import ResponseAPIParamsHandler
+
+__all__ = ["ChatCompletionsAPIParamsHandler", "ResponseAPIParamsHandler", "ClaudeAPIParamsHandler"]

massgen/api_params_handler/_api_params_handler_base.py

@@ -0,0 +1,99 @@
+# -*- 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, Set
+
+
+class APIParamsHandlerBase(ABC):
+    """Abstract base class for API parameter handlers."""
+
+    def __init__(self, backend_instance: Any):
+        """Initialize the API params handler.
+
+        Args:
+            backend_instance: The backend instance containing necessary formatters and config
+        """
+        self.backend = backend_instance
+        self.formatter = backend_instance.formatter
+
+    @abstractmethod
+    async def build_api_params(
+        self,
+        messages: List[Dict[str, Any]],
+        tools: List[Dict[str, Any]],
+        all_params: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Build API parameters for the specific backend.
+
+        Args:
+            messages: List of messages in framework format
+            tools: List of tools in framework format
+            all_params: All parameters including config and runtime params
+
+        Returns:
+            Dictionary of API parameters ready for the backend
+        """
+
+    @abstractmethod
+    def get_excluded_params(self) -> Set[str]:
+        """Get backend-specific parameters to exclude from API calls."""
+
+    @abstractmethod
+    def get_provider_tools(self, all_params: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Get provider-specific tools based on parameters."""
+
+    def get_base_excluded_params(self) -> Set[str]:
+        """Get common parameters to exclude across all backends."""
+        return {
+            "upload_files",
+            # Filesystem manager parameters (handled by base class)
+            "cwd",
+            "agent_temporary_workspace",
+            "context_paths",
+            "context_write_access_enabled",
+            "enable_image_generation",
+            "enable_mcp_command_line",
+            "command_line_allowed_commands",
+            "command_line_blocked_commands",
+            "command_line_execution_mode",
+            "command_line_docker_image",
+            "command_line_docker_memory_limit",
+            "command_line_docker_cpu_limit",
+            "command_line_docker_network_mode",
+            # Backend identification (handled by orchestrator)
+            "enable_audio_generation",  # Audio generation parameter
+            "type",
+            "agent_id",
+            "session_id",
+            # MCP configuration (handled by base class for MCP backends)
+            "mcp_servers",
+        }
+
+    def build_base_api_params(
+        self,
+        messages: List[Dict[str, Any]],
+        all_params: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Build base API parameters common to most backends."""
+        api_params = {"stream": True}
+
+        # Add filtered parameters
+        excluded = self.get_excluded_params()
+        for key, value in all_params.items():
+            if key not in excluded and value is not None:
+                api_params[key] = value
+
+        return api_params
+
+    def get_mcp_tools(self) -> List[Dict[str, Any]]:
+        """Get MCP tools from backend if available."""
+        if hasattr(self.backend, "_mcp_functions") and self.backend._mcp_functions:
+            if hasattr(self.backend, "get_mcp_tools_formatted"):
+                return self.backend.get_mcp_tools_formatted()
+        return []