tactus 0.31.0__py3-none-any.whl

tactus/adapters/lua_tools.py

@@ -0,0 +1,336 @@
+"""
+Lua Tools Adapter - Convert DSL-defined Lua functions to Pydantic AI tools.
+
+Supports:
+- Individual tool() declarations
+- toolset() with type="lua"
+- Inline agent tools with lambda functions
+"""
+
+import logging
+from inspect import Parameter, Signature
+from typing import Any, Dict, List, Optional, Callable
+from pydantic_ai.toolsets import FunctionToolset
+from pydantic import BaseModel, Field, create_model
+
+logger = logging.getLogger(__name__)
+
+
+class LuaToolsAdapter:
+    """Adapter to create Pydantic AI toolsets from Lua function definitions."""
+
+    def __init__(self, tool_primitive: Optional[Any] = None, mock_manager: Optional[Any] = None):
+        """
+        Initialize adapter.
+
+        Args:
+            tool_primitive: Optional ToolPrimitive for call tracking
+            mock_manager: Optional MockManager for mock responses
+        """
+        self.tool_primitive = tool_primitive
+        self.mock_manager = mock_manager
+
+    def create_single_tool_toolset(
+        self, tool_name: str, tool_spec: Dict[str, Any]
+    ) -> FunctionToolset:
+        """
+        Create a FunctionToolset from a single tool() declaration.
+
+        Used for: tool("name", {...}, function)
+
+        Args:
+            tool_name: Name of the tool
+            tool_spec: Dict with description, parameters, handler
+
+        Returns:
+            FunctionToolset with single tool
+        """
+        wrapped_fn = self._create_wrapped_function(tool_name, tool_spec)
+        logger.info(f"Created single-tool toolset '{tool_name}'")
+        return FunctionToolset(tools=[wrapped_fn])
+
+    def create_lua_toolset(
+        self, toolset_name: str, toolset_config: Dict[str, Any]
+    ) -> FunctionToolset:
+        """
+        Create a FunctionToolset from toolset() with type="lua".
+
+        Used for: toolset("name", {type="lua", tools={...}})
+
+        Args:
+            toolset_name: Name of the toolset
+            toolset_config: Dict with type="lua" and tools list
+
+        Returns:
+            FunctionToolset with all tools
+        """
+        tools_list = toolset_config.get("tools", [])
+        if not tools_list:
+            logger.warning(f"Lua toolset '{toolset_name}' has no tools")
+            return FunctionToolset(tools=[])
+
+        wrapped_functions = []
+        for tool_spec in tools_list:
+            tool_name = tool_spec.get("name")
+            if not tool_name:
+                logger.error(f"Tool in toolset '{toolset_name}' missing name")
+                continue
+
+            wrapped_fn = self._create_wrapped_function(tool_name, tool_spec)
+            wrapped_functions.append(wrapped_fn)
+
+        logger.info(f"Created Lua toolset '{toolset_name}' with {len(wrapped_functions)} tools")
+        return FunctionToolset(tools=wrapped_functions)
+
+    def create_inline_tools_toolset(
+        self, agent_name: str, tools_list: List[Dict[str, Any]]
+    ) -> FunctionToolset:
+        """
+        Create a FunctionToolset from inline agent tools.
+
+        Used for: agent("name", {tools = {{...}}})
+
+        Args:
+            agent_name: Name of the agent
+            tools_list: List of inline tool specs
+
+        Returns:
+            FunctionToolset with inline tools
+        """
+        wrapped_functions = []
+        for tool_spec in tools_list:
+            tool_name = tool_spec.get("name")
+            if not tool_name:
+                logger.error(f"Inline tool for agent '{agent_name}' missing name")
+                continue
+
+            # Prefix tool name with agent name for uniqueness
+            prefixed_name = f"{agent_name}_{tool_name}"
+            wrapped_fn = self._create_wrapped_function(prefixed_name, tool_spec)
+            wrapped_functions.append(wrapped_fn)
+
+        logger.info(
+            f"Created inline tools for agent '{agent_name}': {len(wrapped_functions)} tools"
+        )
+        return FunctionToolset(tools=wrapped_functions)
+
+    def create_inline_toolset(
+        self, toolset_name: str, tools_list: List[Dict[str, Any]]
+    ) -> FunctionToolset:
+        """
+        Create a FunctionToolset from inline toolset tools.
+
+        Used for: Toolset "name" { tools = {{...}} }
+
+        Args:
+            toolset_name: Name of the toolset
+            tools_list: List of inline tool specs
+
+        Returns:
+            FunctionToolset with inline tools
+        """
+        wrapped_functions = []
+        for tool_spec in tools_list:
+            tool_name = tool_spec.get("name")
+            if not tool_name:
+                logger.error(f"Inline tool for toolset '{toolset_name}' missing name")
+                continue
+
+            # Prefix tool name with toolset name for uniqueness
+            prefixed_name = f"{toolset_name}_{tool_name}"
+            wrapped_fn = self._create_wrapped_function(prefixed_name, tool_spec)
+            wrapped_functions.append(wrapped_fn)
+
+        logger.info(f"Created inline toolset '{toolset_name}': {len(wrapped_functions)} tools")
+        return FunctionToolset(tools=wrapped_functions)
+
+    def _create_wrapped_function(self, tool_name: str, tool_spec: Dict[str, Any]) -> Callable:
+        """
+        Create a Python async function that wraps a Lua handler.
+
+        Args:
+            tool_name: Tool name for logging/tracking
+            tool_spec: Dict with description, parameters, handler
+
+        Returns:
+            Async Python function suitable for FunctionToolset
+        """
+        lua_handler = tool_spec.get("handler")
+        if lua_handler is None:
+            # Tool/Toolset DSL blocks can specify the handler as an unnamed function value.
+            # `lua_table_to_dict()` preserves that as numeric key `1` for mixed tables.
+            try:
+                candidate = tool_spec.get(1)
+            except Exception:
+                candidate = None
+            if candidate is not None and callable(candidate):
+                lua_handler = candidate
+        description = tool_spec.get("description", f"Tool: {tool_name}")
+        # Only support 'input' field name (new DSL syntax only)
+        input_schema = tool_spec.get("input", {})
+
+        # Debug what we received
+        logger.debug(f"Tool '{tool_name}' spec keys: {list(tool_spec.keys())}")
+        logger.debug(f"Tool '{tool_name}' full spec: {tool_spec}")
+
+        if not lua_handler:
+            raise ValueError(f"Tool '{tool_name}' missing handler function")
+
+        # Create Pydantic model for input
+        param_model = self._create_parameter_model(tool_name, input_schema)
+
+        # Create async wrapper function
+        async def wrapped_tool(**kwargs) -> str:
+            """Tool function that calls Lua handler."""
+            try:
+                # Check for mock response first
+                if self.mock_manager:
+                    mock_result = self.mock_manager.get_mock_response(tool_name, kwargs)
+                    if mock_result is not None:
+                        logger.debug(f"Using mock response for '{tool_name}': {mock_result}")
+                        # Convert mock result to string to match tool return type
+                        result_str = str(mock_result) if mock_result is not None else ""
+                        # Track the mock call
+                        if self.tool_primitive:
+                            self.tool_primitive.record_call(tool_name, kwargs, result_str)
+                        if self.mock_manager:
+                            self.mock_manager.record_call(tool_name, kwargs, result_str)
+                        return result_str
+
+                # Call Lua function directly (Lupa is NOT thread-safe, so we can't use executor)
+                # Lua handlers should be fast and don't do I/O, so this won't block significantly
+
+                # Debug: Log what we're passing
+                logger.debug(f"Calling Lua tool '{tool_name}' with kwargs: {kwargs}")
+
+                # Tool functions expect parameters as a single 'args' table
+                # Pass kwargs directly - Lupa automatically converts Python dicts to Lua tables
+                result = lua_handler(kwargs)
+
+                # Convert result to string
+                result_str = str(result) if result is not None else ""
+
+                # Record tool call
+                if self.tool_primitive:
+                    self.tool_primitive.record_call(tool_name, kwargs, result_str)
+
+                # Also track in mock manager for assertions
+                if self.mock_manager:
+                    self.mock_manager.record_call(tool_name, kwargs, result_str)
+
+                logger.debug(f"Lua tool '{tool_name}' executed successfully")
+                return result_str
+
+            except Exception as e:
+                error_msg = f"Error executing Lua tool '{tool_name}': {str(e)}"
+                logger.error(error_msg, exc_info=True)
+
+                # Record failed call
+                if self.tool_primitive:
+                    self.tool_primitive.record_call(tool_name, kwargs, error_msg)
+
+                # Re-raise to let agent handle it
+                raise RuntimeError(error_msg) from e
+
+        # Build proper signature for Pydantic AI tool discovery
+        sig_params = []
+        logger.debug(f"Building signature for tool '{tool_name}' with schema: {input_schema}")
+
+        # Lua table iteration order is undefined, so ensure signature is always valid:
+        # required params (no defaults) must come before optional params (with defaults).
+        required_param_names: list[str] = []
+        optional_param_names: list[str] = []
+        for param_name in sorted(input_schema.keys()):
+            param_spec = input_schema.get(param_name, {}) or {}
+            if param_spec.get("required", True):
+                required_param_names.append(param_name)
+            else:
+                optional_param_names.append(param_name)
+
+        for param_name in required_param_names + optional_param_names:
+            param_spec = input_schema.get(param_name, {}) or {}
+            param_type = self._map_lua_type(param_spec.get("type", "string"))
+            required = param_spec.get("required", True)
+
+            if required:
+                param = Parameter(
+                    param_name, Parameter.POSITIONAL_OR_KEYWORD, annotation=param_type
+                )
+            else:
+                default = param_spec.get("default")
+                param = Parameter(
+                    param_name,
+                    Parameter.POSITIONAL_OR_KEYWORD,
+                    default=default,
+                    annotation=Optional[param_type],
+                )
+            sig_params.append(param)
+
+        # Set function metadata for Pydantic AI
+        wrapped_tool.__name__ = tool_name
+        wrapped_tool.__doc__ = description
+        wrapped_tool.__signature__ = Signature(sig_params, return_annotation=str)
+        wrapped_tool.__annotations__ = self._build_annotations(param_model)
+
+        return wrapped_tool
+
+    def _create_parameter_model(
+        self, tool_name: str, parameters: Dict[str, Dict[str, Any]]
+    ) -> type[BaseModel]:
+        """
+        Create a Pydantic model from Lua parameter specifications.
+
+        Args:
+            tool_name: Tool name for model naming
+            parameters: Dict of param_name -> {type, description, required}
+
+        Returns:
+            Dynamically created Pydantic model class
+        """
+        if not parameters:
+            # No parameters - return empty model
+            return create_model(f"{tool_name}Params")
+
+        fields = {}
+        for param_name, param_spec in parameters.items():
+            param_type_str = param_spec.get("type", "string")
+            description = param_spec.get("description", "")
+            required = param_spec.get("required", True)
+
+            # Map Lua type strings to Python types
+            python_type = self._map_lua_type(param_type_str)
+
+            # Create field
+            if required:
+                fields[param_name] = (python_type, Field(..., description=description))
+            else:
+                default = param_spec.get("default")
+                fields[param_name] = (
+                    Optional[python_type],
+                    Field(default=default, description=description),
+                )
+
+        return create_model(f"{tool_name}Params", **fields)
+
+    def _map_lua_type(self, lua_type: str) -> type:
+        """Map Lua type string to Python type."""
+        type_map = {
+            "string": str,
+            "number": float,
+            "integer": int,
+            "boolean": bool,
+            "table": dict,
+            "array": list,
+        }
+        return type_map.get(lua_type.lower(), str)
+
+    def _build_annotations(self, param_model: type[BaseModel]) -> Dict[str, type]:
+        """Build __annotations__ dict from Pydantic model."""
+        if not param_model.model_fields:
+            return {"return": str}
+
+        annotations = {}
+        for field_name, field_info in param_model.model_fields.items():
+            annotations[field_name] = field_info.annotation
+        annotations["return"] = str
+        return annotations

tactus/adapters/mcp.py

@@ -0,0 +1,289 @@
+"""
+MCP (Model Context Protocol) adapter for Tactus.
+
+Provides integration with MCP servers to load and convert tools for use with Pydantic AI agents.
+"""
+
+import logging
+from typing import List, Any, Optional, Dict
+from pydantic import create_model, Field
+from pydantic_ai import Tool
+
+logger = logging.getLogger(__name__)
+
+
+class PydanticAIMCPAdapter:
+    """
+    Adapter for converting MCP tools to Pydantic AI format.
+
+    Converts MCP tool definitions (with JSON Schema inputSchema) into
+    Pydantic AI Tool instances with dynamically generated Pydantic models.
+    """
+
+    def __init__(self, mcp_client: Any, tool_primitive: Optional[Any] = None):
+        """
+        Initialize MCP adapter.
+
+        Args:
+            mcp_client: MCP client instance (from fastmcp or similar)
+            tool_primitive: Optional ToolPrimitive for recording tool calls
+        """
+        self.mcp_client = mcp_client
+        self.tool_primitive = tool_primitive
+        logger.debug("PydanticAIMCPAdapter initialized")
+
+    async def load_tools(self) -> List[Tool]:
+        """
+        Load tools from MCP server and convert to Pydantic AI Tools.
+
+        Returns:
+            List of pydantic_ai.Tool instances
+
+        Note: Assumes MCP client has a method to list tools (e.g., list_tools())
+        """
+        try:
+            # Query MCP server for available tools
+            # Common MCP client interface: list_tools() or get_tools()
+            if hasattr(self.mcp_client, "list_tools"):
+                mcp_tools = await self.mcp_client.list_tools()
+            elif hasattr(self.mcp_client, "get_tools"):
+                mcp_tools = await self.mcp_client.get_tools()
+            else:
+                # Try calling as a method that returns tools
+                logger.warning(
+                    "MCP client doesn't have list_tools() or get_tools(), trying direct call"
+                )
+                mcp_tools = await self.mcp_client() if callable(self.mcp_client) else []
+        except Exception as e:
+            logger.error(f"Failed to load tools from MCP server: {e}", exc_info=True)
+            return []
+
+        if not mcp_tools:
+            logger.warning("No tools found from MCP server")
+            return []
+
+        logger.info(f"Found {len(mcp_tools)} tools from MCP server")
+
+        # Convert each MCP tool to Pydantic AI Tool
+        pydantic_tools = []
+        for mcp_tool in mcp_tools:
+            try:
+                tool = self._convert_mcp_tool_to_pydantic_ai(mcp_tool)
+                if tool:
+                    pydantic_tools.append(tool)
+            except Exception as e:
+                logger.error(
+                    f"Failed to convert MCP tool {getattr(mcp_tool, 'name', 'unknown')}: {e}",
+                    exc_info=True,
+                )
+
+        logger.info(f"Converted {len(pydantic_tools)} tools to Pydantic AI format")
+        return pydantic_tools
+
+    def _convert_mcp_tool_to_pydantic_ai(self, mcp_tool: Any) -> Optional[Tool]:
+        """
+        Convert a single MCP tool to Pydantic AI Tool.
+
+        Args:
+            mcp_tool: MCP tool definition (should have name, description, inputSchema)
+
+        Returns:
+            pydantic_ai.Tool instance or None if conversion fails
+        """
+        # Extract tool metadata
+        tool_name = (
+            getattr(mcp_tool, "name", None) or mcp_tool.get("name")
+            if isinstance(mcp_tool, dict)
+            else None
+        )
+        tool_description = (
+            getattr(mcp_tool, "description", None) or mcp_tool.get("description", "")
+            if isinstance(mcp_tool, dict)
+            else ""
+        )
+
+        if not tool_name:
+            logger.warning(f"MCP tool missing name: {mcp_tool}")
+            return None
+
+        # Extract inputSchema (JSON Schema)
+        input_schema = None
+        if hasattr(mcp_tool, "inputSchema"):
+            input_schema = mcp_tool.inputSchema
+        elif isinstance(mcp_tool, dict) and "inputSchema" in mcp_tool:
+            input_schema = mcp_tool["inputSchema"]
+        elif hasattr(mcp_tool, "parameters"):
+            # Some MCP implementations use 'parameters' instead of 'inputSchema'
+            input_schema = mcp_tool.parameters
+
+        # Create Pydantic model from JSON Schema
+        if input_schema:
+            try:
+                args_model = self._json_schema_to_pydantic_model(input_schema, tool_name)
+            except Exception as e:
+                logger.error(
+                    f"Failed to create Pydantic model for tool '{tool_name}': {e}", exc_info=True
+                )
+                # Fallback: create a simple model that accepts any dict
+                args_model = create_model(
+                    f"{tool_name}Args", **{"args": (Dict[str, Any], Field(default={}))}
+                )
+        else:
+            # No schema - create empty model
+            args_model = create_model(f"{tool_name}Args")
+
+        # Create wrapper function that executes the MCP tool
+        async def tool_wrapper(args: args_model) -> str:
+            """
+            Wrapper function that executes the MCP tool call.
+
+            Args:
+                args: Validated arguments from Pydantic model
+
+            Returns:
+                Tool result as string
+            """
+            # Convert Pydantic model to dict for MCP call
+            if hasattr(args, "model_dump"):
+                args_dict = args.model_dump()
+            elif hasattr(args, "dict"):
+                args_dict = args.dict()
+            else:
+                args_dict = dict(args) if hasattr(args, "__dict__") else {}
+
+            logger.info(f"Executing MCP tool '{tool_name}' with args: {args_dict}")
+
+            try:
+                # Call MCP tool - common interface: call_tool(name, args) or tool.execute(args)
+                if hasattr(self.mcp_client, "call_tool"):
+                    result = await self.mcp_client.call_tool(tool_name, args_dict)
+                elif hasattr(self.mcp_client, "call"):
+                    result = await self.mcp_client.call(tool_name, args_dict)
+                elif hasattr(mcp_tool, "execute"):
+                    result = await mcp_tool.execute(args_dict)
+                else:
+                    # Try calling as a method
+                    if callable(mcp_tool):
+                        result = await mcp_tool(**args_dict)
+                    else:
+                        raise ValueError(
+                            f"Cannot execute MCP tool '{tool_name}': no callable interface found"
+                        )
+
+                # Convert result to string
+                if isinstance(result, dict):
+                    # MCP tools often return dict with 'content' or 'text' field
+                    result_str = result.get("content") or result.get("text") or str(result)
+                elif isinstance(result, list):
+                    result_str = str(result)
+                else:
+                    result_str = str(result)
+
+                # Record tool call if tool_primitive is available
+                if self.tool_primitive:
+                    self.tool_primitive.record_call(tool_name, args_dict, result_str)
+
+                logger.debug(f"Tool '{tool_name}' returned: {result_str[:100]}...")
+                return result_str
+
+            except Exception as e:
+                logger.error(f"MCP tool '{tool_name}' execution failed: {e}", exc_info=True)
+                error_msg = f"Error executing tool '{tool_name}': {str(e)}"
+                # Still record the failed call
+                if self.tool_primitive:
+                    self.tool_primitive.record_call(tool_name, args_dict, error_msg)
+                raise
+
+        # Create Pydantic AI Tool
+        tool = Tool(
+            tool_wrapper, name=tool_name, description=tool_description or f"Tool: {tool_name}"
+        )
+
+        return tool
+
+    def _json_schema_to_pydantic_model(
+        self, schema: Dict[str, Any], base_name: str = "Model"
+    ) -> type:
+        """
+        Convert JSON Schema to a Pydantic model.
+
+        Args:
+            schema: JSON Schema dictionary
+            base_name: Base name for the generated model
+
+        Returns:
+            Pydantic model class
+        """
+        # Type mapping from JSON Schema to Python types
+        type_mapping = {
+            "string": str,
+            "integer": int,
+            "number": float,
+            "boolean": bool,
+            "array": list,
+            "object": dict,
+            "null": type(None),
+        }
+
+        # Handle schema type
+        schema_type = schema.get("type", "object")
+        if schema_type != "object":
+            # For non-object schemas, create a simple wrapper
+            python_type = type_mapping.get(schema_type, Any)
+            return create_model(f"{base_name}Args", value=(python_type, Field(...)))
+
+        # Extract properties
+        properties = schema.get("properties", {})
+        required_fields = schema.get("required", [])
+
+        # Build fields dict for create_model
+        fields = {}
+        for field_name, field_schema in properties.items():
+            field_type_info = field_schema.get("type", "string")
+            python_type = type_mapping.get(field_type_info, Any)
+
+            # Check if field is required
+            is_required = field_name in required_fields
+
+            # Handle default values
+            default_value = field_schema.get("default", ...)
+            if not is_required and default_value is ...:
+                default_value = None
+
+            # Create Field with description if available
+            field_description = field_schema.get("description", "")
+            if field_description:
+                fields[field_name] = (
+                    python_type,
+                    Field(default=default_value, description=field_description),
+                )
+            else:
+                fields[field_name] = (python_type, Field(default=default_value))
+
+        # Create the model
+        model_name = schema.get("title", f"{base_name}Args")
+        return create_model(model_name, **fields)
+
+
+def convert_mcp_tools_to_pydantic_ai(
+    mcp_tools: List[Any], tool_primitive: Optional[Any] = None
+) -> List[Tool]:
+    """
+    Convert MCP tools to Pydantic AI Tool format.
+
+    Args:
+        mcp_tools: List of MCP tool objects
+        tool_primitive: Optional ToolPrimitive for recording calls
+
+    Returns:
+        List of pydantic_ai.Tool objects
+
+    Note: This is a convenience function. For full MCP integration,
+    use PydanticAIMCPAdapter with an MCP client.
+    """
+    # This function is kept for backward compatibility but requires an adapter
+    # In practice, use PydanticAIMCPAdapter.load_tools() instead
+    logger.warning(
+        "convert_mcp_tools_to_pydantic_ai() is deprecated - use PydanticAIMCPAdapter instead"
+    )
+    return []