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

mesh/helpers.py

@@ -0,0 +1,259 @@
+"""
+Helper decorators for common mesh patterns.
+
+This module provides convenience decorators that build on top of the core
+mesh decorators to simplify common patterns like zero-code LLM providers.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def llm_provider(
+    model: str,
+    capability: str = "llm",
+    tags: Optional[list[str]] = None,
+    version: str = "1.0.0",
+    **litellm_kwargs: Any,
+):
+    """
+    Zero-code LLM provider decorator.
+
+    Creates a mesh-registered LLM provider that automatically:
+    - Registers as MCP tool (@app.tool) for direct MCP calls
+    - Registers in mesh network (@mesh.tool) for dependency injection
+    - Wraps LiteLLM with standard MeshLlmRequest interface
+    - Returns raw string response (caller handles parsing)
+
+    The decorated function becomes a placeholder - the decorator generates
+    a process_chat(request: MeshLlmRequest) -> str function that handles
+    all LLM provider logic.
+
+    Args:
+        model: LiteLLM model name (e.g., "anthropic/claude-sonnet-4-5")
+        capability: Capability name for mesh registration (default: "llm")
+        tags: Tags for mesh registration (e.g., ["claude", "fast", "+budget"])
+        version: Version string for mesh registration (default: "1.0.0")
+        **litellm_kwargs: Additional kwargs to pass to litellm.completion()
+
+    Usage:
+        from fastmcp import FastMCP
+        import mesh
+
+        app = FastMCP("LLM Provider")
+
+        @mesh.llm_provider(
+            model="anthropic/claude-sonnet-4-5",
+            capability="llm",
+            tags=["claude", "test"],
+            version="1.0.0",
+        )
+        def claude_provider():
+            '''Zero-code Claude provider.'''
+            pass  # Implementation is in the decorator
+
+        @mesh.agent(name="my-provider", auto_run=True)
+        class MyProviderAgent:
+            pass
+
+    The generated process_chat function signature:
+        def process_chat(request: MeshLlmRequest) -> str:
+            '''
+            Auto-generated LLM handler.
+
+            Args:
+                request: MeshLlmRequest with messages, tools, model_params
+
+            Returns:
+                Raw LLM response content as string
+            '''
+
+    Testing:
+        # Direct MCP call
+        curl -X POST http://localhost:9019/mcp \\
+          -H "Content-Type: application/json" \\
+          -d '{
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/call",
+            "params": {
+              "name": "process_chat",
+              "arguments": {
+                "request": {
+                  "messages": [
+                    {"role": "system", "content": "You are helpful."},
+                    {"role": "user", "content": "Say hello."}
+                  ]
+                }
+              }
+            }
+          }'
+
+    Raises:
+        RuntimeError: If FastMCP 'app' not found in module
+        ImportError: If litellm not installed
+    """
+
+    def decorator(func):
+        # Import here to avoid circular imports
+        import sys
+
+        from mesh import tool
+        from mesh.types import MeshLlmRequest
+
+        # Find FastMCP app in current module
+        current_module = sys.modules.get(func.__module__)
+        if not current_module or not hasattr(current_module, "app"):
+            raise RuntimeError(
+                f"@mesh.llm_provider requires FastMCP 'app' in module {func.__module__}. "
+                f"Example: app = FastMCP('LLM Provider')"
+            )
+
+        app = current_module.app
+
+        # Extract vendor from model name using LiteLLM
+        vendor = "unknown"
+        try:
+            import litellm
+
+            _, vendor, _, _ = litellm.get_llm_provider(model=model)
+            logger.info(
+                f"✅ Extracted vendor '{vendor}' from model '{model}' "
+                f"using LiteLLM detection"
+            )
+        except (ImportError, AttributeError, ValueError, KeyError) as e:
+            # Fallback: try to extract from model prefix
+            # ImportError: litellm not installed
+            # AttributeError: get_llm_provider doesn't exist
+            # ValueError: invalid model format
+            # KeyError: model not in provider mapping
+            if "/" in model:
+                vendor = model.split("/")[0]
+                logger.warning(
+                    f"⚠️  Could not extract vendor using LiteLLM ({e}), "
+                    f"falling back to prefix extraction: '{vendor}'"
+                )
+            else:
+                logger.warning(
+                    f"⚠️  Could not extract vendor from model '{model}', "
+                    f"using 'unknown'"
+                )
+
+        # Generate the LLM handler function
+        def process_chat(request: MeshLlmRequest) -> dict[str, Any]:
+            """
+            Auto-generated LLM handler.
+
+            Args:
+                request: MeshLlmRequest with messages, tools, model_params
+
+            Returns:
+                Full message dict with content, role, and tool_calls (if present)
+            """
+            import litellm
+
+            # Build litellm.completion arguments
+            completion_args: dict[str, Any] = {
+                "model": model,
+                "messages": request.messages,
+                **litellm_kwargs,
+            }
+
+            # Add optional request parameters
+            if request.tools:
+                completion_args["tools"] = request.tools
+
+            if request.model_params:
+                completion_args.update(request.model_params)
+
+            # Call LiteLLM
+            try:
+                response = litellm.completion(**completion_args)
+                message = response.choices[0].message
+
+                # Build message dict with all necessary fields for agentic loop
+                # Handle content - it can be a string or list of content blocks
+                content = message.content
+                if isinstance(content, list):
+                    # Extract text from content blocks (robust handling)
+                    text_parts = []
+                    for block in content:
+                        if block is None:
+                            continue  # Skip None blocks
+                        elif isinstance(block, dict):
+                            # Extract text field, ensure it's a string
+                            text_value = block.get("text", "")
+                            text_parts.append(
+                                str(text_value) if text_value is not None else ""
+                            )
+                        else:
+                            # Convert any other type to string
+                            try:
+                                text_parts.append(str(block))
+                            except Exception:
+                                # If str() fails, skip this block
+                                logger.warning(
+                                    f"Unable to convert content block to string: {type(block)}"
+                                )
+                                continue
+                    content = "".join(text_parts)
+
+                message_dict: dict[str, Any] = {
+                    "role": message.role,
+                    "content": content if content else "",
+                }
+
+                # Include tool_calls if present (critical for agentic loop support!)
+                if hasattr(message, "tool_calls") and message.tool_calls:
+                    message_dict["tool_calls"] = [
+                        {
+                            "id": tc.id,
+                            "type": tc.type,
+                            "function": {
+                                "name": tc.function.name,
+                                "arguments": tc.function.arguments,
+                            },
+                        }
+                        for tc in message.tool_calls
+                    ]
+
+                logger.info(
+                    f"LLM provider {func.__name__} processed request "
+                    f"(model={model}, messages={len(request.messages)}, "
+                    f"tool_calls={len(message_dict.get('tool_calls', []))})"
+                )
+
+                return message_dict
+
+            except Exception as e:
+                logger.error(f"LLM provider {func.__name__} failed: {e}")
+                raise
+
+        # Preserve original function's docstring metadata
+        if func.__doc__:
+            process_chat.__doc__ = func.__doc__ + "\n\n" + (process_chat.__doc__ or "")
+
+        # CRITICAL: Apply @mesh.tool() FIRST (before FastMCP caches the function)
+        # This ensures mesh DI wrapper is in place when FastMCP caches the function
+        # Decorators are applied bottom-up, so mesh wrapper must be innermost
+        process_chat = tool(
+            capability=capability,
+            tags=tags,
+            version=version,
+            vendor=vendor,  # Pass vendor to registry for provider handler selection
+        )(process_chat)
+
+        # Then apply @app.tool() for MCP registration (caches the wrapped version)
+        process_chat = app.tool()(process_chat)
+
+        logger.info(
+            f"✅ Created LLM provider '{func.__name__}' -> process_chat "
+            f"(model={model}, capability={capability}, tags={tags}, vendor={vendor})"
+        )
+
+        # Return the generated function (replaces the placeholder)
+        return process_chat
+
+    return decorator

mesh/types.py

@@ -3,7 +3,8 @@ MCP Mesh type definitions for dependency injection.
 """
 
 from collections.abc import AsyncIterator
-from typing import Any, Optional, Protocol
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Protocol
 
 try:
     from pydantic_core import core_schema
@@ -180,113 +181,107 @@ class McpMeshAgent(Protocol):
             }
 
 
-class McpAgent(Protocol):
+class MeshLlmAgent(Protocol):
     """
-    DEPRECATED: Use McpMeshAgent instead.
-
-    This type has been unified with McpMeshAgent. All features previously exclusive
-    to McpAgent are now available in McpMeshAgent using FastMCP's superior client.
-
-    Migration:
-        # Old way (deprecated)
-        def process_files(file_service: McpAgent) -> str:
-            pass
-
-        # New way (recommended)
-        def process_files(file_service: McpMeshAgent) -> str:
-            pass
-
-    McpMeshAgent now provides all MCP protocol features including streaming,
-    session management, and CallToolResult objects via FastMCP client.
+    LLM agent proxy with automatic agentic loop.
+
+    This protocol defines the interface for LLM agents that are automatically injected
+    by the @mesh.llm decorator. The proxy handles the entire agentic loop internally:
+    - Tool formatting for provider (Claude, OpenAI, etc.)
+    - LLM API calls
+    - Tool execution via MCP proxies
+    - Response parsing to Pydantic models
+
+    The MeshLlmAgent is injected by the mesh framework and configured via the
+    @mesh.llm decorator. Users only need to call the proxy with their message.
+
+    Usage Example:
+        from pydantic import BaseModel
+        import mesh
+
+        class ChatResponse(BaseModel):
+            answer: str
+            confidence: float
+
+        @mesh.llm(
+            filter={"capability": "document", "tags": ["pdf"]},
+            provider="claude",
+            model="claude-3-5-sonnet-20241022"
+        )
+        @mesh.tool(capability="chat")
+        def chat(message: str, llm: MeshLlmAgent = None) -> ChatResponse:
+            # Optional: Override system prompt
+            llm.set_system_prompt("You are a helpful document assistant.")
+
+            # Execute automatic agentic loop
+            return llm(message)
+
+    Configuration Hierarchy:
+        - Decorator parameters provide defaults
+        - Environment variables override decorator settings:
+          * MESH_LLM_PROVIDER: Override provider
+          * MESH_LLM_MODEL: Override model
+          * ANTHROPIC_API_KEY: Claude API key
+          * OPENAI_API_KEY: OpenAI API key
+          * MESH_LLM_MAX_ITERATIONS: Override max iterations
+
+    The proxy is automatically injected with:
+        - Filtered tools from registry (based on @mesh.llm filter)
+        - Provider configuration (provider, model, api_key)
+        - Output type (inferred from function return annotation)
+        - System prompt (from decorator or file)
     """
 
-    # Basic compatibility with McpMeshAgent
-    def __call__(self, arguments: Optional[dict[str, Any]] = None) -> Any:
-        """Call the bound remote function (McpMeshAgent compatibility)."""
-        ...
-
-    def invoke(self, arguments: Optional[dict[str, Any]] = None) -> Any:
-        """Explicitly invoke the bound remote function (McpMeshAgent compatibility)."""
-        ...
-
-    # Vanilla MCP Protocol Methods (100% compatibility)
-    async def list_tools(self) -> list:
-        """List available tools from remote agent (vanilla MCP method)."""
-        ...
-
-    async def list_resources(self) -> list:
-        """List available resources from remote agent (vanilla MCP method)."""
-        ...
-
-    async def read_resource(self, uri: str) -> Any:
-        """Read resource contents from remote agent (vanilla MCP method)."""
-        ...
-
-    async def list_prompts(self) -> list:
-        """List available prompts from remote agent (vanilla MCP method)."""
-        ...
-
-    async def get_prompt(self, name: str, arguments: Optional[dict] = None) -> Any:
-        """Get prompt template from remote agent (vanilla MCP method)."""
-        ...
-
-    # Streaming Support - THE BREAKTHROUGH METHOD!
-    async def call_tool_streaming(
-        self, name: str, arguments: dict | None = None
-    ) -> AsyncIterator[dict]:
+    def set_system_prompt(self, prompt: str) -> None:
         """
-        Call a tool with streaming response using FastMCP's text/event-stream.
-
-        This enables multihop streaming (A→B→C chains) by leveraging FastMCP's
-        built-in streaming support with Accept: text/event-stream header.
+        Override the system prompt at runtime.
 
         Args:
-            name: Tool name to call
-            arguments: Tool arguments
-
-        Yields:
-            Streaming response chunks as dictionaries
-        """
-        ...
-
-    # Phase 6: Explicit Session Management
-    async def create_session(self) -> str:
-        """
-        Create a new session and return session ID.
+            prompt: System prompt to use for LLM calls
 
-        For Phase 6 explicit session management. In Phase 8, this will be
-        automated based on @mesh.tool(session_required=True) annotations.
-
-        Returns:
-            New session ID string
+        Example:
+            llm.set_system_prompt("You are an expert document analyst.")
         """
         ...
 
-    async def call_with_session(self, session_id: str, **kwargs) -> Any:
-        """
-        Call tool with explicit session ID for stateful operations.
-
-        This ensures all calls with the same session_id route to the same
-        agent instance for session affinity.
-
-        Args:
-            session_id: Session ID to include in request headers
-            **kwargs: Tool arguments to pass
-
-        Returns:
-            Tool response
+    def __call__(self, message: str | list[dict[str, Any]], **kwargs) -> Any:
         """
-        ...
+        Execute automatic agentic loop and return typed response.
 
-    async def close_session(self, session_id: str) -> bool:
-        """
-        Close session and cleanup session state.
+        This method handles the complete agentic loop:
+        1. Format tools for provider (via LiteLLM)
+        2. Call LLM API with tools
+        3. If tool_use: execute via MCP proxies, loop back to LLM
+        4. If final response: parse into output type (Pydantic model)
+        5. Return typed response
 
         Args:
-            session_id: Session ID to close
+            message: Either:
+                - str: Single user message (will be wrapped in messages array)
+                - list[dict]: Full conversation history with messages in format
+                  [{"role": "user|assistant|system", "content": "..."}]
+            **kwargs: Additional context passed to LLM (provider-specific)
 
         Returns:
-            True if session was closed successfully
+            Pydantic model instance (type inferred from function return annotation)
+
+        Raises:
+            MaxIterationsError: If max_iterations exceeded without final response
+            ValidationError: If LLM response doesn't match output type schema
+            ToolExecutionError: If tool execution fails during agentic loop
+
+        Example (single-turn):
+            response = llm("Analyze this document: /path/to/file.pdf")
+            # Returns ChatResponse(answer="...", confidence=0.95)
+
+        Example (multi-turn):
+            messages = [
+                {"role": "user", "content": "Hello, I need help with Python."},
+                {"role": "assistant", "content": "I'd be happy to help! What do you need?"},
+                {"role": "user", "content": "How do I read a file?"}
+            ]
+            response = llm(messages)
+            # Returns ChatResponse with contextual answer
         """
         ...
 
@@ -299,13 +294,15 @@ class McpAgent(Protocol):
             handler: Any,
         ) -> core_schema.CoreSchema:
             """
-            Custom Pydantic core schema for McpAgent.
+            Custom Pydantic core schema for MeshLlmAgent.
 
-            Similar to McpMeshAgent, this makes McpAgent parameters appear as
-            optional/nullable in MCP schemas, preventing serialization errors
-            while maintaining type safety for dependency injection.
+            This makes MeshLlmAgent parameters appear as optional/nullable in MCP schemas,
+            preventing serialization errors while maintaining type safety for dependency injection.
+
+            The MeshLlmAgentInjector will replace None values with actual proxy objects
+            at runtime, so MCP callers never need to provide these parameters.
             """
-            # Treat McpAgent as an optional Any type for MCP serialization
+            # Treat MeshLlmAgent as an optional Any type for MCP serialization
             return core_schema.with_default_schema(
                 core_schema.nullable_schema(core_schema.any_schema()),
                 default=None,
@@ -320,3 +317,106 @@ class McpAgent(Protocol):
                 "schema": {"type": "nullable", "schema": {"type": "any"}},
                 "default": None,
             }
+
+
+# Import BaseModel for MeshContextModel
+try:
+    from pydantic import BaseModel
+
+    class MeshContextModel(BaseModel):
+        """
+        Base model for LLM prompt template contexts.
+
+        Use this to create type-safe, validated context models for
+        Jinja2 prompt templates in @mesh.llm decorated functions.
+
+        The MeshContextModel provides:
+        - Type safety via Pydantic validation
+        - Field descriptions for LLM schema generation
+        - Strict mode (extra fields forbidden)
+        - Automatic .model_dump() for template rendering
+
+        Example:
+            from mesh import MeshContextModel
+            from pydantic import Field
+
+            class ChatContext(MeshContextModel):
+                user_name: str = Field(description="Name of the user")
+                domain: str = Field(description="Chat domain: support, sales, etc.")
+                expertise_level: str = Field(
+                    default="beginner",
+                    description="User expertise: beginner, intermediate, expert"
+                )
+
+            @mesh.llm(
+                system_prompt="file://prompts/chat.jinja2",
+                context_param="ctx"
+            )
+            @mesh.tool(capability="chat")
+            def chat(message: str, ctx: ChatContext, llm: MeshLlmAgent = None):
+                return llm(message)  # Template auto-rendered with ctx!
+
+        Field Descriptions in LLM Chains:
+            When a specialist LLM agent has MeshContextModel parameters, the Field
+            descriptions are extracted and included in the tool schema sent to
+            calling LLM agents. This helps orchestrator LLMs construct context
+            objects correctly.
+
+            Without descriptions:
+                {"domain": "string"}  # LLM doesn't know what this means
+
+            With descriptions:
+                {"domain": {"type": "string", "description": "Chat domain: support, sales"}}
+                # LLM understands what to provide!
+
+        Template Rendering:
+            When used with @mesh.llm(system_prompt="file://..."), the context is
+            automatically converted to a dict via .model_dump() and passed to the
+            Jinja2 template renderer.
+        """
+
+        class Config:
+            extra = "forbid"  # Strict mode - reject unexpected fields
+
+except ImportError:
+    # Fallback if Pydantic not available (should not happen in practice)
+    class MeshContextModel:  # type: ignore
+        """Placeholder when Pydantic unavailable."""
+
+        pass
+
+
+@dataclass
+class MeshLlmRequest:
+    """
+    Standard LLM request format for mesh-delegated LLM calls.
+
+    This dataclass is used when delegating LLM calls to mesh-registered LLM provider
+    agents via @mesh.llm_provider. It standardizes the request format across the mesh.
+
+    Usage:
+        Provider side (automatic with @mesh.llm_provider):
+            @mesh.llm_provider(model="anthropic/claude-sonnet-4-5", capability="llm")
+            def claude_provider():
+                pass  # Automatically handles MeshLlmRequest
+
+        Consumer side (future with provider=dict):
+            @mesh.llm(provider={"capability": "llm", "tags": ["claude"]})
+            def chat(message: str, llm: MeshLlmAgent = None):
+                return llm(message)  # Converts to MeshLlmRequest internally
+
+    Attributes:
+        messages: List of message dicts with "role" and "content" keys (and optionally "tool_calls")
+        tools: Optional list of tool definitions (MCP format)
+        model_params: Optional parameters to pass to the model (temperature, max_tokens, etc.)
+        context: Optional arbitrary context data for debugging/tracing
+        request_id: Optional request ID for tracking
+        caller_agent: Optional agent name that initiated the request
+    """
+
+    messages: List[Dict[str, Any]]  # Changed from Dict[str, str] to allow tool_calls
+    tools: Optional[List[Dict]] = None
+    model_params: Optional[Dict] = None
+    context: Optional[Dict] = None
+    request_id: Optional[str] = None
+    caller_agent: Optional[str] = None