mcp-mesh 0.6.2__py3-none-any.whl → 0.6.3__py3-none-any.whl

_mcp_mesh/__init__.py

@@ -31,7 +31,7 @@ from .engine.decorator_registry import (
     get_decorator_stats,
 )
 
-__version__ = "0.6.2"
+__version__ = "0.6.3"
 
 # Store reference to runtime processor if initialized
 _runtime_processor = None

_mcp_mesh/engine/llm_config.py

@@ -17,7 +17,7 @@ class LLMConfig:
     Supports both direct LiteLLM providers (string) and mesh delegation (dict).
     """
 
-    provider: Union[str, Dict[str, Any]] = "claude"
+    provider: Union[str, dict[str, Any]] = "claude"
     """LLM provider - string for direct LiteLLM (e.g., 'claude', 'openai') or dict for mesh delegation
        Mesh delegation format: {"capability": "llm", "tags": ["claude"], "version": ">=1.0.0"}"""
 
@@ -33,6 +33,9 @@ class LLMConfig:
     system_prompt: Optional[str] = None
     """Optional system prompt to prepend to all interactions"""
 
+    output_mode: Optional[str] = None
+    """Output mode override: 'strict', 'hint', or 'text'. If None, auto-detected by handler."""
+
     def __post_init__(self):
         """Validate configuration after initialization."""
         if self.max_iterations < 1:
@@ -43,3 +46,9 @@ class LLMConfig:
         # Only validate model for string providers (not needed for mesh delegation)
         if isinstance(self.provider, str) and not self.model:
             raise ValueError("model cannot be empty when using string provider")
+
+        # Validate output_mode if provided
+        if self.output_mode and self.output_mode not in ("strict", "hint", "text"):
+            raise ValueError(
+                f"output_mode must be 'strict', 'hint', or 'text', got '{self.output_mode}'"
+            )

_mcp_mesh/engine/mesh_llm_agent.py

@@ -58,7 +58,7 @@ class MeshLlmAgent:
         self,
         config: LLMConfig,
         filtered_tools: list[dict[str, Any]],
-        output_type: type[BaseModel],
+        output_type: type[BaseModel] | type[str],
         tool_proxies: Optional[dict[str, Any]] = None,
         template_path: Optional[str] = None,
         context_value: Optional[Any] = None,
@@ -71,7 +71,7 @@ class MeshLlmAgent:
         Args:
             config: LLM configuration (provider, model, api_key, etc.)
             filtered_tools: List of tool metadata from registry (for schema building)
-            output_type: Pydantic BaseModel for response validation
+            output_type: Pydantic BaseModel for response validation, or str for plain text
             tool_proxies: Optional map of function_name -> proxy for tool execution
             template_path: Optional path to Jinja2 template file for system prompt
             context_value: Optional context for template rendering (MeshContextModel, dict, or None)
@@ -87,6 +87,7 @@ class MeshLlmAgent:
         self.max_iterations = config.max_iterations
         self.output_type = output_type
         self.system_prompt = config.system_prompt  # Public attribute for tests
+        self.output_mode = config.output_mode  # Output mode override (strict/hint/text)
         self._iteration_count = 0
 
         # Detect if using mesh delegation (provider is dict)
@@ -126,12 +127,19 @@ IMPORTANT TOOL CALLING RULES:
 - Once you have gathered all necessary information, provide your final response
 """
 
-        schema = self.output_type.model_json_schema()
-        schema_str = json.dumps(schema, indent=2)
-        self._cached_json_instructions = (
-            f"\n\nIMPORTANT: You must return your final response as valid JSON matching this schema:\n"
-            f"{schema_str}\n\nReturn ONLY the JSON object, no additional text."
-        )
+        # Only generate JSON schema for Pydantic models, not for str return type
+        if self.output_type is not str and hasattr(
+            self.output_type, "model_json_schema"
+        ):
+            schema = self.output_type.model_json_schema()
+            schema_str = json.dumps(schema, indent=2)
+            self._cached_json_instructions = (
+                f"\n\nIMPORTANT: You must return your final response as valid JSON matching this schema:\n"
+                f"{schema_str}\n\nReturn ONLY the JSON object, no additional text."
+            )
+        else:
+            # str return type - no JSON schema needed
+            self._cached_json_instructions = ""
 
         logger.debug(
             f"🤖 MeshLlmAgent initialized: provider={config.provider}, model={config.model}, "
@@ -483,22 +491,36 @@ IMPORTANT TOOL CALLING RULES:
             try:
                 # Call LLM (either direct LiteLLM or mesh-delegated)
                 try:
-                    if self._is_mesh_delegated:
-                        # Mesh delegation: use provider handler to prepare vendor-specific request
-                        # Phase 2: Handler prepares params including response_format for OpenAI, etc.
-                        request_params = self._provider_handler.prepare_request(
-                            messages=messages,
-                            tools=self._tool_schemas if self._tool_schemas else None,
-                            output_type=self.output_type,
-                            **kwargs,
-                        )
+                    # Build kwargs with output_mode override if set
+                    call_kwargs = (
+                        {**kwargs, "output_mode": self.output_mode}
+                        if self.output_mode
+                        else kwargs
+                    )
+
+                    # Use provider handler to prepare vendor-specific request
+                    request_params = self._provider_handler.prepare_request(
+                        messages=messages,
+                        tools=self._tool_schemas if self._tool_schemas else None,
+                        output_type=self.output_type,
+                        **call_kwargs,
+                    )
 
-                        # Extract model_params to send to provider
-                        # Don't send messages/tools (already separate params) or model/api_key (provider has them)
+                    if self._is_mesh_delegated:
+                        # Mesh delegation: extract model_params to send to provider
+                        # Exclude messages/tools (separate params), model/api_key (provider has them),
+                        # and output_mode (only used locally by prepare_request)
                         model_params = {
                             k: v
                             for k, v in request_params.items()
-                            if k not in ["messages", "tools", "model", "api_key"]
+                            if k
+                            not in [
+                                "messages",
+                                "tools",
+                                "model",
+                                "api_key",
+                                "output_mode",
+                            ]
                         }
 
                         logger.debug(
@@ -509,19 +531,10 @@ IMPORTANT TOOL CALLING RULES:
                         response = await self._call_mesh_provider(
                             messages=messages,
                             tools=self._tool_schemas if self._tool_schemas else None,
-                            **model_params,  # Now includes response_format!
+                            **model_params,
                         )
                     else:
-                        # Direct LiteLLM call
-                        # Phase 2: Use provider handler to prepare vendor-specific request
-                        request_params = self._provider_handler.prepare_request(
-                            messages=messages,
-                            tools=self._tool_schemas if self._tool_schemas else None,
-                            output_type=self.output_type,
-                            **kwargs,
-                        )
-
-                        # Add model and API key (common to all vendors)
+                        # Direct LiteLLM call: add model and API key
                         request_params["model"] = self.model
                         request_params["api_key"] = self.api_key
 
@@ -612,15 +625,20 @@ IMPORTANT TOOL CALLING RULES:
         """
         Parse LLM response into output type.
 
-        Delegates to ResponseParser for actual parsing logic.
+        For str return type, returns content directly without parsing.
+        For Pydantic models, delegates to ResponseParser.
 
         Args:
             content: Response content from LLM
 
         Returns:
-            Parsed Pydantic model instance
+            Raw string (if output_type is str) or parsed Pydantic model instance
 
         Raises:
             ResponseParseError: If response doesn't match output_type schema or invalid JSON
         """
+        # For str return type, return content directly without parsing
+        if self.output_type is str:
+            return content
+
         return ResponseParser.parse(content, self.output_type)

_mcp_mesh/engine/mesh_llm_agent_injector.py

@@ -307,6 +307,22 @@ class MeshLlmAgentInjector(BaseInjector):
             llm_agent = self._create_llm_agent(function_id)
             wrapper._mesh_update_llm_agent(llm_agent)
             logger.info(f"🔄 Updated wrapper with MeshLlmAgent for '{function_id}'")
+
+            # Set factory for per-call context agent creation (template support)
+            # This allows the decorator's wrapper to create new agents with context per-call
+            config_dict = llm_metadata.config
+            if config_dict.get("is_template", False):
+                # Capture function_id by value using default argument to avoid closure issues
+                def create_context_agent(
+                    context_value: Any, _func_id: str = function_id
+                ) -> MeshLlmAgent:
+                    """Factory to create MeshLlmAgent with context for template rendering."""
+                    return self._create_llm_agent(_func_id, context_value=context_value)
+
+                wrapper._mesh_create_context_agent = create_context_agent
+                logger.info(
+                    f"🎯 Set context agent factory for template-based function '{function_id}'"
+                )
         elif wrapper:
             logger.warning(
                 f"⚠️ Wrapper for '{function_id}' found but has no _mesh_update_llm_agent method"
@@ -512,6 +528,9 @@ class MeshLlmAgentInjector(BaseInjector):
             api_key=config_dict.get("api_key", ""),  # Will use ENV if empty
             max_iterations=config_dict.get("max_iterations", 10),
             system_prompt=config_dict.get("system_prompt"),
+            output_mode=config_dict.get(
+                "output_mode"
+            ),  # Pass through output_mode from decorator
         )
 
         # Phase 4: Template support - extract template metadata

_mcp_mesh/engine/provider_handlers/claude_handler.py

@@ -3,15 +3,33 @@ Claude/Anthropic provider handler.
 
 Optimized for Claude API (Claude 3.x, Sonnet, Opus, Haiku)
 using Anthropic's best practices for tool calling and JSON responses.
+
+Supports three output modes for performance/reliability tradeoffs:
+- strict: Use response_format for guaranteed schema compliance (slowest, 100% reliable)
+- hint: Use prompt-based JSON instructions (medium speed, ~95% reliable)
+- text: Plain text output for str return types (fastest)
+
+Features:
+- Automatic prompt caching for system messages (up to 90% cost reduction)
+- Anti-XML tool calling instructions
+- Output mode optimization based on return type
 """
 
 import json
-from typing import Any, Dict, List, Optional
+import logging
+from typing import Any, Optional, get_args, get_origin
 
 from pydantic import BaseModel
 
 from .base_provider_handler import BaseProviderHandler
 
+logger = logging.getLogger(__name__)
+
+# Output mode constants
+OUTPUT_MODE_STRICT = "strict"
+OUTPUT_MODE_HINT = "hint"
+OUTPUT_MODE_TEXT = "text"
+
 
 class ClaudeHandler(BaseProviderHandler):
     """
@@ -19,48 +37,260 @@ class ClaudeHandler(BaseProviderHandler):
 
     Claude Characteristics:
     - Excellent at following detailed instructions
-    - Prefers verbose system prompts with explicit guidelines
-    - Handles JSON output well with schema instructions
+    - Native structured output via response_format (requires strict schema)
     - Native tool calling (via Anthropic messages API)
     - Performs best with anti-XML tool calling instructions
+    - Automatic prompt caching for cost optimization
+
+    Output Modes:
+    - strict: response_format with JSON schema (slowest, guaranteed valid JSON)
+    - hint: JSON schema in prompt (medium speed, usually valid JSON)
+    - text: Plain text output for str return types (fastest)
 
     Best Practices (from Anthropic docs):
-    - Provide clear, detailed system prompts
-    - Include explicit JSON schema in prompt for structured output
+    - Use response_format for guaranteed JSON schema compliance
+    - Schema must have additionalProperties: false on all objects
     - Add anti-XML instructions to prevent <invoke> style tool calls
     - Use one tool call at a time for better reliability
+    - Use cache_control for system prompts to reduce costs
     """
 
     def __init__(self):
         """Initialize Claude handler."""
         super().__init__(vendor="anthropic")
 
+    def _is_simple_schema(self, model_class: type[BaseModel]) -> bool:
+        """
+        Check if a Pydantic model has a simple schema.
+
+        Simple schema criteria:
+        - Less than 5 fields
+        - All fields are basic types (str, int, float, bool, list, Optional)
+        - No nested Pydantic models
+
+        Args:
+            model_class: Pydantic model class
+
+        Returns:
+            True if schema is simple, False otherwise
+        """
+        try:
+            schema = model_class.model_json_schema()
+            properties = schema.get("properties", {})
+
+            # Check field count
+            if len(properties) >= 5:
+                return False
+
+            # Check for nested objects or complex types
+            for field_name, field_schema in properties.items():
+                field_type = field_schema.get("type")
+
+                # Check for nested objects (indicates nested Pydantic model)
+                if field_type == "object" and "properties" in field_schema:
+                    return False
+
+                # Check for $ref (nested model reference)
+                if "$ref" in field_schema:
+                    return False
+
+                # Check array items for complex types
+                if field_type == "array":
+                    items = field_schema.get("items", {})
+                    if items.get("type") == "object" or "$ref" in items:
+                        return False
+
+            return True
+        except Exception:
+            return False
+
+    def determine_output_mode(
+        self, output_type: type, override_mode: Optional[str] = None
+    ) -> str:
+        """
+        Determine the output mode based on return type.
+
+        Logic:
+        - If override_mode specified, use it
+        - If return type is str, use "text" mode
+        - If return type is simple schema (<5 fields, basic types), use "hint" mode
+        - Otherwise, use "strict" mode
+
+        Args:
+            output_type: Return type (str or BaseModel subclass)
+            override_mode: Optional override ("strict", "hint", or "text")
+
+        Returns:
+            Output mode string
+        """
+        # Allow explicit override
+        if override_mode:
+            return override_mode
+
+        # String return type -> text mode
+        if output_type is str:
+            return OUTPUT_MODE_TEXT
+
+        # Check if it's a Pydantic model
+        if isinstance(output_type, type) and issubclass(output_type, BaseModel):
+            if self._is_simple_schema(output_type):
+                return OUTPUT_MODE_HINT
+            else:
+                return OUTPUT_MODE_STRICT
+
+        # Default to strict for unknown types
+        return OUTPUT_MODE_STRICT
+
+    def _make_schema_strict(self, schema: dict[str, Any]) -> dict[str, Any]:
+        """
+        Make a JSON schema strict for Claude's structured output.
+
+        Claude requires additionalProperties: false on all object types.
+        This recursively processes the schema to add this constraint.
+
+        Args:
+            schema: JSON schema dict
+
+        Returns:
+            Schema with additionalProperties: false on all objects
+        """
+        if not isinstance(schema, dict):
+            return schema
+
+        result = schema.copy()
+
+        # If this is an object type, add additionalProperties: false
+        if result.get("type") == "object":
+            result["additionalProperties"] = False
+
+        # Recursively process nested schemas
+        if "properties" in result:
+            result["properties"] = {
+                k: self._make_schema_strict(v) for k, v in result["properties"].items()
+            }
+
+        # Process $defs (Pydantic uses this for nested models)
+        if "$defs" in result:
+            result["$defs"] = {
+                k: self._make_schema_strict(v) for k, v in result["$defs"].items()
+            }
+
+        # Process items for arrays
+        if "items" in result:
+            result["items"] = self._make_schema_strict(result["items"])
+
+        # Process anyOf, oneOf, allOf
+        for key in ["anyOf", "oneOf", "allOf"]:
+            if key in result:
+                result[key] = [self._make_schema_strict(s) for s in result[key]]
+
+        return result
+
+    def _apply_prompt_caching(
+        self, messages: list[dict[str, Any]]
+    ) -> list[dict[str, Any]]:
+        """
+        Apply prompt caching to system messages for Claude.
+
+        Claude's prompt caching feature caches the system prompt prefix,
+        reducing costs by up to 90% and improving latency for repeated calls.
+
+        The cache_control with type "ephemeral" tells Claude to cache
+        this content for the duration of the session (typically 5 minutes).
+
+        Args:
+            messages: List of message dicts
+
+        Returns:
+            Messages with cache_control applied to system messages
+
+        Reference:
+            https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+        """
+        cached_messages = []
+
+        for msg in messages:
+            if msg.get("role") == "system":
+                content = msg.get("content", "")
+
+                # Convert string content to cached content block format
+                if isinstance(content, str):
+                    cached_msg = {
+                        "role": "system",
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": content,
+                                "cache_control": {"type": "ephemeral"},
+                            }
+                        ],
+                    }
+                    cached_messages.append(cached_msg)
+                    logger.debug(
+                        f"🗄️ Applied prompt caching to system message ({len(content)} chars)"
+                    )
+                elif isinstance(content, list):
+                    # Already in content block format - add cache_control to last block
+                    cached_content = []
+                    for i, block in enumerate(content):
+                        if isinstance(block, dict):
+                            block_copy = block.copy()
+                            # Add cache_control to the last text block
+                            if i == len(content) - 1 and block.get("type") == "text":
+                                block_copy["cache_control"] = {"type": "ephemeral"}
+                            cached_content.append(block_copy)
+                        else:
+                            cached_content.append(block)
+                    cached_messages.append(
+                        {"role": "system", "content": cached_content}
+                    )
+                    logger.debug("🗄️ Applied prompt caching to system content blocks")
+                else:
+                    # Unknown format - pass through unchanged
+                    cached_messages.append(msg)
+            else:
+                # Non-system messages pass through unchanged
+                cached_messages.append(msg)
+
+        return cached_messages
+
     def prepare_request(
         self,
-        messages: List[Dict[str, Any]],
-        tools: Optional[List[Dict[str, Any]]],
-        output_type: type[BaseModel],
-        **kwargs: Any
-    ) -> Dict[str, Any]:
+        messages: list[dict[str, Any]],
+        tools: Optional[list[dict[str, Any]]],
+        output_type: type,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
         """
-        Prepare request parameters for Claude API.
+        Prepare request parameters for Claude API with output mode support.
 
-        Claude uses standard LiteLLM interface with:
-        - Standard messages format
-        - OpenAI-compatible tools format (LiteLLM converts to Anthropic format)
-        - No special response_format needed (uses prompt-based JSON instructions)
+        Output Mode Strategy:
+        - strict: Use response_format for guaranteed JSON schema compliance (slowest)
+        - hint: No response_format, rely on prompt instructions (medium speed)
+        - text: No response_format, plain text output (fastest)
 
         Args:
             messages: List of message dicts
             tools: Optional list of tool schemas
-            output_type: Pydantic model for response
-            **kwargs: Additional model parameters
+            output_type: Return type (str or Pydantic model)
+            **kwargs: Additional model parameters (may include output_mode override)
 
         Returns:
             Dictionary of parameters for litellm.completion()
         """
+        # Extract output_mode from kwargs if provided
+        output_mode = kwargs.pop("output_mode", None)
+        determined_mode = self.determine_output_mode(output_type, output_mode)
+
+        # Remove response_format from kwargs - we control this based on output mode
+        # The decorator's response_format="json" is just a hint for parsing, not API param
+        kwargs.pop("response_format", None)
+
+        # Apply prompt caching to system messages for cost optimization
+        cached_messages = self._apply_prompt_caching(messages)
+
         request_params = {
-            "messages": messages,
+            "messages": cached_messages,
             **kwargs,  # Pass through temperature, max_tokens, etc.
         }
 
@@ -69,32 +299,49 @@ class ClaudeHandler(BaseProviderHandler):
         if tools:
             request_params["tools"] = tools
 
+        # Only add response_format in "strict" mode
+        if determined_mode == OUTPUT_MODE_STRICT:
+            # Claude requires additionalProperties: false on all object types
+            if isinstance(output_type, type) and issubclass(output_type, BaseModel):
+                schema = output_type.model_json_schema()
+                strict_schema = self._make_schema_strict(schema)
+                request_params["response_format"] = {
+                    "type": "json_schema",
+                    "json_schema": {
+                        "name": output_type.__name__,
+                        "schema": strict_schema,
+                        "strict": False,  # Allow optional fields with defaults
+                    },
+                }
+
         return request_params
 
     def format_system_prompt(
         self,
         base_prompt: str,
-        tool_schemas: Optional[List[Dict[str, Any]]],
-        output_type: type[BaseModel]
+        tool_schemas: Optional[list[dict[str, Any]]],
+        output_type: type,
+        output_mode: Optional[str] = None,
     ) -> str:
         """
-        Format system prompt for Claude with detailed instructions.
+        Format system prompt for Claude with output mode support.
 
-        Claude Strategy:
-        1. Use base prompt as-is (detailed is better for Claude)
-        2. Add anti-XML tool calling instructions if tools present
-        3. Add explicit JSON schema instructions for final response
-        4. Claude performs best with verbose, explicit guidelines
+        Output Mode Strategy:
+        - strict: Minimal JSON instructions (response_format handles schema)
+        - hint: Add detailed JSON schema instructions in prompt
+        - text: No JSON instructions (plain text output)
 
         Args:
             base_prompt: Base system prompt
             tool_schemas: Optional tool schemas
             output_type: Expected response type
+            output_mode: Optional override for output mode
 
         Returns:
             Formatted system prompt optimized for Claude
         """
         system_content = base_prompt
+        determined_mode = self.determine_output_mode(output_type, output_mode)
 
         # Add tool calling instructions if tools available
         # These prevent Claude from using XML-style <invoke> syntax
@@ -103,26 +350,58 @@ class ClaudeHandler(BaseProviderHandler):
 
 IMPORTANT TOOL CALLING RULES:
 - You have access to tools that you can call to gather information
-- Make ONE tool call at a time - each tool call must be separate
-- NEVER combine multiple tools in a single tool_use block
+- Make ONE tool call at a time
 - NEVER use XML-style syntax like <invoke name="tool_name"/>
-- Each tool must be called using proper JSON tool_use format
-- After receiving results from a tool, you can make additional tool calls if needed
-- Once you have gathered all necessary information, provide your final response
+- After receiving tool results, you can make additional calls if needed
+- Once you have all needed information, provide your final response
 """
 
-        # Add JSON schema instructions for final response
-        # Claude needs explicit schema in prompt (no native response_format)
-        schema = output_type.model_json_schema()
-        schema_str = json.dumps(schema, indent=2)
-        system_content += (
-            f"\n\nIMPORTANT: You must return your final response as valid JSON matching this schema:\n"
-            f"{schema_str}\n\nReturn ONLY the JSON object, no additional text."
-        )
+        # Add output format instructions based on mode
+        if determined_mode == OUTPUT_MODE_TEXT:
+            # Text mode: No JSON instructions
+            pass
+
+        elif determined_mode == OUTPUT_MODE_STRICT:
+            # Strict mode: Minimal instructions (response_format handles schema)
+            if isinstance(output_type, type) and issubclass(output_type, BaseModel):
+                system_content += f"\n\nYour final response will be structured as JSON matching the {output_type.__name__} format."
+
+        elif determined_mode == OUTPUT_MODE_HINT:
+            # Hint mode: Add detailed JSON schema instructions
+            if isinstance(output_type, type) and issubclass(output_type, BaseModel):
+                schema = output_type.model_json_schema()
+                properties = schema.get("properties", {})
+                required = schema.get("required", [])
+
+                # Build human-readable schema description
+                field_descriptions = []
+                for field_name, field_schema in properties.items():
+                    field_type = field_schema.get("type", "any")
+                    is_required = field_name in required
+                    req_marker = " (required)" if is_required else " (optional)"
+                    desc = field_schema.get("description", "")
+                    desc_text = f" - {desc}" if desc else ""
+                    field_descriptions.append(
+                        f"  - {field_name}: {field_type}{req_marker}{desc_text}"
+                    )
+
+                fields_text = "\n".join(field_descriptions)
+                system_content += f"""
+
+RESPONSE FORMAT:
+You MUST respond with valid JSON matching this schema:
+{{
+{fields_text}
+}}
+
+Example format:
+{json.dumps({k: f"<{v.get('type', 'value')}>" for k, v in properties.items()}, indent=2)}
+
+IMPORTANT: Respond ONLY with valid JSON. No markdown code fences, no preamble text."""
 
         return system_content
 
-    def get_vendor_capabilities(self) -> Dict[str, bool]:
+    def get_vendor_capabilities(self) -> dict[str, bool]:
         """
         Return Claude-specific capabilities.
 
@@ -131,8 +410,9 @@ IMPORTANT TOOL CALLING RULES:
         """
         return {
             "native_tool_calling": True,  # Claude has native function calling
-            "structured_output": False,  # No response_format, uses prompt-based JSON
+            "structured_output": True,  # Native response_format support via LiteLLM
             "streaming": True,  # Supports streaming
             "vision": True,  # Claude 3+ supports vision
-            "json_mode": False,  # No dedicated JSON mode, uses prompting
+            "json_mode": True,  # Native JSON mode via response_format
+            "prompt_caching": True,  # Automatic system prompt caching for cost savings
         }

_mcp_mesh/engine/provider_handlers/openai_handler.py

@@ -46,11 +46,11 @@ class OpenAIHandler(BaseProviderHandler):
 
     def prepare_request(
         self,
-        messages: List[Dict[str, Any]],
-        tools: Optional[List[Dict[str, Any]]],
+        messages: list[dict[str, Any]],
+        tools: Optional[list[dict[str, Any]]],
         output_type: type[BaseModel],
-        **kwargs: Any
-    ) -> Dict[str, Any]:
+        **kwargs: Any,
+    ) -> dict[str, Any]:
         """
         Prepare request parameters for OpenAI API with structured output.
 
@@ -83,6 +83,10 @@ class OpenAIHandler(BaseProviderHandler):
         # rather than relying on prompt instructions alone
         schema = output_type.model_json_schema()
 
+        # Transform schema for OpenAI strict mode
+        # OpenAI requires additionalProperties: false on all object schemas
+        schema = self._add_additional_properties_false(schema)
+
         # OpenAI structured output format
         # See: https://platform.openai.com/docs/guides/structured-outputs
         request_params["response_format"] = {
@@ -90,8 +94,8 @@ class OpenAIHandler(BaseProviderHandler):
             "json_schema": {
                 "name": output_type.__name__,
                 "schema": schema,
-                "strict": False,  # Allow optional fields with defaults
-            }
+                "strict": True,  # Enforce schema compliance
+            },
         }
 
         return request_params
@@ -99,8 +103,8 @@ class OpenAIHandler(BaseProviderHandler):
     def format_system_prompt(
         self,
         base_prompt: str,
-        tool_schemas: Optional[List[Dict[str, Any]]],
-        output_type: type[BaseModel]
+        tool_schemas: Optional[list[dict[str, Any]]],
+        output_type: type[BaseModel],
     ) -> str:
         """
         Format system prompt for OpenAI (concise approach).
@@ -147,7 +151,7 @@ IMPORTANT TOOL CALLING RULES:
 
         return system_content
 
-    def get_vendor_capabilities(self) -> Dict[str, bool]:
+    def get_vendor_capabilities(self) -> dict[str, bool]:
         """
         Return OpenAI-specific capabilities.
 
@@ -161,3 +165,55 @@ IMPORTANT TOOL CALLING RULES:
             "vision": True,  # GPT-4V and later support vision
             "json_mode": True,  # Has dedicated JSON mode via response_format
         }
+
+    def _add_additional_properties_false(
+        self, schema: dict[str, Any]
+    ) -> dict[str, Any]:
+        """
+        Recursively add additionalProperties: false to all object schemas.
+
+        OpenAI strict mode requires this for all object schemas.
+        See: https://platform.openai.com/docs/guides/structured-outputs
+
+        Args:
+            schema: JSON schema from Pydantic model
+
+        Returns:
+            Modified schema with additionalProperties: false on all objects
+        """
+        import copy
+
+        schema = copy.deepcopy(schema)
+        self._add_additional_properties_recursive(schema)
+        return schema
+
+    def _add_additional_properties_recursive(self, obj: Any) -> None:
+        """Recursively process schema for OpenAI strict mode compliance."""
+        if isinstance(obj, dict):
+            # If this is an object type, add additionalProperties: false
+            # and ensure required includes all properties
+            if obj.get("type") == "object":
+                obj["additionalProperties"] = False
+                # OpenAI strict mode: required must include ALL property keys
+                if "properties" in obj:
+                    obj["required"] = list(obj["properties"].keys())
+
+            # Process $defs (Pydantic uses this for nested models)
+            if "$defs" in obj:
+                for def_schema in obj["$defs"].values():
+                    self._add_additional_properties_recursive(def_schema)
+
+            # Process properties
+            if "properties" in obj:
+                for prop_schema in obj["properties"].values():
+                    self._add_additional_properties_recursive(prop_schema)
+
+            # Process items (for arrays)
+            if "items" in obj:
+                self._add_additional_properties_recursive(obj["items"])
+
+            # Process anyOf, oneOf, allOf
+            for key in ("anyOf", "oneOf", "allOf"):
+                if key in obj:
+                    for item in obj[key]:
+                        self._add_additional_properties_recursive(item)

_mcp_mesh/engine/response_parser.py

@@ -8,7 +8,7 @@ Separated from MeshLlmAgent for better testability and reusability.
 import json
 import logging
 import re
-from typing import Any, TypeVar
+from typing import Any, TypeVar, Union
 
 from pydantic import BaseModel, ValidationError
 
@@ -40,12 +40,12 @@ class ResponseParser:
     """
 
     @staticmethod
-    def parse(content: str, output_type: type[T]) -> T:
+    def parse(content: Any, output_type: type[T]) -> T:
         """
         Parse LLM response into Pydantic model.
 
         Args:
-            content: Raw response content from LLM
+            content: Raw response content from LLM (string or pre-parsed dict/list)
             output_type: Pydantic BaseModel class to parse into
 
         Returns:
@@ -57,16 +57,26 @@ class ResponseParser:
         logger.debug(f"📝 Parsing response into {output_type.__name__}...")
 
         try:
-            # Extract JSON from mixed content (narrative + XML + JSON)
-            extracted_content = ResponseParser._extract_json_from_mixed_content(content)
-
-            # Strip markdown code fences if present
-            cleaned_content = ResponseParser._strip_markdown_fences(extracted_content)
-
-            # Try to parse as JSON
-            response_data = ResponseParser._parse_json_with_fallback(
-                cleaned_content, output_type
-            )
+            # If content is already parsed (e.g., OpenAI strict mode), skip string processing
+            if isinstance(content, (dict, list)):
+                logger.debug("📦 Content already parsed, skipping string processing")
+                response_data = content
+            else:
+                # String processing for Claude, Gemini, and non-strict OpenAI
+                # Extract JSON from mixed content (narrative + XML + JSON)
+                extracted_content = ResponseParser._extract_json_from_mixed_content(
+                    content
+                )
+
+                # Strip markdown code fences if present
+                cleaned_content = ResponseParser._strip_markdown_fences(
+                    extracted_content
+                )
+
+                # Try to parse as JSON
+                response_data = ResponseParser._parse_json_with_fallback(
+                    cleaned_content, output_type
+                )
 
             # Validate against output type
             return ResponseParser._validate_and_create(response_data, output_type)
@@ -175,12 +185,16 @@ class ResponseParser:
                 raise ResponseParseError(f"Invalid JSON response: {e}")
 
     @staticmethod
-    def _validate_and_create(response_data: dict[str, Any], output_type: type[T]) -> T:
+    def _validate_and_create(response_data: Any, output_type: type[T]) -> T:
         """
         Validate data against Pydantic model and create instance.
 
+        Handles both dict and list responses:
+        - Dict: Direct unpacking into model
+        - List: Auto-wrap into first list field of model (for OpenAI strict mode)
+
         Args:
-            response_data: Parsed JSON data
+            response_data: Parsed JSON data (dict or list)
             output_type: Target Pydantic model
 
         Returns:
@@ -190,6 +204,31 @@ class ResponseParser:
             ResponseParseError: If validation fails
         """
         try:
+            # Handle list responses - wrap into first list field of model
+            if isinstance(response_data, list):
+                # Find the first list field in the model
+                model_fields = output_type.model_fields
+                list_field_name = None
+                for field_name, field_info in model_fields.items():
+                    # Check if field annotation is a list type
+                    field_type = field_info.annotation
+                    if (
+                        hasattr(field_type, "__origin__")
+                        and field_type.__origin__ is list
+                    ):
+                        list_field_name = field_name
+                        break
+
+                if list_field_name:
+                    logger.debug(
+                        f"📦 Wrapping list response into '{list_field_name}' field"
+                    )
+                    response_data = {list_field_name: response_data}
+                else:
+                    raise ResponseParseError(
+                        f"Response is a list but {output_type.__name__} has no list field to wrap into"
+                    )
+
             parsed = output_type(**response_data)
             logger.debug(f"✅ Response parsed successfully: {parsed}")
             return parsed

{mcp_mesh-0.6.2.dist-info → mcp_mesh-0.6.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-mesh
-Version: 0.6.2
+Version: 0.6.3
 Summary: Kubernetes-native platform for distributed MCP applications
 Project-URL: Homepage, https://github.com/dhyansraj/mcp-mesh
 Project-URL: Documentation, https://github.com/dhyansraj/mcp-mesh/tree/main/docs

{mcp_mesh-0.6.2.dist-info → mcp_mesh-0.6.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-_mcp_mesh/__init__.py,sha256=0-xOI5iH1RtI9h1XclT7zPovVsrj3LuH8vbEnmbvhRU,2719
+_mcp_mesh/__init__.py,sha256=4Pk7c0F7B-b6m0mHql0kvKWn6HEFWJmd-mRFEkin6VY,2719
 _mcp_mesh/engine/__init__.py,sha256=2ennzbo7yJcpkXO9BqN69TruLjJfmJY4Y5VEsG644K4,3630
 _mcp_mesh/engine/async_mcp_client.py,sha256=UcbQjxtgVfeRw6DHTZhAzN1gkcKlTg-lUPEePRPQWAU,6306
 _mcp_mesh/engine/base_injector.py,sha256=qzRLZqFP2VvEFagVovkpdldvDmm3VwPHm6tHwV58a2k,5648
@@ -6,12 +6,12 @@ _mcp_mesh/engine/decorator_registry.py,sha256=sb4Ng2y0hZovFzmrLdRCiwIEdwCm57WUD9
 _mcp_mesh/engine/dependency_injector.py,sha256=1bjeJ7pHUPEF_IoTF-7_Wm1pDLHphtfcFfSrUPWrWI4,31230
 _mcp_mesh/engine/full_mcp_proxy.py,sha256=PlRv7GSKqn5riOCqeCVulVdtq3z1Ug76mOkwMsOFHXw,25297
 _mcp_mesh/engine/http_wrapper.py,sha256=T9VQ2LZbGgCzyOVXVwdqas7-W3Wid0EwRboFUpdYWtM,20718
-_mcp_mesh/engine/llm_config.py,sha256=UOOfQbhYcljT9TsJJg_edwpk_5H4ZXQ6L1QARgiy8oc,1649
+_mcp_mesh/engine/llm_config.py,sha256=95bOsGWro5E1JGq7oZtEYhVdrzcIJqjht_r5vEdJVz4,2049
 _mcp_mesh/engine/llm_errors.py,sha256=h7BiI14u-jL8vtvBfFbFDDrN7gIw8PQjXIl5AP1SBuA,3276
 _mcp_mesh/engine/mcp_client_proxy.py,sha256=eJStwy_VQJexYYD8bOh_m4Ld3Bb8Ae_dt8N1CC41qBc,17625
-_mcp_mesh/engine/mesh_llm_agent.py,sha256=h83F7ZJWGv048tnXmNsD8HnmA0_t7D-aEWuCfke7psI,24038
-_mcp_mesh/engine/mesh_llm_agent_injector.py,sha256=nye3NYxJUP1ZS4IQZz-HSbCJKHIoaERMhjMW14pHuPg,26224
-_mcp_mesh/engine/response_parser.py,sha256=4_yEnxvHGvfgo7oqikgpjEjHuZRpBqBPJ_1QTH9YZOs,6943
+_mcp_mesh/engine/mesh_llm_agent.py,sha256=CcS2WX0ku1DSwUSx0H9YdV7oIiPNMs1jbxSPJvScRao,24679
+_mcp_mesh/engine/mesh_llm_agent_injector.py,sha256=isufzCBExli8tdLUZOaPuea3uQs3C_yeVXbOVSF0YIU,27270
+_mcp_mesh/engine/response_parser.py,sha256=NsOuGD7HJ0BFiiDUCp9v9cjLzVaU86HShVKzsrNnulk,8786
 _mcp_mesh/engine/self_dependency_proxy.py,sha256=OkKt0-B_ADnJlWtHiHItoZCBZ7Su0iz2unEPFfXvrs4,3302
 _mcp_mesh/engine/session_aware_client.py,sha256=mc9eh-aCvUvfllORiXTf_X8_jPqV-32QdWKlr8tHLkU,10600
 _mcp_mesh/engine/session_manager.py,sha256=MCr0_fXBaUjXM51WU5EhDkiGvBdfzYQFVNb9DCXXL0A,10418
@@ -21,9 +21,9 @@ _mcp_mesh/engine/tool_schema_builder.py,sha256=SQCxQIrSfdLu9-dLqiFurQLK7dhl0dc0x
 _mcp_mesh/engine/unified_mcp_proxy.py,sha256=SmhLWXdjmgvJWOLGQk-cXrvYjGSzx98HzL0Q5jpMNIY,36326
 _mcp_mesh/engine/provider_handlers/__init__.py,sha256=LLTCOgnuM3dlogbLmrpiMK3oB5L22eAmDC4BfxJ-L2I,593
 _mcp_mesh/engine/provider_handlers/base_provider_handler.py,sha256=J-SPFFFG1eFSUVvfsv7y4EuNM4REjSxaYWC5E_lC6Pc,4195
-_mcp_mesh/engine/provider_handlers/claude_handler.py,sha256=woTDtrDgv0UlXgbDxnOxE92i7VWTDWCG5NRwZitm6Cs,4875
+_mcp_mesh/engine/provider_handlers/claude_handler.py,sha256=CCmlsWiCfIcgrLbAZzeSnl0g2pq0uDffT8zOj4F-sPQ,15727
 _mcp_mesh/engine/provider_handlers/generic_handler.py,sha256=ewcwxWMmNEFEeBJ_2m16Oc3SnhCKpc0PVDtKy7TsLv0,5153
-_mcp_mesh/engine/provider_handlers/openai_handler.py,sha256=YKLnY1epdnoFDOm8LsuwGOIvkyJ4bSaEdArNxyHyaYQ,5511
+_mcp_mesh/engine/provider_handlers/openai_handler.py,sha256=rpHvnOfZkk73uICgU4pKe-BsWts4cQeykm_UXkAA3Rk,7754
 _mcp_mesh/engine/provider_handlers/provider_handler_registry.py,sha256=d2G3vndANzTiNl2ApfJuE2bmOlUI88y42144PjVst4s,5605
 _mcp_mesh/generated/.openapi-generator-ignore,sha256=5opOTZ_fahF3ctMAmN-i3PzJXM0d9Tnji_uAET2ZyEw,162
 _mcp_mesh/generated/.openapi-generator/FILES,sha256=Jpd-j6le0SjEvwdAJ51SWdZrlOUrUAFLtQ4sCHZVdKk,2571
@@ -140,10 +140,10 @@ _mcp_mesh/tracing/trace_context_helper.py,sha256=6tEkwjWFqMBe45zBlhacktmIpzJWTF9
 _mcp_mesh/tracing/utils.py,sha256=t9lJuTH7CeuzAiiAaD0WxsJMFJPdzZFR0w6-vyR9f2E,3849
 _mcp_mesh/utils/fastmcp_schema_extractor.py,sha256=M54ffesC-56zl_fNJHj9dZxElDQaWFf1MXdSLCuFStg,17253
 mesh/__init__.py,sha256=0zequaBtd_9NLOLsr9sNONuwWa_fT_-G4LnJ1CHTEY0,3808
-mesh/decorators.py,sha256=iCneI4xgihw1cc22mx0K-OnMIOLbh47EtwgTvPGTRzk,54126
+mesh/decorators.py,sha256=QTd1wJ8XV0Pfjq2ejyXjyeXBtyodbj1gbs5WKG9AFTs,55632
 mesh/helpers.py,sha256=c3FhSy9U4KBHEH6WH6MjCVrPMw9li5JAgBLUTIoamz4,9472
 mesh/types.py,sha256=9TqbJSxlybLQaPVjugcKwPiIrVnJEzqAOvPRhlX1zmo,15559
-mcp_mesh-0.6.2.dist-info/METADATA,sha256=HfPNBY41hVS3eq2RauZzQTIrTL28gamvmoGAUZLBzU8,4879
-mcp_mesh-0.6.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mcp_mesh-0.6.2.dist-info/licenses/LICENSE,sha256=_EBQHRQThv9FPOLc5eFOUdeeRO0mYwChC7cx60dM1tM,1078
-mcp_mesh-0.6.2.dist-info/RECORD,,
+mcp_mesh-0.6.3.dist-info/METADATA,sha256=6xLJu280gn5O2D1OUOZYAwOVGtQVf0g2tHDk3XnRXz8,4879
+mcp_mesh-0.6.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mcp_mesh-0.6.3.dist-info/licenses/LICENSE,sha256=_EBQHRQThv9FPOLc5eFOUdeeRO0mYwChC7cx60dM1tM,1078
+mcp_mesh-0.6.3.dist-info/RECORD,,

{mcp_mesh-0.6.2.dist-info → mcp_mesh-0.6.3.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

mesh/decorators.py

@@ -989,6 +989,39 @@ def set_shutdown_context(context: dict[str, Any]):
     set_global_shutdown_context(context)
 
 
+def _get_llm_agent_for_injection(
+    wrapper: Any, param_name: str, kwargs: dict, func_name: str
+) -> Any:
+    """
+    Get the appropriate LLM agent for injection based on template mode.
+
+    Handles both template-based (per-call context) and non-template (cached) modes.
+
+    Args:
+        wrapper: The wrapper function with _mesh_llm_* attributes
+        param_name: Name of the LLM parameter to inject
+        kwargs: Current call kwargs (may contain context value)
+        func_name: Function name for logging
+
+    Returns:
+        MeshLlmAgent instance (either per-call with context or cached)
+    """
+    config = getattr(wrapper, "_mesh_llm_config", {})
+    is_template = config.get("is_template", False)
+    context_param_name = config.get("context_param")
+    create_context_agent = getattr(wrapper, "_mesh_create_context_agent", None)
+
+    if is_template and context_param_name and create_context_agent:
+        # Template mode: create per-call agent with context
+        context_value = kwargs.get(context_param_name)
+        if context_value is not None:
+            logger.debug(f"🎯 Created per-call LLM agent with context for {func_name}")
+            return create_context_agent(context_value)
+
+    # Non-template mode or no context provided: use cached agent
+    return wrapper._mesh_llm_agent
+
+
 def llm(
     filter: dict[str, Any] | list[dict[str, Any] | str] | str | None = None,
     *,
@@ -1247,7 +1280,9 @@ def llm(
                 """Wrapper that injects both MeshLlmAgent and DI parameters."""
                 # Inject LLM parameter if not provided or if it's None
                 if param_name not in kwargs or kwargs.get(param_name) is None:
-                    kwargs[param_name] = combined_injection_wrapper._mesh_llm_agent
+                    kwargs[param_name] = _get_llm_agent_for_injection(
+                        combined_injection_wrapper, param_name, kwargs, func.__name__
+                    )
                 # Then call the original wrapper (which handles DI injection)
                 return original_call(*args, **kwargs)
 
@@ -1310,7 +1345,9 @@ def llm(
                 """Wrapper that injects MeshLlmAgent parameter."""
                 # Inject llm parameter if not provided or if it's None
                 if param_name not in kwargs or kwargs.get(param_name) is None:
-                    kwargs[param_name] = llm_injection_wrapper._mesh_llm_agent
+                    kwargs[param_name] = _get_llm_agent_for_injection(
+                        llm_injection_wrapper, param_name, kwargs, func.__name__
+                    )
                 return func(*args, **kwargs)
 
             # Create update method for heartbeat - updates the wrapper, not func