hexdag 0.5.0.dev1__py3-none-any.whl

hexdag/builtin/adapters/mock/mock_llm.py

@@ -0,0 +1,177 @@
+"""Mock LLM implementation for testing purposes."""
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from hexdag.core.ports.llm import LLM, MessageList
+
+if TYPE_CHECKING:
+    from hexdag.core.ports.healthcheck import HealthStatus
+
+
+class MockLLM(LLM):
+    """Mock implementation of the LLM interface for testing.
+
+    The LLM port interface is stateless, but this mock provides testing utilities like response
+    sequencing and call inspection without violating the port contract.
+    """
+
+    # Type annotations for attributes
+    delay_seconds: float
+    responses: list[str]
+    call_count: int
+    last_messages: MessageList | None
+    should_raise: bool
+    mock_tool_calls: list[dict[str, Any] | list[dict[str, Any]]] | None
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize with configuration.
+
+        Args
+        ----
+            **kwargs: Configuration options
+                - responses: List of text responses or single response string
+                - delay_seconds: Delay before returning responses
+                - mock_tool_calls: List of tool call configurations for testing
+        """
+        self.delay_seconds = kwargs.get("delay_seconds", 0.0)
+
+        # Process responses (convert to list if needed)
+        responses = kwargs.get("responses")
+        if responses is not None:
+            if isinstance(responses, str):
+                self.responses = [responses]
+            else:
+                self.responses = responses
+        else:
+            self.responses = ['{"result": "Mock response"}']
+
+        # Process mock tool calls
+        self.mock_tool_calls = kwargs.get("mock_tool_calls")
+
+        # Non-config state
+        self.call_count = 0
+        self.last_messages: MessageList | None = None
+        self.should_raise = False
+
+    async def aresponse(self, messages: MessageList) -> str | None:
+        """Return a response based on the configured responses.
+
+        Parameters
+        ----------
+        messages : MessageList
+            List of messages to process
+
+        Returns
+        -------
+        str | None
+            Mock response string or None
+
+        Raises
+        ------
+        Exception
+            When should_raise is True for testing error conditions
+        """
+        self.last_messages = messages
+
+        if self.delay_seconds > 0:
+            await asyncio.sleep(self.delay_seconds)
+
+        if self.should_raise:
+            raise Exception("Mock LLM error for testing")
+
+        if self.call_count < len(self.responses):
+            response = self.responses[self.call_count]
+        else:
+            response = self.responses[-1]  # Repeat last response
+
+        self.call_count += 1
+        return response
+
+    async def aresponse_with_tools(
+        self,
+        messages: MessageList,
+        tools: list[dict[str, Any]],
+        tool_choice: str | dict[str, Any] = "auto",
+    ) -> Any:
+        """Mock implementation of tool calling with configurable tool call simulation.
+
+        For testing purposes, this can simulate tool calls based on configuration.
+        If mock_tool_calls are configured, it will return those. Otherwise, it
+        returns a regular response without tool calls.
+
+        Examples
+        --------
+        Configure mock to return tool calls::
+
+            mock_llm = MockLLM(
+                responses=["I'll search for that"],
+                mock_tool_calls=[
+                    {
+                        "id": "call_123",
+                        "name": "search",
+                        "arguments": {"query": "test"}
+                    }
+                ]
+            )
+        """
+        from hexdag.core.ports.llm import LLMResponse, ToolCall
+
+        # Get regular response
+        response_text = await self.aresponse(messages)
+
+        # Check if mock tool calls are configured
+        mock_tool_calls = getattr(self, "mock_tool_calls", None)
+
+        if mock_tool_calls and self.call_count <= len(mock_tool_calls):
+            # Return configured tool calls
+            tool_call_data = (
+                mock_tool_calls[self.call_count - 1]
+                if self.call_count <= len(mock_tool_calls)
+                else mock_tool_calls[-1]
+            )
+
+            if isinstance(tool_call_data, dict):
+                tool_calls_list = [
+                    ToolCall(
+                        id=tool_call_data.get("id", "call_mock"),
+                        name=tool_call_data.get("name", "mock_tool"),
+                        arguments=tool_call_data.get("arguments", {}),
+                    )
+                ]
+            elif isinstance(tool_call_data, list):
+                tool_calls_list = [
+                    ToolCall(
+                        id=tc.get("id", f"call_mock_{i}"),
+                        name=tc.get("name", "mock_tool"),
+                        arguments=tc.get("arguments", {}),
+                    )
+                    for i, tc in enumerate(tool_call_data)
+                ]
+            else:
+                tool_calls_list = None
+
+            return LLMResponse(
+                content=response_text,
+                tool_calls=tool_calls_list,
+                finish_reason="tool_calls" if tool_calls_list else "stop",
+            )
+
+        # Return as LLMResponse without tool calls
+        return LLMResponse(content=response_text, tool_calls=None, finish_reason="stop")
+
+    async def ahealth_check(self) -> "HealthStatus":
+        """Health check for Mock LLM (always healthy)."""
+        from hexdag.core.ports.healthcheck import HealthStatus
+
+        return HealthStatus(
+            status="healthy",
+            adapter_name="MockLLM",
+            latency_ms=0.1,
+        )
+
+    # Testing utilities (not part of the LLM port interface)
+    def reset(self) -> None:
+        """Reset the mock state for testing."""
+        self.call_count = 0
+        self.last_messages = None

hexdag/builtin/adapters/mock/mock_tool_adapter.py

@@ -0,0 +1,192 @@
+"""Simple mock tool adapter with predefined responses for testing."""
+
+from typing import Any
+
+from hexdag.core.ports.tool_router import ToolRouter
+
+
+class MockToolAdapter(ToolRouter):
+    """Mock tool adapter that returns predefined responses.
+
+    This is a simpler alternative to MockToolRouter, designed for
+    unit tests and offline runs where you want predictable,
+    predefined responses for specific tool calls.
+
+    Example
+    -------
+    Example usage::
+
+        mock_tools = {
+            "search_customers": [{"id": 1, "name": "Alice"}],
+            "get_product": {"id": 42, "name": "Widget", "price": 9.99}
+        }
+    """
+
+    # Type annotations for attributes
+    default_response: Any | None
+    raise_on_unknown: bool
+    mock_responses: dict[str, Any]
+    call_history: list[dict[str, Any]]
+
+    def __init__(
+        self,
+        mock_responses: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the mock tool adapter.
+
+        Args
+        ----
+            mock_responses: Dictionary mapping tool names to their predefined responses.
+            **kwargs: Configuration options (default_response, raise_on_unknown)
+        """
+        self.default_response = kwargs.get("default_response")
+        self.raise_on_unknown = kwargs.get("raise_on_unknown", False)
+        self.mock_responses = mock_responses or {}
+
+        self.call_history: list[dict[str, Any]] = []
+
+    async def acall_tool(self, tool_name: str, params: dict[str, Any]) -> Any:
+        """Call a tool and return its predefined response.
+
+        Args
+        ----
+            tool_name: Name of the tool to call
+            params: Parameters passed to the tool (logged but not used)
+
+        Returns
+        -------
+            The predefined response for the tool
+
+        Raises
+        ------
+            ValueError: If tool not found and raise_on_unknown is True
+        """
+        self.call_history.append({
+            "tool": tool_name,
+            "params": params,
+        })
+
+        if tool_name in self.mock_responses:
+            response = self.mock_responses[tool_name]
+            # If response is callable, call it with params
+            if callable(response):
+                return response(params)
+            return response
+
+        if self.raise_on_unknown:
+            available = ", ".join(self.mock_responses.keys())
+            raise ValueError(f"Unknown tool: '{tool_name}'. Available tools: {available or 'none'}")
+
+        if self.default_response is not None:
+            return self.default_response
+
+        return {
+            "status": "success",
+            "tool": tool_name,
+            "message": f"Mock response for {tool_name}",
+        }
+
+    def get_available_tools(self) -> list[str]:
+        """Get list of available tool names.
+
+        Returns
+        -------
+            List of tool names that have predefined responses
+        """
+        return list(self.mock_responses.keys())
+
+    def get_tool_schema(self, tool_name: str) -> dict[str, Any]:
+        """Get schema for a specific tool.
+
+        Since this is a mock adapter, it returns a basic schema.
+
+        Args
+        ----
+            tool_name: Name of the tool
+
+        Returns
+        -------
+            Basic schema for the tool
+        """
+        if tool_name in self.mock_responses:
+            return {
+                "name": tool_name,
+                "description": f"Mock tool: {tool_name}",
+                "parameters": {},  # Mock doesn't validate parameters
+            }
+
+        return {}
+
+    def get_all_tool_schemas(self) -> dict[str, dict[str, Any]]:
+        """Get schemas for all available tools.
+
+        Returns
+        -------
+            Dictionary mapping tool names to their basic schemas
+        """
+        return {name: self.get_tool_schema(name) for name in self.mock_responses}
+
+    # Utility methods for testing
+    def set_response(self, tool_name: str, response: Any) -> None:
+        """Set or update the response for a tool.
+
+        Args
+        ----
+            tool_name: Name of the tool
+            response: Response to return (can be callable)
+        """
+        self.mock_responses[tool_name] = response
+
+    def remove_tool(self, tool_name: str) -> None:
+        """Remove a tool from available tools.
+
+        Args
+        ----
+            tool_name: Name of the tool to remove
+        """
+        self.mock_responses.pop(tool_name, None)
+
+    def clear_history(self) -> None:
+        """Clear the call history."""
+        self.call_history.clear()
+
+    def get_call_count(self, tool_name: str | None = None) -> int:
+        """Get number of times a tool was called.
+
+        Args
+        ----
+            tool_name: Name of specific tool, or None for all tools
+
+        Returns
+        -------
+            Number of calls
+        """
+        if tool_name is None:
+            return len(self.call_history)
+
+        return sum(1 for call in self.call_history if call["tool"] == tool_name)
+
+    def get_last_call(self, tool_name: str | None = None) -> dict[str, Any] | None:
+        """Get the most recent call.
+
+        Args
+        ----
+            tool_name: Name of specific tool, or None for any tool
+
+        Returns
+        -------
+            Last call details or None if no calls
+        """
+        if not self.call_history:
+            return None
+
+        if tool_name is None:
+            return self.call_history[-1]
+
+        # Find last call for specific tool
+        for call in reversed(self.call_history):
+            if call["tool"] == tool_name:
+                return call
+
+        return None

hexdag/builtin/adapters/mock/mock_tool_router.py

@@ -0,0 +1,232 @@
+"""Mock tool router implementation for testing."""
+
+import ast
+import asyncio
+import operator
+from typing import Any
+
+from hexdag.core.exceptions import ResourceNotFoundError
+from hexdag.core.ports.tool_router import ToolRouter
+
+
+class MockToolRouter(ToolRouter):
+    """Mock implementation of ToolRouter for testing."""
+
+    # Type annotations for attributes
+    available_tools: list[str]
+    delay_seconds: float
+    raise_on_unknown_tool: bool
+    tools: dict[str, dict[str, Any]]
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize mock tool router.
+
+        Args
+        ----
+            **kwargs: Configuration options
+        """
+        self.available_tools = kwargs.get("available_tools", [])
+        self.delay_seconds = kwargs.get("delay_seconds", 0.0)
+        self.raise_on_unknown_tool = kwargs.get("raise_on_unknown_tool", False)
+
+        # Default mock tools
+        self.tools: dict[str, dict[str, Any]] = {
+            "search": {
+                "name": "search",
+                "description": "Search for information",
+                "parameters": {
+                    "query": {"type": "string", "description": "Search query"},
+                },
+            },
+            "calculate": {
+                "name": "calculate",
+                "description": "Perform calculations",
+                "parameters": {
+                    "expression": {"type": "string", "description": "Math expression"},
+                },
+            },
+            "get_weather": {
+                "name": "get_weather",
+                "description": "Get weather information",
+                "parameters": {
+                    "location": {"type": "string", "description": "Location name"},
+                },
+            },
+        }
+
+        for tool_name in self.available_tools:
+            if tool_name not in self.tools:
+                self.tools[tool_name] = {
+                    "name": tool_name,
+                    "description": f"Mock tool: {tool_name}",
+                    "parameters": {},
+                }
+
+        self.call_history: list[dict[str, Any]] = []
+
+    async def acall_tool(self, tool_name: str, params: dict[str, Any]) -> Any:
+        """Call a mock tool with parameters.
+
+        Args
+        ----
+            tool_name: The name of the tool to call
+            params: Parameters to pass to the tool
+
+        Returns
+        -------
+            Mock result based on the tool
+
+        Raises
+        ------
+        ResourceNotFoundError
+            If tool not found and raise_on_unknown_tool is True
+        """
+        if self.delay_seconds > 0:
+            await asyncio.sleep(self.delay_seconds)
+
+        self.call_history.append({
+            "tool": tool_name,
+            "params": params,
+            "timestamp": asyncio.get_event_loop().time(),
+        })
+
+        if tool_name not in self.tools:
+            if self.raise_on_unknown_tool:
+                raise ResourceNotFoundError("tool", tool_name, list(self.tools.keys()))
+            return {"error": f"Unknown tool: {tool_name}"}
+
+        if tool_name == "search":
+            query = params.get("query", "")
+            return {
+                "results": [
+                    {"title": f"Result 1 for {query}", "url": "http://example.com/1"},
+                    {"title": f"Result 2 for {query}", "url": "http://example.com/2"},
+                ]
+            }
+        if tool_name == "calculate":
+            expression = params.get("expression", "0")
+            try:
+                # Safe evaluation using ast for simple math expressions
+                # Supports: +, -, *, /, //, %, **, and numbers
+
+                ops: dict[type[ast.operator] | type[ast.unaryop], Any] = {
+                    ast.Add: operator.add,
+                    ast.Sub: operator.sub,
+                    ast.Mult: operator.mul,
+                    ast.Div: operator.truediv,
+                    ast.FloorDiv: operator.floordiv,
+                    ast.Mod: operator.mod,
+                    ast.Pow: operator.pow,
+                    ast.USub: operator.neg,
+                    ast.UAdd: operator.pos,
+                }
+
+                def safe_eval(node: ast.AST) -> float | int:
+                    if isinstance(node, ast.Constant):  # Python 3.8+
+                        val = node.value
+                        if not isinstance(val, (int, float)):
+                            raise ValueError(f"Only numeric constants are allowed, got {type(val)}")
+                        return val
+                    if isinstance(node, ast.BinOp):
+                        left = safe_eval(node.left)
+                        right = safe_eval(node.right)
+                        op_func = ops.get(type(node.op))
+                        if op_func is None:
+                            raise ValueError(f"Unsupported binary operation: {ast.dump(node)}")
+                        result = op_func(left, right)
+                        if not isinstance(result, (int, float)):
+                            raise ValueError("Operation resulted in non-numeric value")
+                        return result
+                    if isinstance(node, ast.UnaryOp):
+                        operand = safe_eval(node.operand)
+                        op_func = ops.get(type(node.op))
+                        if op_func is None:
+                            raise ValueError(f"Unsupported unary operation: {ast.dump(node)}")
+                        result = op_func(operand)
+                        if not isinstance(result, (int, float)):
+                            raise ValueError("Operation resulted in non-numeric value")
+                        return result
+                    raise ValueError(f"Unsupported operation: {ast.dump(node)}")
+
+                tree = ast.parse(expression, mode="eval")
+                result = safe_eval(tree.body)
+                return {"result": result}
+            except Exception as e:
+                return {"error": str(e)}
+        elif tool_name == "get_weather":
+            location = params.get("location", "Unknown")
+            return {
+                "location": location,
+                "temperature": 22,
+                "conditions": "Partly cloudy",
+                "humidity": 65,
+            }
+        else:
+            # Generic mock response for custom tools
+            return {
+                "tool": tool_name,
+                "status": "success",
+                "result": f"Mock result for {tool_name}",
+            }
+
+    def get_available_tools(self) -> list[str]:
+        """Get list of available mock tool names.
+
+        Returns
+        -------
+            List of tool names
+        """
+        return list(self.tools.keys())
+
+    def get_tool_schema(self, tool_name: str) -> dict[str, Any]:
+        """Get schema for a specific mock tool.
+
+        Args
+        ----
+            tool_name: Name of the tool
+
+        Returns
+        -------
+            Tool schema dictionary
+
+        Raises
+        ------
+        KeyError
+            If tool not found
+        """
+        if tool_name not in self.tools:
+            raise KeyError(f"Tool not found: {tool_name}")
+        return self.tools[tool_name].copy()
+
+    def get_all_tool_schemas(self) -> dict[str, dict[str, Any]]:
+        """Get schemas for all available mock tools.
+
+        Returns
+        -------
+            Dictionary mapping tool names to their schemas
+        """
+        return {name: schema.copy() for name, schema in self.tools.items()}
+
+    # Testing utilities
+    def reset(self) -> None:
+        """Reset call history for testing."""
+        self.call_history.clear()
+
+    def get_call_history(self) -> list[dict[str, Any]]:
+        """Get the history of tool calls for testing."""
+        return self.call_history.copy()
+
+    def add_tool(self, name: str, description: str, parameters: dict[str, Any]) -> None:
+        """Add a new mock tool for testing.
+
+        Args
+        ----
+            name: Tool name
+            description: Tool description
+            parameters: Tool parameter schema
+        """
+        self.tools[name] = {
+            "name": name,
+            "description": description,
+            "parameters": parameters,
+        }

hexdag/builtin/adapters/openai/__init__.py

@@ -0,0 +1,5 @@
+"""OpenAI adapters for hexDAG."""
+
+from hexdag.builtin.adapters.openai.openai_adapter import OpenAIAdapter
+
+__all__ = ["OpenAIAdapter"]