tactus 0.31.0__py3-none-any.whl

tactus/adapters/mcp_manager.py

@@ -0,0 +1,196 @@
+"""
+MCP Server Manager for Tactus.
+
+Manages multiple MCP server connections using Pydantic AI's native MCPServerStdio.
+Handles lifecycle, tool prefixing, and tool call tracking.
+"""
+
+import logging
+import os
+import re
+import asyncio
+from contextlib import AsyncExitStack
+from typing import Dict, Any, List
+
+from pydantic_ai.mcp import MCPServerStdio
+
+logger = logging.getLogger(__name__)
+
+
+def substitute_env_vars(value: Any) -> Any:
+    """
+    Replace ${VAR} with environment variable values.
+
+    Args:
+        value: Value to process (can be str, dict, list, or other)
+
+    Returns:
+        Value with environment variables substituted
+    """
+    if isinstance(value, str):
+        # Replace ${VAR} or $VAR with environment variable value
+        return re.sub(r"\$\{(\w+)\}", lambda m: os.getenv(m.group(1), ""), value)
+    elif isinstance(value, dict):
+        return {k: substitute_env_vars(v) for k, v in value.items()}
+    elif isinstance(value, list):
+        return [substitute_env_vars(v) for v in value]
+    return value
+
+
+class MCPServerManager:
+    """
+    Manages multiple native Pydantic AI MCP servers.
+
+    Uses Pydantic AI's MCPServerStdio for stdio transport and automatic
+    tool prefixing. Handles connection lifecycle and tool call tracking.
+    """
+
+    def __init__(self, server_configs: Dict[str, Dict[str, Any]], tool_primitive=None):
+        """
+        Initialize MCP server manager.
+
+        Args:
+            server_configs: Dict of {server_name: {command, args, env}}
+            tool_primitive: Optional ToolPrimitive for recording tool calls
+        """
+        self.configs = server_configs
+        self.tool_primitive = tool_primitive
+        self.servers: List[MCPServerStdio] = []
+        self.server_toolsets: Dict[str, MCPServerStdio] = {}  # Map server names to toolsets
+        self._exit_stack = AsyncExitStack()
+        logger.info(f"MCPServerManager initialized with {len(server_configs)} server(s)")
+
+    async def __aenter__(self):
+        """Connect to all configured MCP servers."""
+        for name, config in self.configs.items():
+            # Retry a few times for transient stdio startup issues.
+            last_error: Exception | None = None
+            for attempt in range(1, 4):
+                try:
+                    logger.info(f"Connecting to MCP server '{name}' (attempt {attempt}/3)...")
+
+                    # Substitute environment variables in config
+                    config = substitute_env_vars(config)
+
+                    # Create base server
+                    server = MCPServerStdio(
+                        command=config["command"],
+                        args=config.get("args", []),
+                        env=config.get("env"),
+                        cwd=config.get("cwd"),
+                        process_tool_call=self._create_trace_callback(name),  # Tracking hook
+                    )
+
+                    # Wrap with prefix to namespace tools
+                    prefixed_server = server.prefixed(name)
+
+                    # Connect the prefixed server
+                    await self._exit_stack.enter_async_context(prefixed_server)
+                    self.servers.append(prefixed_server)
+                    self.server_toolsets[name] = prefixed_server  # Store by name for lookup
+                    logger.info(
+                        f"Successfully connected to MCP server '{name}' with prefix '{name}_'"
+                    )
+                    last_error = None
+                    break
+                except Exception as e:
+                    last_error = e
+
+                    # Check if this is a fileno error (common in test environments)
+                    import io
+
+                    error_str = str(e)
+                    if "fileno" in error_str or isinstance(e, io.UnsupportedOperation):
+                        logger.warning(
+                            f"Failed to connect to MCP server '{name}': {e} "
+                            f"(test environment with redirected streams)"
+                        )
+                        # Allow procedures to continue without MCP in this environment.
+                        last_error = None
+                        break
+
+                    # Retry transient anyio TaskGroup/broken stream issues.
+                    if (
+                        "BrokenResourceError" in error_str
+                        or "unhandled errors in a TaskGroup" in error_str
+                    ):
+                        logger.warning(
+                            f"Transient MCP connection failure for '{name}': {e} (retrying)"
+                        )
+                        await asyncio.sleep(0.05 * attempt)
+                        continue
+
+                    logger.error(f"Failed to connect to MCP server '{name}': {e}", exc_info=True)
+                    break
+
+            if last_error is not None:
+                # For non-transient failures, raise so callers can decide whether to ignore.
+                raise last_error
+
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Disconnect from all MCP servers."""
+        logger.info("Disconnecting from all MCP servers...")
+        await self._exit_stack.aclose()
+        logger.info("All MCP servers disconnected")
+
+    def _create_trace_callback(self, server_name: str):
+        """
+        Create a tool call tracing callback for a specific server.
+
+        Args:
+            server_name: Name of the MCP server
+
+        Returns:
+            Async callback function for process_tool_call
+        """
+
+        async def trace_tool_call(ctx, next_call, tool_name, tool_args):
+            """Middleware to record tool calls in Tactus ToolPrimitive."""
+            logger.debug(
+                f"MCP server '{server_name}' calling tool '{tool_name}' with args: {tool_args}"
+            )
+
+            try:
+                result = await next_call(tool_name, tool_args)
+
+                # Record in ToolPrimitive if available
+                if self.tool_primitive:
+                    # Convert result to string for consistency with old behavior
+                    # Pydantic AI tools can return various types
+                    result_str = str(result) if not isinstance(result, str) else result
+                    self.tool_primitive.record_call(tool_name, tool_args, result_str)
+
+                logger.debug(f"Tool '{tool_name}' completed successfully")
+                return result
+            except Exception as e:
+                logger.error(f"Tool '{tool_name}' failed: {e}", exc_info=True)
+                # Still record the failed call
+                if self.tool_primitive:
+                    error_msg = f"Error: {str(e)}"
+                    self.tool_primitive.record_call(tool_name, tool_args, error_msg)
+                raise
+
+        return trace_tool_call
+
+    def get_toolsets(self) -> List[MCPServerStdio]:
+        """
+        Return list of connected servers as toolsets.
+
+        Returns:
+            List of MCPServerStdio instances (which are AbstractToolset)
+        """
+        return self.servers
+
+    def get_toolset_by_name(self, server_name: str):
+        """
+        Get a specific toolset by server name.
+
+        Args:
+            server_name: Name of the MCP server
+
+        Returns:
+            MCPServerStdio instance for the named server, or None if not found
+        """
+        return self.server_toolsets.get(server_name)

tactus/adapters/memory.py

@@ -0,0 +1,53 @@
+"""
+In-memory storage backend for Tactus.
+
+Simple implementation that stores all data in memory (RAM).
+Useful for testing and simple CLI workflows that don't need persistence.
+"""
+
+from typing import Optional, Any, Dict
+
+from tactus.protocols.models import ProcedureMetadata
+
+
+class MemoryStorage:
+    """
+    In-memory storage backend.
+
+    All data stored in Python dicts - lost when process exits.
+    """
+
+    def __init__(self):
+        """Initialize in-memory storage."""
+        self._procedures: Dict[str, ProcedureMetadata] = {}
+
+    def load_procedure_metadata(self, procedure_id: str) -> ProcedureMetadata:
+        """Load procedure metadata from memory."""
+        if procedure_id not in self._procedures:
+            # Create new metadata if doesn't exist
+            self._procedures[procedure_id] = ProcedureMetadata(procedure_id=procedure_id)
+        return self._procedures[procedure_id]
+
+    def save_procedure_metadata(self, procedure_id: str, metadata: ProcedureMetadata) -> None:
+        """Save procedure metadata to memory."""
+        self._procedures[procedure_id] = metadata
+
+    def update_procedure_status(
+        self, procedure_id: str, status: str, waiting_on_message_id: Optional[str] = None
+    ) -> None:
+        """Update procedure status."""
+        metadata = self.load_procedure_metadata(procedure_id)
+        metadata.status = status
+        metadata.waiting_on_message_id = waiting_on_message_id
+        self.save_procedure_metadata(procedure_id, metadata)
+
+    def get_state(self, procedure_id: str) -> Dict[str, Any]:
+        """Get mutable state dictionary."""
+        metadata = self.load_procedure_metadata(procedure_id)
+        return metadata.state
+
+    def set_state(self, procedure_id: str, state: Dict[str, Any]) -> None:
+        """Set mutable state dictionary."""
+        metadata = self.load_procedure_metadata(procedure_id)
+        metadata.state = state
+        self.save_procedure_metadata(procedure_id, metadata)

tactus/adapters/plugins.py

@@ -0,0 +1,419 @@
+"""
+Local Python Plugin Loader for Tactus.
+
+Provides lightweight tool loading from local Python files without requiring MCP servers.
+"""
+
+import logging
+import importlib.util
+import inspect
+import sys
+from pathlib import Path
+from typing import List, Any, Optional, Callable
+from pydantic_ai import Tool
+from pydantic_ai.toolsets import FunctionToolset
+
+logger = logging.getLogger(__name__)
+
+
+class PluginLoader:
+    """
+    Loader for local Python function tools.
+
+    Scans specified directories and files for Python functions and converts them
+    to Pydantic AI Tool instances.
+
+    Convention: Any public function (not starting with _) in the specified paths
+    is automatically loaded as a tool. The function's docstring becomes the tool
+    description, and type hints are used for parameter validation.
+    """
+
+    def __init__(self, tool_primitive: Optional[Any] = None):
+        """
+        Initialize plugin loader.
+
+        Args:
+            tool_primitive: Optional ToolPrimitive for recording tool calls
+        """
+        self.tool_primitive = tool_primitive
+        self.loaded_modules = {}  # Cache loaded modules
+        logger.debug("PluginLoader initialized")
+
+    def create_toolset(self, paths: List[str], name: str = "plugin") -> FunctionToolset:
+        """
+        Create a FunctionToolset from specified paths.
+
+        This is the preferred method for loading plugin tools - it returns a composable
+        toolset that can be combined with other toolsets.
+
+        Args:
+            paths: List of directory paths or file paths to scan
+            name: Name for the toolset (used in logging)
+
+        Returns:
+            FunctionToolset instance containing all loaded tools
+        """
+        # Load all functions from paths
+        functions = self._load_all_functions(paths)
+
+        if not functions:
+            logger.warning(f"No functions found in paths: {paths}")
+            # Return empty toolset
+            return FunctionToolset(tools=[])
+
+        # Create toolset
+        # Note: FunctionToolset doesn't support process_tool_call parameter
+        # Tool call tracking needs to be done at Agent level
+        toolset = FunctionToolset(tools=functions)
+
+        logger.info(f"Created FunctionToolset '{name}' with {len(functions)} tool(s)")
+        return toolset
+
+    def load_from_paths(self, paths: List[str]) -> List[Tool]:
+        """
+        Load tools from specified paths (directories or files).
+
+        DEPRECATED: Use create_toolset() instead. This method is kept for backward
+        compatibility but will be removed in a future version.
+
+        Args:
+            paths: List of directory paths or file paths to scan
+
+        Returns:
+            List of pydantic_ai.Tool instances
+        """
+        all_tools = []
+
+        for path_str in paths:
+            path = Path(path_str).resolve()
+
+            if not path.exists():
+                logger.warning(f"Tool path does not exist: {path}")
+                continue
+
+            if path.is_file():
+                # Load tools from single file
+                if path.suffix == ".py":
+                    tools = self._load_tools_from_file(path)
+                    all_tools.extend(tools)
+                else:
+                    logger.warning(f"Skipping non-Python file: {path}")
+            elif path.is_dir():
+                # Scan directory for Python files
+                tools = self._load_tools_from_directory(path)
+                all_tools.extend(tools)
+            else:
+                logger.warning(f"Path is neither file nor directory: {path}")
+
+        logger.info(f"Loaded {len(all_tools)} tools from {len(paths)} path(s)")
+        return all_tools
+
+    def _load_all_functions(self, paths: List[str]) -> List[Callable]:
+        """
+        Load all functions from specified paths.
+
+        Args:
+            paths: List of directory paths or file paths to scan
+
+        Returns:
+            List of callable functions (not wrapped in Tool)
+        """
+        all_functions = []
+
+        for path_str in paths:
+            path = Path(path_str).resolve()
+
+            if not path.exists():
+                logger.warning(f"Tool path does not exist: {path}")
+                continue
+
+            if path.is_file():
+                if path.suffix == ".py":
+                    functions = self._load_functions_from_file(path)
+                    all_functions.extend(functions)
+                else:
+                    logger.warning(f"Skipping non-Python file: {path}")
+            elif path.is_dir():
+                functions = self._load_functions_from_directory(path)
+                all_functions.extend(functions)
+            else:
+                logger.warning(f"Path is neither file nor directory: {path}")
+
+        logger.debug(f"Loaded {len(all_functions)} function(s) from {len(paths)} path(s)")
+        return all_functions
+
+    def _load_functions_from_directory(self, directory: Path) -> List[Callable]:
+        """
+        Scan directory for Python files and load functions.
+
+        Args:
+            directory: Directory path to scan
+
+        Returns:
+            List of callable functions
+        """
+        functions = []
+
+        for py_file in directory.glob("*.py"):
+            if py_file.name.startswith("_"):
+                continue
+
+            file_functions = self._load_functions_from_file(py_file)
+            functions.extend(file_functions)
+
+        return functions
+
+    def _load_functions_from_file(self, file_path: Path) -> List[Callable]:
+        """
+        Load functions from a single Python file.
+
+        Args:
+            file_path: Path to Python file
+
+        Returns:
+            List of callable functions
+        """
+        functions = []
+
+        try:
+            # Create module name from file path
+            module_name = f"tactus_plugin_{file_path.stem}_{id(file_path)}"
+
+            # Load module dynamically
+            spec = importlib.util.spec_from_file_location(module_name, file_path)
+            if spec is None or spec.loader is None:
+                logger.error(f"Could not load spec for {file_path}")
+                return functions
+
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[module_name] = module
+            spec.loader.exec_module(module)
+
+            # Cache the module
+            self.loaded_modules[str(file_path)] = module
+
+            logger.debug(f"Loaded module from {file_path}")
+
+            # Find all public functions in the module
+            for name, obj in inspect.getmembers(module):
+                if self._is_valid_tool_function(name, obj, module):
+                    functions.append(obj)
+                    logger.debug(f"Found function '{name}' in {file_path.name}")
+
+        except Exception as e:
+            logger.error(f"Failed to load functions from {file_path}: {e}", exc_info=True)
+
+        return functions
+
+    def _create_trace_callback(self, toolset_name: str):
+        """
+        Create a tool call tracing callback for the toolset.
+
+        Args:
+            toolset_name: Name of the toolset
+
+        Returns:
+            Async callback function for process_tool_call
+        """
+
+        async def trace_tool_call(ctx, next_call, tool_name, tool_args):
+            """Middleware to record tool calls in Tactus ToolPrimitive."""
+            logger.debug(
+                f"Toolset '{toolset_name}' calling tool '{tool_name}' with args: {tool_args}"
+            )
+
+            try:
+                result = await next_call(tool_name, tool_args)
+
+                # Record in ToolPrimitive if available
+                if self.tool_primitive:
+                    result_str = str(result) if not isinstance(result, str) else result
+                    self.tool_primitive.record_call(tool_name, tool_args, result_str)
+
+                logger.debug(f"Tool '{tool_name}' completed successfully")
+                return result
+            except Exception as e:
+                logger.error(f"Tool '{tool_name}' failed: {e}", exc_info=True)
+                # Still record the failed call
+                if self.tool_primitive:
+                    error_msg = f"Error: {str(e)}"
+                    self.tool_primitive.record_call(tool_name, tool_args, error_msg)
+                raise
+
+        return trace_tool_call
+
+    def _load_tools_from_directory(self, directory: Path) -> List[Tool]:
+        """
+        Recursively scan directory for Python files and load tools.
+
+        Args:
+            directory: Directory path to scan
+
+        Returns:
+            List of Tool instances
+        """
+        tools = []
+
+        # Find all .py files (non-recursive for now)
+        for py_file in directory.glob("*.py"):
+            if py_file.name.startswith("_"):
+                # Skip private modules (e.g., __init__.py, __pycache__)
+                continue
+
+            file_tools = self._load_tools_from_file(py_file)
+            tools.extend(file_tools)
+
+        return tools
+
+    def _load_tools_from_file(self, file_path: Path) -> List[Tool]:
+        """
+        Load tools from a single Python file.
+
+        Args:
+            file_path: Path to Python file
+
+        Returns:
+            List of Tool instances
+        """
+        tools = []
+
+        try:
+            # Create module name from file path
+            module_name = f"tactus_plugin_{file_path.stem}_{id(file_path)}"
+
+            # Load module dynamically
+            spec = importlib.util.spec_from_file_location(module_name, file_path)
+            if spec is None or spec.loader is None:
+                logger.error(f"Could not load spec for {file_path}")
+                return tools
+
+            module = importlib.util.module_from_spec(spec)
+
+            # Add to sys.modules so imports work
+            sys.modules[module_name] = module
+
+            # Execute module
+            spec.loader.exec_module(module)
+
+            # Cache the module
+            self.loaded_modules[str(file_path)] = module
+
+            logger.debug(f"Loaded module from {file_path}")
+
+            # Find all public functions in the module
+            for name, obj in inspect.getmembers(module):
+                if self._is_valid_tool_function(name, obj, module):
+                    tool = self._create_tool_from_function(obj, name)
+                    if tool:
+                        tools.append(tool)
+                        logger.info(f"Loaded tool '{name}' from {file_path.name}")
+
+        except Exception as e:
+            logger.error(f"Failed to load tools from {file_path}: {e}", exc_info=True)
+
+        return tools
+
+    def _is_valid_tool_function(self, name: str, obj: Any, module: Any) -> bool:
+        """
+        Check if an object is a valid tool function.
+
+        Args:
+            name: Object name
+            obj: Object to check
+            module: Module the object belongs to
+
+        Returns:
+            True if object is a valid tool function
+        """
+        # Must be a function
+        if not inspect.isfunction(obj):
+            return False
+
+        # Must be public (not start with _)
+        if name.startswith("_"):
+            return False
+
+        # Must be defined in this module (not imported)
+        if obj.__module__ != module.__name__:
+            return False
+
+        return True
+
+    def _create_tool_from_function(self, func: Callable, name: str) -> Optional[Tool]:
+        """
+        Create a Pydantic AI Tool from a Python function.
+
+        Args:
+            func: Python function to wrap
+            name: Tool name
+
+        Returns:
+            Tool instance or None if creation fails
+        """
+        try:
+            # Get function signature and docstring
+            sig = inspect.signature(func)
+            doc = inspect.getdoc(func) or f"Tool: {name}"
+
+            # Check if function is async
+            is_async = inspect.iscoroutinefunction(func)
+
+            # Create wrapper that records tool calls
+            if is_async:
+
+                async def tool_wrapper(*args, **kwargs):
+                    """Async wrapper for tool function."""
+                    try:
+                        result = await func(*args, **kwargs)
+
+                        # Record tool call if tool_primitive is available
+                        if self.tool_primitive:
+                            self.tool_primitive.record_call(name, kwargs, str(result))
+
+                        return result
+                    except Exception as e:
+                        logger.error(f"Tool '{name}' execution failed: {e}", exc_info=True)
+                        error_msg = f"Error executing tool '{name}': {str(e)}"
+
+                        # Record failed call
+                        if self.tool_primitive:
+                            self.tool_primitive.record_call(name, kwargs, error_msg)
+
+                        raise
+
+            else:
+
+                def tool_wrapper(*args, **kwargs):
+                    """Sync wrapper for tool function."""
+                    try:
+                        result = func(*args, **kwargs)
+
+                        # Record tool call if tool_primitive is available
+                        if self.tool_primitive:
+                            self.tool_primitive.record_call(name, kwargs, str(result))
+
+                        return result
+                    except Exception as e:
+                        logger.error(f"Tool '{name}' execution failed: {e}", exc_info=True)
+                        error_msg = f"Error executing tool '{name}': {str(e)}"
+
+                        # Record failed call
+                        if self.tool_primitive:
+                            self.tool_primitive.record_call(name, kwargs, error_msg)
+
+                        raise
+
+            # Copy signature and docstring to wrapper
+            tool_wrapper.__signature__ = sig
+            tool_wrapper.__doc__ = doc
+            tool_wrapper.__name__ = name
+            tool_wrapper.__annotations__ = func.__annotations__
+
+            # Create Pydantic AI Tool
+            tool = Tool(tool_wrapper, name=name, description=doc)
+
+            return tool
+
+        except Exception as e:
+            logger.error(f"Failed to create tool from function '{name}': {e}", exc_info=True)
+            return None