polyrob 0.5.0__py3-none-any.whl

tools/controller/mcp_registrar.py

@@ -0,0 +1,190 @@
+"""MCP → direct-action registration (Item 7H — extracted from ``controller/service.py``).
+
+LLMs consistently fail to use nested ``mcp_execute_tool(arguments={...})``. This
+registrar flattens each discovered MCP tool into a direct action named
+``{server}_{tool}`` with a dynamic Pydantic param model built from the tool's JSON
+input schema — eliminating the nesting problem.
+
+It holds a back-reference to the owning ``Controller`` so ``registry`` and ``logger``
+stay live (the Controller delegates ``_register_mcp_tools_as_direct_actions`` /
+``_create_param_model_from_schema`` here). The WS-B5 typed-array behaviour (arrays
+carry their item type; objects stay lenient ``dict``) is preserved verbatim.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Type
+
+from pydantic import BaseModel
+
+
+class MCPActionRegistrar:
+    """Registers MCP server tools as flat Controller actions + builds param models."""
+
+    def __init__(self, controller: Any) -> None:
+        self._controller = controller
+
+    @property
+    def registry(self):
+        return self._controller.registry
+
+    @property
+    def logger(self):
+        return self._controller.logger
+
+    async def register(self, mcp_tool: Any) -> None:
+        """Register individual MCP tools as direct actions with flat parameter schemas.
+
+        Args:
+            mcp_tool: The MCPTool instance with server_manager
+        """
+        self.logger.info("🔧 _register_mcp_tools_as_direct_actions called")
+
+        if not hasattr(mcp_tool, 'server_manager') or not mcp_tool.server_manager:
+            self.logger.warning("MCP tool has no server_manager, cannot register direct actions")
+            return
+
+        try:
+            # Get all MCP tools from all servers
+            all_tools = mcp_tool.server_manager.get_all_tools()
+            self.logger.info(f"🔧 Found {len(all_tools)} MCP servers with tools")
+            registered_count = 0
+
+            for server_name, tools in all_tools.items():
+                for tool_meta in tools:
+                    try:
+                        # Create namespaced action name: server_toolname
+                        action_name = f"{server_name}_{tool_meta.name}"
+
+                        # Skip if already registered (avoid duplicates with mcp_* wrapper actions)
+                        if action_name in self.registry.actions:
+                            self.logger.debug(f"MCP action '{action_name}' already registered, skipping")
+                            continue
+
+                        # Create a dynamic Pydantic model from the tool's input schema
+                        param_model = self.create_param_model(
+                            action_name,
+                            tool_meta.input_schema or {}
+                        )
+
+                        # Create an async executor that routes to execute_mcp_tool
+                        # Use closure to capture server_name and tool_name
+                        def make_executor(srv_name, t_name, mcp_ref):
+                            # execution_context is a NAMED param (not **kwargs) so the
+                            # registry routes the per-call context here instead of folding
+                            # it into the MCP params dict — and so it reaches the per-tenant
+                            # rate limiter (was falling back to a shared "global" bucket,
+                            # cross-keying tenants).
+                            async def executor(params_obj=None, execution_context=None, **kwargs):
+                                # Convert Pydantic model to dict if needed
+                                if params_obj is not None:
+                                    if hasattr(params_obj, 'model_dump'):
+                                        params = params_obj.model_dump()
+                                    elif isinstance(params_obj, dict):
+                                        params = params_obj
+                                    else:
+                                        params = dict(params_obj) if params_obj else {}
+                                else:
+                                    params = kwargs
+                                # Execute via MCP tool's execute_mcp_tool method
+                                action = f"{srv_name}_{t_name}"
+                                return await mcp_ref.execute_mcp_tool(
+                                    action, params, execution_context=execution_context
+                                )
+                            return executor
+
+                        executor_func = make_executor(server_name, tool_meta.name, mcp_tool)
+
+                        # Store metadata for routing
+                        executor_func._mcp_server = server_name
+                        executor_func._mcp_tool = tool_meta.name
+
+                        # Register with the registry
+                        self.registry.wrap_function(
+                            name=action_name,
+                            function=executor_func,
+                            description=tool_meta.description or f"Execute {tool_meta.name} on {server_name}",
+                            tool='mcp',
+                            param_model=param_model
+                        )
+
+                        registered_count += 1
+                        self.logger.debug(f"Registered MCP action: {action_name}")
+
+                    except Exception as e:
+                        self.logger.warning(f"Failed to register MCP tool {server_name}_{tool_meta.name}: {e}")
+
+            self.logger.info(f"✅ Registered {registered_count} MCP tools as direct actions")
+
+        except Exception as e:
+            self.logger.error(f"Failed to register MCP tools as direct actions: {e}", exc_info=True)
+
+    def create_param_model(self, action_name: str, schema: Dict[str, Any]) -> Type[BaseModel]:
+        """Create a dynamic Pydantic model from a JSON schema.
+
+        Args:
+            action_name: Name for the model
+            schema: JSON schema dict with properties, required, etc.
+
+        Returns:
+            Dynamically created Pydantic BaseModel subclass
+        """
+        from pydantic import create_model, Field
+        from typing import Optional, List, Any as TypingAny
+
+        properties = schema.get('properties', {})
+        required = set(schema.get('required', []))
+
+        # Build field definitions
+        fields = {}
+        for prop_name, prop_schema in properties.items():
+            prop_type = prop_schema.get('type', 'string')
+            description = prop_schema.get('description', '')
+            default = prop_schema.get('default', ...)
+
+            # Map JSON schema types to Python types
+            type_mapping = {
+                'string': str,
+                'integer': int,
+                'number': float,
+                'boolean': bool,
+                'array': list,
+                'object': dict,
+            }
+
+            python_type = type_mapping.get(prop_type, TypingAny)
+
+            # WS-B5: preserve array item type (List[item]) instead of bare list.
+            # Objects stay as dict (lenient) so previously-valid payloads with
+            # unforeseen keys are never rejected.
+            if prop_type == 'array':
+                items_schema = prop_schema.get('items') or {}
+                item_type = type_mapping.get(items_schema.get('type'), TypingAny)
+                python_type = List[item_type]
+
+            # Handle nullable types (anyOf with null)
+            if 'anyOf' in prop_schema:
+                for option in prop_schema['anyOf']:
+                    if option.get('type') == 'null':
+                        python_type = Optional[python_type]
+                        break
+
+            # Set default based on whether field is required
+            if prop_name in required:
+                field_default = ...  # Required
+            elif default != ...:
+                field_default = default
+            else:
+                field_default = None
+                python_type = Optional[python_type] if python_type != Optional else python_type
+
+            # Create field with description
+            fields[prop_name] = (python_type, Field(default=field_default, description=description))
+
+        # Create dynamic model
+        model_name = f"MCP_{action_name.replace('-', '_').title().replace('_', '')}Params"
+
+        try:
+            return create_model(model_name, **fields)
+        except Exception as e:
+            self.logger.warning(f"Failed to create param model for {action_name}: {e}, using empty model")
+            return create_model(model_name)

tools/controller/message_send.py

@@ -0,0 +1,31 @@
+"""Pure-ish send helper for the `message` action: resolve tier, gate, route.
+Router is any object with async send_message(chat_id, text, surface_id)."""
+import logging
+from core.surfaces.outbound_target import resolve_target_tier
+
+logger = logging.getLogger(__name__)
+
+
+async def perform_message_send(*, router, allowlist, owner_targets, user_id,
+                               surface, target, text, action="send", reply_to=None,
+                               message_id=None) -> dict:
+    tier = resolve_target_tier(surface=surface, target=target, user_id=user_id,
+                               allowlist=allowlist, owner_targets=owner_targets)
+    if tier == "denied":
+        return {"success": False, "tier": "denied", "surface": surface, "target": target,
+                "error": ("target not on owner allowlist; ask the owner to run "
+                          f"`/allow {surface} {target}` (or `polyrob owner allow {surface} {target}`)")}
+    if action not in ("send", "reply"):
+        # edit/delete/react are capability-gated and deferred to P2; fail cleanly.
+        return {"success": False, "tier": tier, "surface": surface, "target": target,
+                "error": f"action '{action}' not supported yet on {surface}"}
+    if router is None:
+        return {"success": False, "tier": tier, "surface": surface, "target": target,
+                "error": "no message_router available (SINGULAR_CHAT_ENABLED off?)"}
+    try:
+        ok = await router.send_message(chat_id=target, text=text, surface_id=surface)
+    except Exception as e:  # fail-open: never crash the loop on a send fault
+        logger.error("message send failed: %s", e, exc_info=True)
+        return {"success": False, "tier": tier, "surface": surface, "target": target, "error": str(e)}
+    return {"success": bool(ok), "tier": tier, "surface": surface, "target": target,
+            "error": None if ok else "send returned false"}

tools/controller/registry/__init__.py

@@ -0,0 +1,4 @@
+from tools.controller.registry.service import Registry
+from tools.controller.registry.views import ActionModel, ActionRegistry, RegisteredAction
+
+__all__ = ['Registry', 'ActionModel', 'ActionRegistry', 'RegisteredAction'] 

tools/controller/registry/schema_generators.py

@@ -0,0 +1,395 @@
+"""Provider-specific tool schema generators for native tool calling"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Type, Tuple
+import json
+import logging
+import os
+from pydantic import BaseModel
+
+from tools.controller.registry.views import RegisteredAction
+from agents.task.utils import fix_openai_schema, fix_anthropic_schema
+
+logger = logging.getLogger(__name__)
+
+
+class SchemaValidationError(Exception):
+    """Raised when a generated schema fails validation."""
+    pass
+
+
+_VALID_SCHEMA_ERROR_POLICIES = ("DROP_TOOL", "RAISE", "WARN")
+
+
+def get_schema_error_policy() -> str:
+    """Policy for handling a tool whose generated native schema fails validation.
+
+    Env ``TOOL_SCHEMA_ERROR_POLICY`` (default ``DROP_TOOL``):
+      - ``DROP_TOOL`` — exclude the offending tool from the emitted list (never
+        ship an invalid schema to the provider).
+      - ``RAISE``     — propagate ``SchemaValidationError``.
+      - ``WARN``      — legacy: log and ship the tool anyway.
+    """
+    val = os.getenv("TOOL_SCHEMA_ERROR_POLICY", "DROP_TOOL").upper().strip()
+    return val if val in _VALID_SCHEMA_ERROR_POLICIES else "DROP_TOOL"
+
+
+class ToolSchemaGenerator(ABC):
+    """Base class for provider-specific tool schema generation"""
+
+    @abstractmethod
+    def generate_tool_schema(self, action: RegisteredAction) -> Dict[str, Any]:
+        """Generate tool schema for specific provider"""
+        pass
+
+    @abstractmethod
+    def generate_tools_list(self, actions: List[RegisteredAction]) -> Any:
+        """Generate the complete tools list/object for the provider"""
+        pass
+
+    def _get_json_schema(self, param_model: Type[BaseModel]) -> Dict[str, Any]:
+        """Get JSON schema from Pydantic model, removing unnecessary fields"""
+        schema = param_model.model_json_schema()
+        # Remove title from properties to reduce token usage
+        if 'properties' in schema:
+            for prop in schema['properties'].values():
+                if isinstance(prop, dict) and 'title' in prop:
+                    del prop['title']
+        # Remove title from root
+        if 'title' in schema:
+            del schema['title']
+        return schema
+
+    def _validate_schema(self, schema: Dict[str, Any], action_name: str) -> Tuple[bool, List[str]]:
+        """Validate a generated schema for common issues.
+
+        Returns:
+            Tuple of (is_valid, list of warning/error messages)
+        """
+        issues = []
+
+        # Check for basic structure
+        if not isinstance(schema, dict):
+            issues.append(f"Schema for '{action_name}' is not a dictionary")
+            return False, issues
+
+        # Check for required fields based on schema type
+        if 'function' in schema:
+            # OpenAI format
+            func = schema.get('function', {})
+            if not func.get('name'):
+                issues.append(f"OpenAI schema for '{action_name}' missing function name")
+            if not func.get('description'):
+                issues.append(f"OpenAI schema for '{action_name}' missing description")
+            if 'parameters' not in func:
+                issues.append(f"OpenAI schema for '{action_name}' missing parameters")
+            else:
+                params = func.get('parameters', {})
+                if params.get('type') != 'object':
+                    issues.append(f"OpenAI schema for '{action_name}' parameters should have type 'object'")
+        elif 'input_schema' in schema:
+            # Anthropic format
+            if not schema.get('name'):
+                issues.append(f"Anthropic schema for '{action_name}' missing name")
+            if not schema.get('description'):
+                issues.append(f"Anthropic schema for '{action_name}' missing description")
+            input_schema = schema.get('input_schema', {})
+            if input_schema.get('type') != 'object':
+                issues.append(f"Anthropic schema for '{action_name}' input_schema should have type 'object'")
+        elif 'parameters' in schema and 'name' in schema:
+            # Gemini format
+            if not schema.get('name'):
+                issues.append(f"Gemini schema for '{action_name}' missing name")
+            if not schema.get('description'):
+                issues.append(f"Gemini schema for '{action_name}' missing description")
+
+        # Check for empty properties (debug only - not an error, some actions have no params)
+        properties = None
+        if 'function' in schema:
+            properties = schema.get('function', {}).get('parameters', {}).get('properties')
+        elif 'input_schema' in schema:
+            properties = schema.get('input_schema', {}).get('properties')
+        elif 'parameters' in schema:
+            properties = schema.get('parameters', {}).get('properties')
+
+        # Note: Empty properties is not an error - some actions intentionally have no parameters
+        # (e.g., get_positions, get_portfolio_value, etc.)
+        # Only log at debug level to avoid noise
+        if properties is not None and len(properties) == 0:
+            logger.debug(f"Schema for '{action_name}' has empty properties (no parameters) - this is expected for parameterless actions")
+
+        is_valid = len([i for i in issues if 'missing' in i.lower()]) == 0
+        return is_valid, issues
+
+    def validate_and_log(self, schema: Dict[str, Any], action_name: str) -> Dict[str, Any]:
+        """Validate schema and log any issues.
+
+        Args:
+            schema: The generated schema
+            action_name: Name of the action for logging
+
+        Returns:
+            The schema (unchanged)
+
+        Raises:
+            SchemaValidationError: If validation fails critically
+        """
+        is_valid, issues = self._validate_schema(schema, action_name)
+
+        if issues:
+            for issue in issues:
+                if 'missing' in issue.lower():
+                    logger.error(f"Schema validation error: {issue}")
+                else:
+                    logger.warning(f"Schema validation warning: {issue}")
+
+        if not is_valid:
+            raise SchemaValidationError(f"Schema validation failed for '{action_name}': {issues}")
+
+        return schema
+
+    def _apply_schema_error_policy(self, schema: Dict[str, Any], action_name: str) -> Optional[Dict[str, Any]]:
+        """Validate ``schema`` and apply ``TOOL_SCHEMA_ERROR_POLICY``.
+
+        Returns the schema if valid (or under WARN policy), ``None`` if the tool
+        should be dropped (DROP_TOOL), or raises ``SchemaValidationError`` (RAISE).
+        """
+        is_valid, issues = self._validate_schema(schema, action_name)
+        if is_valid:
+            return schema
+
+        policy = get_schema_error_policy()
+        msg = f"Schema validation failed for '{action_name}': {issues}"
+        if policy == "RAISE":
+            raise SchemaValidationError(msg)
+        if policy == "WARN":
+            logger.warning(f"{msg} (WARN policy: shipping tool anyway)")
+            return schema
+        # DROP_TOOL (default): never ship an invalid schema to the provider
+        logger.warning(f"{msg} (DROP_TOOL policy: excluding this tool from the list)")
+        return None
+
+
+class OpenAISchemaGenerator(ToolSchemaGenerator):
+    """OpenAI function calling schema generator"""
+
+    def generate_tool_schema(self, action: RegisteredAction, validate: bool = True) -> Dict[str, Any]:
+        """Generate OpenAI function schema"""
+        # Get the base schema
+        params_schema = self._get_json_schema(action.param_model)
+
+        # Apply OpenAI-specific fixes (additionalProperties: false)
+        params_schema = fix_openai_schema(params_schema)
+
+        schema = {
+            "type": "function",
+            "function": {
+                "name": action.name,
+                "description": action.description,
+                "parameters": params_schema
+            }
+        }
+
+        # Validate if requested (log warnings but don't fail)
+        if validate:
+            try:
+                self.validate_and_log(schema, action.name)
+            except SchemaValidationError as e:
+                logger.warning(f"Schema validation issue (continuing anyway): {e}")
+
+        return schema
+
+    def generate_tools_list(self, actions: List[RegisteredAction]) -> List[Dict[str, Any]]:
+        """Generate OpenAI tools list with deduplication by name + error policy."""
+        seen_names = set()
+        tools = []
+        for action in actions:
+            if action.name in seen_names:
+                logger.debug(f"Skipping duplicate tool name: {action.name}")
+                continue
+            seen_names.add(action.name)
+            schema = self._apply_schema_error_policy(
+                self.generate_tool_schema(action, validate=False), action.name
+            )
+            if schema is not None:
+                tools.append(schema)
+        return tools
+
+
+class AnthropicSchemaGenerator(ToolSchemaGenerator):
+    """Anthropic tool calling schema generator"""
+
+    def generate_tool_schema(self, action: RegisteredAction, validate: bool = True) -> Dict[str, Any]:
+        """Generate Anthropic tool schema"""
+        # Get the base schema
+        params_schema = self._get_json_schema(action.param_model)
+
+        # Apply Anthropic-specific fixes (additionalProperties: false)
+        params_schema = fix_anthropic_schema(params_schema)
+
+        schema = {
+            "name": action.name,
+            "description": action.description,
+            "input_schema": params_schema
+        }
+
+        # Validate if requested (log warnings but don't fail)
+        if validate:
+            try:
+                self.validate_and_log(schema, action.name)
+            except SchemaValidationError as e:
+                logger.warning(f"Schema validation issue (continuing anyway): {e}")
+
+        return schema
+
+    def generate_tools_list(self, actions: List[RegisteredAction]) -> List[Dict[str, Any]]:
+        """Generate Anthropic tools list with deduplication by name + error policy."""
+        seen_names = set()
+        tools = []
+        for action in actions:
+            if action.name in seen_names:
+                logger.debug(f"Skipping duplicate tool name: {action.name}")
+                continue
+            seen_names.add(action.name)
+            schema = self._apply_schema_error_policy(
+                self.generate_tool_schema(action, validate=False), action.name
+            )
+            if schema is not None:
+                tools.append(schema)
+        return tools
+
+
+class GeminiSchemaGenerator(ToolSchemaGenerator):
+    """Google Gemini function calling schema generator"""
+
+    def generate_tool_schema(self, action: RegisteredAction, validate: bool = True) -> Dict[str, Any]:
+        """Generate Gemini function schema"""
+        base_schema = self._get_json_schema(action.param_model)
+
+        # Gemini expects 'type' and 'properties' at minimum
+        parameters = {
+            "type": "object",
+            "properties": base_schema.get("properties", {}),
+        }
+
+        # Only add required if it exists and is non-empty
+        if "required" in base_schema and base_schema["required"]:
+            parameters["required"] = base_schema["required"]
+
+        schema = {
+            "name": action.name,
+            "description": action.description,
+            "parameters": parameters
+        }
+
+        # Validate if requested (log warnings but don't fail)
+        if validate:
+            try:
+                self.validate_and_log(schema, action.name)
+            except SchemaValidationError as e:
+                logger.warning(f"Schema validation issue (continuing anyway): {e}")
+
+        return schema
+
+    def generate_tools_list(self, actions: List[RegisteredAction]) -> List[Dict[str, Any]]:
+        """Generate Gemini tools list with function declarations + error policy."""
+        if not actions:
+            return []
+
+        declarations = []
+        for action in actions:
+            schema = self._apply_schema_error_policy(
+                self.generate_tool_schema(action, validate=False), action.name
+            )
+            if schema is not None:
+                declarations.append(schema)
+        if not declarations:
+            return []
+        return [{"function_declarations": declarations}]
+
+
+class JSONFallbackSchemaGenerator(ToolSchemaGenerator):
+    """JSON schema generator for providers without native tool support"""
+
+    def generate_tool_schema(self, action: RegisteredAction) -> Dict[str, Any]:
+        """Generate JSON schema for action"""
+        return {
+            "name": action.name,
+            "description": action.description,
+            "parameters": self._get_json_schema(action.param_model)
+        }
+
+    def generate_tools_list(self, actions: List[RegisteredAction]) -> Dict[str, Any]:
+        """Generate JSON schema for all actions"""
+        # This creates a schema that expects: {"action": [{"action_name": {...params}}]}
+        action_properties = {}
+
+        for action in actions:
+            action_properties[action.name] = {
+                "type": "object",
+                "description": action.description,
+                "properties": action.param_model.model_json_schema().get("properties", {}),
+                "required": action.param_model.model_json_schema().get("required", [])
+            }
+
+        return {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "array",
+                    "description": "List of actions to execute",
+                    "items": {
+                        "type": "object",
+                        "properties": action_properties,
+                        "additionalProperties": False
+                    }
+                }
+            },
+            "required": ["action"]
+        }
+
+
+# Provider registry mapping
+# NOTE: DeepSeek V3+ uses OpenAI-compatible function calling API
+# NOTE: OpenRouter proxies to many providers and uses OpenAI-compatible format
+SCHEMA_GENERATORS = {
+    "openai": OpenAISchemaGenerator(),
+    "anthropic": AnthropicSchemaGenerator(),
+    "gemini": GeminiSchemaGenerator(),
+    "google": GeminiSchemaGenerator(),  # Alias
+    "deepseek": OpenAISchemaGenerator(),  # DeepSeek V3+ is OpenAI-compatible
+    "openrouter": OpenAISchemaGenerator(),  # OpenRouter uses OpenAI-compatible format
+    "nvidia": OpenAISchemaGenerator(),  # NVIDIA NIM uses OpenAI-compatible format
+    "groq": JSONFallbackSchemaGenerator(),
+    "fireworks": JSONFallbackSchemaGenerator(),
+    "default": JSONFallbackSchemaGenerator(),
+}
+
+
+# Providers that have intentionally fallen back to the JSON generator are tracked
+# so we warn exactly once per unrecognized provider string (avoids log spam).
+_warned_fallback_providers: set = set()
+
+
+def get_schema_generator(provider: str) -> ToolSchemaGenerator:
+    """Get the appropriate schema generator for a provider.
+
+    Falls back to the JSON generator for unknown providers — but warns once so a
+    misspelled/new provider silently losing native tool-calling is visible
+    (see the new-provider checklist: SCHEMA_GENERATORS is the easy-to-miss seam).
+    """
+    provider_lower = provider.lower()
+
+    # Check for partial matches (e.g., "openai-gpt4" -> "openai")
+    for key in SCHEMA_GENERATORS:
+        if key != "default" and key in provider_lower:
+            return SCHEMA_GENERATORS[key]
+
+    if provider_lower not in _warned_fallback_providers:
+        _warned_fallback_providers.add(provider_lower)
+        logger.warning(
+            f"No native schema generator matched provider '{provider}' — using JSON "
+            f"fallback (native tool-calling disabled). If this provider supports native "
+            f"tools, add it to SCHEMA_GENERATORS."
+        )
+    return SCHEMA_GENERATORS["default"]