mcp-mesh 0.5.7__py3-none-any.whl → 0.6.0__py3-none-any.whl

_mcp_mesh/engine/response_parser.py

@@ -0,0 +1,240 @@
+"""
+Response parser for LLM outputs.
+
+Handles parsing and validation of LLM responses into Pydantic models.
+Separated from MeshLlmAgent for better testability and reusability.
+"""
+
+import json
+import logging
+import re
+from typing import Any, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+logger = logging.getLogger(__name__)
+
+# Module-level compiled regex for code fence stripping (compile once, use many times)
+_CODE_FENCE_PATTERN = re.compile(r"^```(?:json)?\s*|\s*```$", re.MULTILINE)
+
+# REMOVE_LATER: Regex to extract JSON from code fences in mixed content
+_JSON_BLOCK_PATTERN = re.compile(r"```json\s*\n(.+?)\n```", re.DOTALL)
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class ResponseParseError(Exception):
+    """Raised when response parsing or validation fails."""
+
+    pass
+
+
+class ResponseParser:
+    """
+    Utility class for parsing LLM responses into Pydantic models.
+
+    Handles:
+    - Markdown code fence stripping (```json ... ```)
+    - JSON parsing with fallback wrapping
+    - Pydantic validation
+    """
+
+    @staticmethod
+    def parse(content: str, output_type: type[T]) -> T:
+        """
+        Parse LLM response into Pydantic model.
+
+        Args:
+            content: Raw response content from LLM
+            output_type: Pydantic BaseModel class to parse into
+
+        Returns:
+            Parsed and validated Pydantic model instance
+
+        Raises:
+            ResponseParseError: If response doesn't match schema or invalid JSON
+        """
+        logger.debug(f"📝 Parsing response into {output_type.__name__}...")
+
+        # REMOVE_LATER: Debug raw content
+        logger.warning(f"🔍 REMOVE_LATER: Raw content length: {len(content)}")
+        logger.warning(
+            f"🔍 REMOVE_LATER: Raw content (first 500 chars): {content[:500]!r}"
+        )
+        logger.warning(
+            f"🔍 REMOVE_LATER: Raw content (last 200 chars): {content[-200:]!r}"
+        )
+
+        try:
+            # REMOVE_LATER: 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)
+
+            # REMOVE_LATER: Debug cleaned content
+            logger.warning(
+                f"🔍 REMOVE_LATER: Cleaned content length: {len(cleaned_content)}"
+            )
+            logger.warning(
+                f"🔍 REMOVE_LATER: Cleaned content: {cleaned_content[:500]!r}"
+            )
+
+            # 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)
+
+        except ResponseParseError:
+            raise
+        except Exception as e:
+            logger.error(f"❌ Unexpected error parsing response: {e}")
+            raise ResponseParseError(f"Unexpected parsing error: {e}")
+
+    @staticmethod
+    def _extract_json_from_mixed_content(content: str) -> str:
+        """
+        REMOVE_LATER: Extract JSON from mixed content (narrative + XML + JSON).
+
+        Tries multiple strategies to find JSON in mixed responses:
+        1. Find ```json ... ``` code fence blocks
+        2. Find any JSON object {...} in the content
+        3. Return original content if no extraction needed
+
+        Args:
+            content: Raw content that may contain narrative, XML, and JSON
+
+        Returns:
+            Extracted JSON string or original content
+        """
+        # REMOVE_LATER: Debug extraction attempt
+        logger.warning(
+            f"🔍 REMOVE_LATER: Attempting JSON extraction from content length: {len(content)}"
+        )
+
+        # Strategy 1: Try to find ```json ... ``` blocks
+        json_match = _JSON_BLOCK_PATTERN.search(content)
+        if json_match:
+            extracted = json_match.group(1).strip()
+            logger.warning(
+                f"🔍 REMOVE_LATER: Extracted JSON from code fence, length: {len(extracted)}"
+            )
+            logger.warning(f"🔍 REMOVE_LATER: Extracted content: {extracted[:200]}...")
+            return extracted
+
+        # Strategy 2: Try to find any JSON object {...} in content
+        # Look for balanced braces starting with { and ending with }
+        brace_start = content.find("{")
+        if brace_start != -1:
+            # Find matching closing brace
+            brace_count = 0
+            for i in range(brace_start, len(content)):
+                if content[i] == "{":
+                    brace_count += 1
+                elif content[i] == "}":
+                    brace_count -= 1
+                    if brace_count == 0:
+                        # Found matching brace
+                        extracted = content[brace_start : i + 1]
+                        logger.warning(
+                            f"🔍 REMOVE_LATER: Extracted JSON from braces, length: {len(extracted)}"
+                        )
+                        logger.warning(
+                            f"🔍 REMOVE_LATER: Extracted content: {extracted[:200]}..."
+                        )
+                        return extracted
+
+        # No JSON found, return original
+        logger.warning(
+            "🔍 REMOVE_LATER: No JSON extraction needed, returning original"
+        )
+        return content
+
+    @staticmethod
+    def _strip_markdown_fences(content: str) -> str:
+        """
+        Strip markdown code fences from content using regex.
+
+        Handles:
+        - ```json ... ``` (with optional whitespace/newlines)
+        - ``` ... ``` (with optional whitespace/newlines)
+        - Mixed whitespace and newline patterns
+
+        Uses compiled regex for optimal performance.
+
+        Args:
+            content: Raw content
+
+        Returns:
+            Content with fences removed
+        """
+        return _CODE_FENCE_PATTERN.sub("", content).strip()
+
+    @staticmethod
+    def _parse_json_with_fallback(content: str, output_type: type[T]) -> dict[str, Any]:
+        """
+        Parse content as JSON with fallback wrapping.
+
+        If direct JSON parsing fails, tries to wrap content in {"response": content}
+        to handle plain text responses.
+
+        Args:
+            content: Cleaned content
+            output_type: Target Pydantic model
+
+        Returns:
+            Parsed JSON dict
+
+        Raises:
+            ResponseParseError: If JSON parsing fails even with fallback
+        """
+        try:
+            return json.loads(content)
+        except json.JSONDecodeError as e:
+            # If not JSON, try wrapping it as a simple response
+            logger.warning(
+                f"⚠️ Response is not valid JSON, attempting to wrap: {content[:100]}..."
+            )
+            try:
+                # Try to match it to the output type as a simple string
+                response_data = {"response": content}
+                # Test if wrapping works by validating
+                output_type(**response_data)
+                logger.debug("✅ Response wrapped successfully")
+                return response_data
+            except ValidationError:
+                # If wrapping doesn't work, raise the original JSON error
+                raise ResponseParseError(f"Invalid JSON response: {e}")
+
+    @staticmethod
+    def _validate_and_create(response_data: dict[str, Any], output_type: type[T]) -> T:
+        """
+        Validate data against Pydantic model and create instance.
+
+        Args:
+            response_data: Parsed JSON data
+            output_type: Target Pydantic model
+
+        Returns:
+            Validated Pydantic model instance
+
+        Raises:
+            ResponseParseError: If validation fails
+        """
+        try:
+            parsed = output_type(**response_data)
+            logger.debug(f"✅ Response parsed successfully: {parsed}")
+            return parsed
+        except ValidationError as e:
+            # Enhanced error logging with schema diff
+            expected_schema = output_type.model_json_schema()
+            logger.error(
+                f"❌ Schema validation failed:\n"
+                f"Expected schema: {json.dumps(expected_schema, indent=2)}\n"
+                f"Received data: {json.dumps(response_data, indent=2)}\n"
+                f"Validation errors: {e}"
+            )
+            raise ResponseParseError(f"Response validation failed: {e}")

_mcp_mesh/engine/signature_analyzer.py

@@ -5,89 +5,21 @@ Function signature analysis for MCP Mesh dependency injection.
 import inspect
 from typing import Any, get_type_hints
 
-from mesh.types import McpAgent, McpMeshAgent
-
-
-def get_agent_parameter_types(func: Any) -> dict[int, str]:
-    """
-    Get parameter positions and their agent types (McpAgent vs McpMeshAgent).
-
-    Args:
-        func: Function to analyze
-
-    Returns:
-        Dict mapping parameter position to agent type name
-        e.g., {1: "McpAgent", 2: "McpMeshAgent"}
-    """
-    try:
-        # Get type hints for the function
-        type_hints = get_type_hints(func)
-
-        # Get parameter names in order
-        sig = inspect.signature(func)
-        param_names = list(sig.parameters.keys())
-
-        # Find positions and types of agent parameters
-        agent_types = {}
-        for i, param_name in enumerate(param_names):
-            if param_name in type_hints:
-                param_type = type_hints[param_name]
-
-                # Check for McpAgent or McpMeshAgent (handle Union types too)
-                agent_type = None
-
-                # Direct type check
-                if param_type == McpAgent or (
-                    hasattr(param_type, "__name__")
-                    and param_type.__name__ == "McpAgent"
-                ):
-                    agent_type = "McpAgent"
-                elif param_type == McpMeshAgent or (
-                    hasattr(param_type, "__name__")
-                    and param_type.__name__ == "McpMeshAgent"
-                ):
-                    agent_type = "McpMeshAgent"
-
-                # Union type check (e.g., McpAgent | None)
-                elif hasattr(param_type, "__args__"):
-                    for arg in param_type.__args__:
-                        if arg == McpAgent or (
-                            hasattr(arg, "__name__") and arg.__name__ == "McpAgent"
-                        ):
-                            agent_type = "McpAgent"
-                            break
-                        elif arg == McpMeshAgent or (
-                            hasattr(arg, "__name__") and arg.__name__ == "McpMeshAgent"
-                        ):
-                            agent_type = "McpMeshAgent"
-                            break
-
-                if agent_type:
-                    agent_types[i] = agent_type
-
-        return agent_types
-
-    except Exception as e:
-        # If we can't analyze the signature, return empty dict
-        import logging
-
-        logger = logging.getLogger(__name__)
-        logger.warning(f"Failed to analyze agent parameter types for {func}: {e}")
-        return {}
+from mesh.types import McpMeshAgent, MeshLlmAgent
 
 
 def get_mesh_agent_positions(func: Any) -> list[int]:
     """
-    Get positions of McpAgent and McpMeshAgent parameters in function signature.
+    Get positions of McpMeshAgent parameters in function signature.
 
     Args:
         func: Function to analyze
 
     Returns:
-        List of parameter positions (0-indexed) that are McpAgent or McpMeshAgent types
+        List of parameter positions (0-indexed) that are McpMeshAgent types
 
     Example:
-        def greet(name: str, date_svc: McpMeshAgent, file_svc: McpAgent):
+        def greet(name: str, date_svc: McpMeshAgent, file_svc: McpMeshAgent):
             pass
 
         get_mesh_agent_positions(greet) → [1, 2]
@@ -106,31 +38,29 @@ def get_mesh_agent_positions(func: Any) -> list[int]:
             if param_name in type_hints:
                 param_type = type_hints[param_name]
 
-                # Check if it's McpAgent or McpMeshAgent type (handle different import paths and Union types)
+                # Check if it's McpMeshAgent type (handle different import paths and Union types)
                 is_agent = False
 
-                # Direct McpAgent or McpMeshAgent type
+                # Direct McpMeshAgent type
                 if (
-                    param_type in (McpAgent, McpMeshAgent)
+                    param_type == McpMeshAgent
                     or (
                         hasattr(param_type, "__name__")
-                        and param_type.__name__ in ("McpAgent", "McpMeshAgent")
+                        and param_type.__name__ == "McpMeshAgent"
                     )
                     or (
                         hasattr(param_type, "__origin__")
-                        and param_type.__origin__
-                        in (type(McpAgent), type(McpMeshAgent))
+                        and param_type.__origin__ == type(McpMeshAgent)
                     )
                 ):
                     is_agent = True
 
-                # Union type (e.g., McpAgent | None, McpMeshAgent | None)
+                # Union type (e.g., McpMeshAgent | None)
                 elif hasattr(param_type, "__args__"):
-                    # Check if any arg in the union is McpAgent or McpMeshAgent
+                    # Check if any arg in the union is McpMeshAgent
                     for arg in param_type.__args__:
-                        if arg in (McpAgent, McpMeshAgent) or (
-                            hasattr(arg, "__name__")
-                            and arg.__name__ in ("McpAgent", "McpMeshAgent")
+                        if arg == McpMeshAgent or (
+                            hasattr(arg, "__name__") and arg.__name__ == "McpMeshAgent"
                         ):
                             is_agent = True
                             break
@@ -151,13 +81,13 @@ def get_mesh_agent_positions(func: Any) -> list[int]:
 
 def get_mesh_agent_parameter_names(func: Any) -> list[str]:
     """
-    Get names of McpMeshAgent/McpAgent parameters in function signature.
+    Get names of McpMeshAgent parameters in function signature.
 
     Args:
         func: Function to analyze
 
     Returns:
-        List of parameter names that are McpMeshAgent or McpAgent types
+        List of parameter names that are McpMeshAgent types
     """
     try:
         type_hints = get_type_hints(func)
@@ -168,31 +98,29 @@ def get_mesh_agent_parameter_names(func: Any) -> list[str]:
             if param_name in type_hints:
                 param_type = type_hints[param_name]
 
-                # Check if it's McpAgent or McpMeshAgent type (handle different import paths and Union types)
+                # Check if it's McpMeshAgent type (handle different import paths and Union types)
                 is_mesh_agent = False
 
-                # Direct McpAgent or McpMeshAgent type
+                # Direct McpMeshAgent type
                 if (
-                    param_type in (McpAgent, McpMeshAgent)
+                    param_type == McpMeshAgent
                     or (
                         hasattr(param_type, "__name__")
-                        and param_type.__name__ in ("McpAgent", "McpMeshAgent")
+                        and param_type.__name__ == "McpMeshAgent"
                     )
                     or (
                         hasattr(param_type, "__origin__")
-                        and param_type.__origin__
-                        in (type(McpAgent), type(McpMeshAgent))
+                        and param_type.__origin__ == type(McpMeshAgent)
                     )
                 ):
                     is_mesh_agent = True
 
-                # Union type (e.g., McpAgent | None, McpMeshAgent | None)
+                # Union type (e.g., McpMeshAgent | None)
                 elif hasattr(param_type, "__args__"):
-                    # Check if any arg in the union is McpAgent or McpMeshAgent
+                    # Check if any arg in the union is McpMeshAgent
                     for arg in param_type.__args__:
-                        if arg in (McpAgent, McpMeshAgent) or (
-                            hasattr(arg, "__name__")
-                            and arg.__name__ in ("McpAgent", "McpMeshAgent")
+                        if arg == McpMeshAgent or (
+                            hasattr(arg, "__name__") and arg.__name__ == "McpMeshAgent"
                         ):
                             is_mesh_agent = True
                             break
@@ -208,7 +136,7 @@ def get_mesh_agent_parameter_names(func: Any) -> list[str]:
 
 def validate_mesh_dependencies(func: Any, dependencies: list[dict]) -> tuple[bool, str]:
     """
-    Validate that the number of dependencies matches McpMeshAgent/McpAgent parameters.
+    Validate that the number of dependencies matches McpMeshAgent parameters.
 
     Args:
         func: Function to validate
@@ -221,9 +149,211 @@ def validate_mesh_dependencies(func: Any, dependencies: list[dict]) -> tuple[boo
 
     if len(dependencies) != len(mesh_positions):
         return False, (
-            f"Function {func.__name__} has {len(mesh_positions)} McpMeshAgent/McpAgent parameters "
+            f"Function {func.__name__} has {len(mesh_positions)} McpMeshAgent parameters "
             f"but {len(dependencies)} dependencies declared. "
-            f"Each McpMeshAgent/McpAgent parameter needs a corresponding dependency."
+            f"Each McpMeshAgent parameter needs a corresponding dependency."
         )
 
     return True, ""
+
+
+def get_llm_agent_positions(func: Any) -> list[int]:
+    """
+    Get positions of MeshLlmAgent parameters in function signature.
+
+    Args:
+        func: Function to analyze
+
+    Returns:
+        List of parameter positions (0-indexed) that are MeshLlmAgent types
+
+    Example:
+        def chat(msg: str, llm: MeshLlmAgent):
+            pass
+
+        get_llm_agent_positions(chat) → [1]
+    """
+    try:
+        # Get type hints for the function
+        type_hints = get_type_hints(func)
+
+        # Get parameter names in order
+        sig = inspect.signature(func)
+        param_names = list(sig.parameters.keys())
+
+        # Find positions of MeshLlmAgent parameters
+        llm_positions = []
+        for i, param_name in enumerate(param_names):
+            if param_name in type_hints:
+                param_type = type_hints[param_name]
+
+                # Check if it's MeshLlmAgent type (handle different import paths and Union types)
+                is_llm_agent = False
+
+                # Direct MeshLlmAgent type
+                if (
+                    param_type == MeshLlmAgent
+                    or (
+                        hasattr(param_type, "__name__")
+                        and param_type.__name__ == "MeshLlmAgent"
+                    )
+                    or (
+                        hasattr(param_type, "__origin__")
+                        and param_type.__origin__ == type(MeshLlmAgent)
+                    )
+                ):
+                    is_llm_agent = True
+
+                # Union type (e.g., MeshLlmAgent | None)
+                elif hasattr(param_type, "__args__"):
+                    # Check if any arg in the union is MeshLlmAgent
+                    for arg in param_type.__args__:
+                        if arg == MeshLlmAgent or (
+                            hasattr(arg, "__name__") and arg.__name__ == "MeshLlmAgent"
+                        ):
+                            is_llm_agent = True
+                            break
+
+                if is_llm_agent:
+                    llm_positions.append(i)
+
+        return llm_positions
+
+    except Exception as e:
+        # If we can't analyze the signature, return empty list
+        import logging
+
+        logger = logging.getLogger(__name__)
+        logger.warning(f"Failed to analyze signature for {func}: {e}")
+        return []
+
+
+def has_llm_agent_parameter(func: Any) -> bool:
+    """
+    Check if function has any MeshLlmAgent parameters.
+
+    Args:
+        func: Function to analyze
+
+    Returns:
+        True if function has at least one MeshLlmAgent parameter
+    """
+    return len(get_llm_agent_positions(func)) > 0
+
+
+def get_context_parameter_name(
+    func: Any, explicit_name: str | None = None
+) -> tuple[str, int] | None:
+    """
+    Get context parameter name and index for template rendering (Phase 2).
+
+    This function detects context parameters using a hybrid approach:
+    1. Explicit name (if provided) - validates existence
+    2. Convention-based detection - checks for prompt_context, llm_context, context
+    3. Type hint detection - finds MeshContextModel subclass parameters
+
+    Args:
+        func: Function to analyze
+        explicit_name: Optional explicit parameter name from @mesh.llm(context_param="...")
+
+    Returns:
+        Tuple of (param_name, param_index) or None if no context parameter found
+
+    Raises:
+        ValueError: If explicit_name provided but parameter not found
+
+    Example:
+        # Explicit name
+        def chat(msg: str, ctx: ChatContext, llm: MeshLlmAgent = None):
+            pass
+        get_context_parameter_name(chat, "ctx") → ("ctx", 1)
+
+        # Convention-based
+        def analyze(query: str, prompt_context: dict, llm: MeshLlmAgent = None):
+            pass
+        get_context_parameter_name(analyze) → ("prompt_context", 1)
+
+        # Type hint detection
+        def process(data: str, my_ctx: ChatContext, llm: MeshLlmAgent = None):
+            pass
+        get_context_parameter_name(process) → ("my_ctx", 1)
+    """
+    try:
+        sig = inspect.signature(func)
+        param_names = list(sig.parameters.keys())
+
+        # Get type hints (may fail for some functions)
+        type_hints = {}
+        try:
+            type_hints = get_type_hints(func)
+        except Exception:
+            pass  # Continue without type hints
+
+        # Strategy 1: Explicit name (highest priority)
+        if explicit_name is not None:
+            if explicit_name in param_names:
+                param_index = param_names.index(explicit_name)
+                return (explicit_name, param_index)
+            else:
+                raise ValueError(
+                    f"Context parameter '{explicit_name}' not found in function '{func.__name__}'. "
+                    f"Available parameters: {param_names}"
+                )
+
+        # Strategy 2: Type hint detection (find MeshContextModel parameters)
+        # This has priority over convention names
+        if type_hints:
+            from mesh.types import MeshContextModel
+
+            for i, param_name in enumerate(param_names):
+                if param_name in type_hints:
+                    param_type = type_hints[param_name]
+
+                    # Check if it's MeshContextModel or subclass
+                    is_context_model = False
+
+                    # Direct MeshContextModel type
+                    try:
+                        if inspect.isclass(param_type) and issubclass(
+                            param_type, MeshContextModel
+                        ):
+                            is_context_model = True
+                    except TypeError:
+                        pass  # Not a class, check other cases
+
+                    # Union type (e.g., Optional[MeshContextModel])
+                    if not is_context_model and hasattr(param_type, "__args__"):
+                        for arg in param_type.__args__:
+                            if arg is not type(None):  # Skip None in Optional
+                                try:
+                                    if inspect.isclass(arg) and issubclass(
+                                        arg, MeshContextModel
+                                    ):
+                                        is_context_model = True
+                                        break
+                                except TypeError:
+                                    pass
+
+                    if is_context_model:
+                        return (param_name, i)
+
+        # Strategy 3: Convention-based detection (check in priority order)
+        # This comes after type hint detection
+        convention_names = ["prompt_context", "llm_context", "context"]
+        for convention_name in convention_names:
+            if convention_name in param_names:
+                param_index = param_names.index(convention_name)
+                return (convention_name, param_index)
+
+        # No context parameter found
+        return None
+
+    except ValueError:
+        # Re-raise ValueError for explicit name validation errors
+        raise
+    except Exception as e:
+        import logging
+
+        logger = logging.getLogger(__name__)
+        logger.debug(f"Failed to detect context parameter for {func.__name__}: {e}")
+        return None