ouroboros-ai 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

ouroboros/mcp/tools/definitions.py

@@ -0,0 +1,351 @@
+"""Ouroboros tool definitions for MCP server.
+
+This module defines the standard Ouroboros tools that are exposed
+via the MCP server:
+- execute_seed: Execute a seed (task specification)
+- session_status: Get current session status
+- query_events: Query event history
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+import structlog
+
+from ouroboros.core.types import Result
+from ouroboros.mcp.errors import MCPServerError, MCPToolError
+from ouroboros.mcp.types import (
+    ContentType,
+    MCPContentItem,
+    MCPToolDefinition,
+    MCPToolParameter,
+    MCPToolResult,
+    ToolInputType,
+)
+
+log = structlog.get_logger(__name__)
+
+
+@dataclass
+class ExecuteSeedHandler:
+    """Handler for the execute_seed tool.
+
+    Executes a seed (task specification) in the Ouroboros system.
+    This is the primary entry point for running tasks.
+    """
+
+    @property
+    def definition(self) -> MCPToolDefinition:
+        """Return the tool definition."""
+        return MCPToolDefinition(
+            name="ouroboros_execute_seed",
+            description=(
+                "Execute a seed (task specification) in Ouroboros. "
+                "A seed defines a task to be executed with acceptance criteria."
+            ),
+            parameters=(
+                MCPToolParameter(
+                    name="seed_content",
+                    type=ToolInputType.STRING,
+                    description="The seed content describing the task to execute",
+                    required=True,
+                ),
+                MCPToolParameter(
+                    name="session_id",
+                    type=ToolInputType.STRING,
+                    description="Optional session ID to resume. If not provided, a new session is created.",
+                    required=False,
+                ),
+                MCPToolParameter(
+                    name="model_tier",
+                    type=ToolInputType.STRING,
+                    description="Model tier to use (small, medium, large). Default: medium",
+                    required=False,
+                    default="medium",
+                    enum=("small", "medium", "large"),
+                ),
+                MCPToolParameter(
+                    name="max_iterations",
+                    type=ToolInputType.INTEGER,
+                    description="Maximum number of execution iterations. Default: 10",
+                    required=False,
+                    default=10,
+                ),
+            ),
+        )
+
+    async def handle(
+        self,
+        arguments: dict[str, Any],
+    ) -> Result[MCPToolResult, MCPServerError]:
+        """Handle a seed execution request.
+
+        Args:
+            arguments: Tool arguments including seed_content.
+
+        Returns:
+            Result containing execution result or error.
+        """
+        seed_content = arguments.get("seed_content")
+        if not seed_content:
+            return Result.err(
+                MCPToolError(
+                    "seed_content is required",
+                    tool_name="ouroboros_execute_seed",
+                )
+            )
+
+        session_id = arguments.get("session_id")
+        model_tier = arguments.get("model_tier", "medium")
+        max_iterations = arguments.get("max_iterations", 10)
+
+        log.info(
+            "mcp.tool.execute_seed",
+            session_id=session_id,
+            model_tier=model_tier,
+            max_iterations=max_iterations,
+        )
+
+        # This is a placeholder - actual implementation would integrate
+        # with the Ouroboros execution engine
+        try:
+            # TODO: Integrate with actual execution engine
+            result_text = (
+                f"Seed execution initiated.\n"
+                f"Session ID: {session_id or 'new'}\n"
+                f"Model tier: {model_tier}\n"
+                f"Max iterations: {max_iterations}\n"
+                f"Seed content: {seed_content[:100]}..."
+            )
+
+            return Result.ok(
+                MCPToolResult(
+                    content=(
+                        MCPContentItem(type=ContentType.TEXT, text=result_text),
+                    ),
+                    is_error=False,
+                    meta={"session_id": session_id or "new-session-id"},
+                )
+            )
+        except Exception as e:
+            log.error("mcp.tool.execute_seed.error", error=str(e))
+            return Result.err(
+                MCPToolError(
+                    f"Seed execution failed: {e}",
+                    tool_name="ouroboros_execute_seed",
+                )
+            )
+
+
+@dataclass
+class SessionStatusHandler:
+    """Handler for the session_status tool.
+
+    Returns the current status of an Ouroboros session.
+    """
+
+    @property
+    def definition(self) -> MCPToolDefinition:
+        """Return the tool definition."""
+        return MCPToolDefinition(
+            name="ouroboros_session_status",
+            description=(
+                "Get the status of an Ouroboros session. "
+                "Returns information about the current phase, progress, and any errors."
+            ),
+            parameters=(
+                MCPToolParameter(
+                    name="session_id",
+                    type=ToolInputType.STRING,
+                    description="The session ID to query",
+                    required=True,
+                ),
+            ),
+        )
+
+    async def handle(
+        self,
+        arguments: dict[str, Any],
+    ) -> Result[MCPToolResult, MCPServerError]:
+        """Handle a session status request.
+
+        Args:
+            arguments: Tool arguments including session_id.
+
+        Returns:
+            Result containing session status or error.
+        """
+        session_id = arguments.get("session_id")
+        if not session_id:
+            return Result.err(
+                MCPToolError(
+                    "session_id is required",
+                    tool_name="ouroboros_session_status",
+                )
+            )
+
+        log.info("mcp.tool.session_status", session_id=session_id)
+
+        try:
+            # TODO: Integrate with actual session management
+            status_text = (
+                f"Session: {session_id}\n"
+                f"Status: active\n"
+                f"Phase: execution\n"
+                f"Progress: 60%\n"
+                f"Current iteration: 3/10\n"
+            )
+
+            return Result.ok(
+                MCPToolResult(
+                    content=(
+                        MCPContentItem(type=ContentType.TEXT, text=status_text),
+                    ),
+                    is_error=False,
+                    meta={
+                        "session_id": session_id,
+                        "status": "active",
+                        "phase": "execution",
+                        "progress": 0.6,
+                    },
+                )
+            )
+        except Exception as e:
+            log.error("mcp.tool.session_status.error", error=str(e))
+            return Result.err(
+                MCPToolError(
+                    f"Failed to get session status: {e}",
+                    tool_name="ouroboros_session_status",
+                )
+            )
+
+
+@dataclass
+class QueryEventsHandler:
+    """Handler for the query_events tool.
+
+    Queries the event history for a session or across sessions.
+    """
+
+    @property
+    def definition(self) -> MCPToolDefinition:
+        """Return the tool definition."""
+        return MCPToolDefinition(
+            name="ouroboros_query_events",
+            description=(
+                "Query the event history for an Ouroboros session. "
+                "Returns a list of events matching the specified criteria."
+            ),
+            parameters=(
+                MCPToolParameter(
+                    name="session_id",
+                    type=ToolInputType.STRING,
+                    description="Filter events by session ID. If not provided, returns events across all sessions.",
+                    required=False,
+                ),
+                MCPToolParameter(
+                    name="event_type",
+                    type=ToolInputType.STRING,
+                    description="Filter by event type (e.g., 'execution', 'evaluation', 'error')",
+                    required=False,
+                ),
+                MCPToolParameter(
+                    name="limit",
+                    type=ToolInputType.INTEGER,
+                    description="Maximum number of events to return. Default: 50",
+                    required=False,
+                    default=50,
+                ),
+                MCPToolParameter(
+                    name="offset",
+                    type=ToolInputType.INTEGER,
+                    description="Number of events to skip for pagination. Default: 0",
+                    required=False,
+                    default=0,
+                ),
+            ),
+        )
+
+    async def handle(
+        self,
+        arguments: dict[str, Any],
+    ) -> Result[MCPToolResult, MCPServerError]:
+        """Handle an event query request.
+
+        Args:
+            arguments: Tool arguments for filtering events.
+
+        Returns:
+            Result containing matching events or error.
+        """
+        session_id = arguments.get("session_id")
+        event_type = arguments.get("event_type")
+        limit = arguments.get("limit", 50)
+        offset = arguments.get("offset", 0)
+
+        log.info(
+            "mcp.tool.query_events",
+            session_id=session_id,
+            event_type=event_type,
+            limit=limit,
+            offset=offset,
+        )
+
+        try:
+            # TODO: Integrate with actual event store
+            events_text = (
+                f"Event Query Results\n"
+                f"==================\n"
+                f"Session: {session_id or 'all'}\n"
+                f"Type filter: {event_type or 'all'}\n"
+                f"Showing {offset} to {offset + limit}\n\n"
+                f"1. [execution] Started seed execution\n"
+                f"2. [evaluation] Mechanical check passed\n"
+                f"3. [execution] Iteration 2 completed\n"
+            )
+
+            return Result.ok(
+                MCPToolResult(
+                    content=(
+                        MCPContentItem(type=ContentType.TEXT, text=events_text),
+                    ),
+                    is_error=False,
+                    meta={
+                        "total_events": 3,
+                        "offset": offset,
+                        "limit": limit,
+                    },
+                )
+            )
+        except Exception as e:
+            log.error("mcp.tool.query_events.error", error=str(e))
+            return Result.err(
+                MCPToolError(
+                    f"Failed to query events: {e}",
+                    tool_name="ouroboros_query_events",
+                )
+            )
+
+
+# Convenience functions for handler access
+def execute_seed_handler() -> ExecuteSeedHandler:
+    """Create an ExecuteSeedHandler instance."""
+    return ExecuteSeedHandler()
+
+
+def session_status_handler() -> SessionStatusHandler:
+    """Create a SessionStatusHandler instance."""
+    return SessionStatusHandler()
+
+
+def query_events_handler() -> QueryEventsHandler:
+    """Create a QueryEventsHandler instance."""
+    return QueryEventsHandler()
+
+
+# List of all Ouroboros tools for registration
+OUROBOROS_TOOLS: tuple[ExecuteSeedHandler | SessionStatusHandler | QueryEventsHandler, ...] = (
+    ExecuteSeedHandler(),
+    SessionStatusHandler(),
+    QueryEventsHandler(),
+)

ouroboros/mcp/tools/registry.py

@@ -0,0 +1,269 @@
+"""Tool registry for managing MCP tool handlers.
+
+This module provides a registry for managing tool handlers, supporting
+dynamic registration, discovery, and invocation of tools.
+"""
+
+import threading
+from collections.abc import Sequence
+from typing import Any
+
+import structlog
+
+from ouroboros.core.types import Result
+from ouroboros.mcp.errors import MCPResourceNotFoundError, MCPServerError, MCPToolError
+from ouroboros.mcp.server.protocol import ToolHandler
+from ouroboros.mcp.types import MCPToolDefinition, MCPToolResult
+
+log = structlog.get_logger(__name__)
+
+
+class ToolRegistry:
+    """Registry for managing MCP tool handlers.
+
+    Provides a centralized place to register, discover, and invoke tools.
+    Supports grouping tools by category and provides metadata for discovery.
+
+    Example:
+        registry = ToolRegistry()
+
+        # Register individual handlers
+        registry.register(ExecuteSeedHandler())
+        registry.register(SessionStatusHandler())
+
+        # Or register multiple at once
+        registry.register_all([
+            ExecuteSeedHandler(),
+            SessionStatusHandler(),
+        ])
+
+        # List tools
+        tools = registry.list_tools()
+
+        # Call a tool
+        result = await registry.call("execute_seed", {"seed_id": "123"})
+    """
+
+    def __init__(self) -> None:
+        """Initialize the registry."""
+        self._handlers: dict[str, ToolHandler] = {}
+        self._categories: dict[str, set[str]] = {}
+
+    @property
+    def tool_count(self) -> int:
+        """Return the number of registered tools."""
+        return len(self._handlers)
+
+    def register(
+        self,
+        handler: ToolHandler,
+        *,
+        category: str = "default",
+    ) -> None:
+        """Register a tool handler.
+
+        Args:
+            handler: The tool handler to register.
+            category: Optional category for grouping tools.
+
+        Raises:
+            ValueError: If a tool with the same name is already registered.
+        """
+        name = handler.definition.name
+
+        if name in self._handlers:
+            msg = f"Tool already registered: {name}"
+            raise ValueError(msg)
+
+        self._handlers[name] = handler
+
+        # Track category
+        if category not in self._categories:
+            self._categories[category] = set()
+        self._categories[category].add(name)
+
+        log.info("mcp.registry.tool_registered", tool=name, category=category)
+
+    def register_all(
+        self,
+        handlers: Sequence[ToolHandler],
+        *,
+        category: str = "default",
+    ) -> None:
+        """Register multiple tool handlers.
+
+        Args:
+            handlers: The tool handlers to register.
+            category: Optional category for grouping tools.
+        """
+        for handler in handlers:
+            self.register(handler, category=category)
+
+    def unregister(self, name: str) -> bool:
+        """Unregister a tool handler.
+
+        Args:
+            name: Name of the tool to unregister.
+
+        Returns:
+            True if the tool was unregistered, False if not found.
+        """
+        if name not in self._handlers:
+            return False
+
+        del self._handlers[name]
+
+        # Remove from categories
+        for category_tools in self._categories.values():
+            category_tools.discard(name)
+
+        log.info("mcp.registry.tool_unregistered", tool=name)
+        return True
+
+    def get(self, name: str) -> ToolHandler | None:
+        """Get a tool handler by name.
+
+        Args:
+            name: Name of the tool.
+
+        Returns:
+            The tool handler or None if not found.
+        """
+        return self._handlers.get(name)
+
+    def list_tools(self, category: str | None = None) -> Sequence[MCPToolDefinition]:
+        """List all registered tools.
+
+        Args:
+            category: Optional category to filter by.
+
+        Returns:
+            Sequence of tool definitions.
+        """
+        if category is not None:
+            tool_names = self._categories.get(category, set())
+            return tuple(
+                self._handlers[name].definition
+                for name in tool_names
+                if name in self._handlers
+            )
+
+        return tuple(h.definition for h in self._handlers.values())
+
+    def list_categories(self) -> Sequence[str]:
+        """List all tool categories.
+
+        Returns:
+            Sequence of category names.
+        """
+        return tuple(self._categories.keys())
+
+    def tools_in_category(self, category: str) -> Sequence[str]:
+        """List tool names in a category.
+
+        Args:
+            category: Category name.
+
+        Returns:
+            Sequence of tool names in the category.
+        """
+        return tuple(self._categories.get(category, set()))
+
+    async def call(
+        self,
+        name: str,
+        arguments: dict[str, Any],
+    ) -> Result[MCPToolResult, MCPServerError]:
+        """Call a registered tool.
+
+        Args:
+            name: Name of the tool to call.
+            arguments: Arguments for the tool.
+
+        Returns:
+            Result containing the tool result or an error.
+        """
+        handler = self._handlers.get(name)
+        if not handler:
+            return Result.err(
+                MCPResourceNotFoundError(
+                    f"Tool not found: {name}",
+                    resource_type="tool",
+                    resource_id=name,
+                )
+            )
+
+        try:
+            log.debug("mcp.registry.calling_tool", tool=name)
+            result = await handler.handle(arguments)
+            return result
+        except Exception as e:
+            log.error("mcp.registry.tool_error", tool=name, error=str(e))
+            return Result.err(
+                MCPToolError(
+                    f"Tool execution failed: {e}",
+                    tool_name=name,
+                )
+            )
+
+    def get_definition(self, name: str) -> MCPToolDefinition | None:
+        """Get the definition for a tool.
+
+        Args:
+            name: Name of the tool.
+
+        Returns:
+            The tool definition or None if not found.
+        """
+        handler = self._handlers.get(name)
+        return handler.definition if handler else None
+
+    def has_tool(self, name: str) -> bool:
+        """Check if a tool is registered.
+
+        Args:
+            name: Name of the tool.
+
+        Returns:
+            True if the tool is registered.
+        """
+        return name in self._handlers
+
+    def clear(self) -> None:
+        """Clear all registered tools."""
+        self._handlers.clear()
+        self._categories.clear()
+        log.info("mcp.registry.cleared")
+
+
+# Global registry instance for convenience
+_global_registry: ToolRegistry | None = None
+_global_registry_lock = threading.Lock()
+
+
+def get_global_registry() -> ToolRegistry:
+    """Get the global tool registry.
+
+    Returns:
+        The global ToolRegistry instance.
+    """
+    global _global_registry
+    if _global_registry is None:
+        with _global_registry_lock:
+            if _global_registry is None:
+                _global_registry = ToolRegistry()
+    return _global_registry
+
+
+def register_tool(
+    handler: ToolHandler,
+    *,
+    category: str = "default",
+) -> None:
+    """Register a tool handler with the global registry.
+
+    Args:
+        handler: The tool handler to register.
+        category: Optional category for grouping tools.
+    """
+    get_global_registry().register(handler, category=category)