petfishframework 0.1.0__py3-none-any.whl

petfishframework/mcp/stdio_transport.py

@@ -0,0 +1,218 @@
+"""Real MCP stdio transport using JSON-RPC 2.0 over subprocess pipes.
+
+This module implements the client side of the Model Context Protocol stdio
+transport. It spawns a subprocess, speaks newline-delimited JSON-RPC 2.0 over
+``stdin``/``stdout``, and exposes a small synchronous API for tool discovery
+and invocation.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from typing import Any
+
+
+class StdioMCPClient:
+    """A synchronous MCP client that uses stdio JSON-RPC.
+
+    The client is designed to be used as a context manager so the subprocess is
+    always terminated on exit:
+
+        with StdioMCPClient("uvx", ["mcp-server-time"]) as client:
+            tools = client.list_tools()
+            result = client.call_tool("get_current_time", {"timezone": "UTC"})
+
+    Outside a context manager, callers must call :meth:`close` explicitly.
+    """
+
+    def __init__(
+        self,
+        command: str,
+        args: list[str],
+        env: dict[str, str] | None = None,
+    ) -> None:
+        self._command = command
+        self._args = args
+        self._env = env
+        self._process: subprocess.Popen[str] | None = None
+        self._next_id = 1
+        self._server_capabilities: dict[str, Any] = {}
+
+    def _get_env(self) -> dict[str, str] | None:
+        """Return the environment for the subprocess.
+
+        A shallow copy of ``os.environ`` is merged with any user-supplied extra
+        variables. ``PATH`` is preserved unless explicitly overridden.
+        """
+        if self._env is None:
+            return None
+        merged = dict(os.environ)
+        merged.update(self._env)
+        return merged
+
+    def _spawn(self) -> subprocess.Popen[str]:
+        """Start the MCP server subprocess with text-mode pipes.
+
+        On Windows, commands like 'npx' are .cmd files that Popen can't find
+        without shell=True. We resolve the full path via shutil.which instead.
+        """
+        import shutil
+
+        resolved = shutil.which(self._command)
+        cmd = resolved or self._command
+        return subprocess.Popen(
+            [cmd] + self._args,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            env=self._get_env(),
+        )
+
+    @property
+    def _proc(self) -> subprocess.Popen[str]:
+        """Return the active subprocess, raising if it has not been started."""
+        if self._process is None:
+            raise RuntimeError("StdioMCPClient is not initialized")
+        return self._process
+
+    def _read_message(self) -> dict[str, Any]:
+        """Read and parse one newline-delimited JSON-RPC message."""
+        proc = self._proc
+        if proc.stdout is None:
+            raise RuntimeError("subprocess stdout pipe is closed")
+        line = proc.stdout.readline()
+        if not line:
+            raise RuntimeError("subprocess closed stdout before returning a response")
+        return json.loads(line)
+
+    def _send_request(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        """Send a JSON-RPC request and return the ``result`` field."""
+        proc = self._proc
+        if proc.stdin is None:
+            raise RuntimeError("subprocess stdin pipe is closed")
+
+        request_id = self._next_id
+        self._next_id += 1
+
+        message: dict[str, Any] = {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "method": method,
+        }
+        if params is not None:
+            message["params"] = params
+
+        proc.stdin.write(json.dumps(message) + "\n")
+        proc.stdin.flush()
+
+        while True:
+            response = self._read_message()
+            # Ignore notifications / unsolicited messages while waiting for
+            # the matching response.
+            if response.get("id") == request_id:
+                break
+
+        if "error" in response:
+            error = response["error"]
+            raise RuntimeError(
+                f"JSON-RPC error for {method}: "
+                f"{error.get('code')} {error.get('message')}"
+            )
+
+        return response.get("result")
+
+    def _send_notification(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+    ) -> None:
+        """Send a JSON-RPC notification (no response expected)."""
+        proc = self._proc
+        if proc.stdin is None:
+            raise RuntimeError("subprocess stdin pipe is closed")
+
+        message: dict[str, Any] = {
+            "jsonrpc": "2.0",
+            "method": method,
+        }
+        if params is not None:
+            message["params"] = params
+
+        proc.stdin.write(json.dumps(message) + "\n")
+        proc.stdin.flush()
+
+    def initialize(self) -> None:
+        """Perform the MCP initialization handshake."""
+        if self._process is None:
+            self._process = self._spawn()
+
+        result = self._send_request(
+            "initialize",
+            {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "petfishframework", "version": "0.1.0"},
+            },
+        )
+        self._server_capabilities = (result or {}).get("capabilities", {})
+        self._send_notification("notifications/initialized")
+
+    def list_tools(self) -> list[dict[str, Any]]:
+        """Return the list of tools exposed by the server."""
+        result = self._send_request("tools/list", {})
+        if not isinstance(result, dict):
+            raise RuntimeError(f"unexpected tools/list response: {result!r}")
+        tools = result.get("tools", [])
+        if not isinstance(tools, list):
+            raise RuntimeError(f"unexpected tools/list tools field: {tools!r}")
+        return tools
+
+    def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
+        """Call a tool by name and return the raw result."""
+        return self._send_request(
+            "tools/call",
+            {"name": name, "arguments": arguments},
+        )
+
+    def close(self) -> None:
+        """Terminate the subprocess and close pipes.
+
+        This method is idempotent: repeated calls are safe.
+        """
+        proc = self._process
+        if proc is None:
+            return
+
+        self._process = None
+
+        if proc.stdin is not None:
+            try:
+                proc.stdin.close()
+            except BrokenPipeError:
+                pass
+
+        try:
+            proc.terminate()
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.wait()
+        except ProcessLookupError:
+            pass
+
+        for pipe in (proc.stdout, proc.stderr):
+            if pipe is not None:
+                try:
+                    pipe.close()
+                except BrokenPipeError:
+                    pass
+
+    def __enter__(self) -> "StdioMCPClient":
+        self.initialize()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

petfishframework/mcp/wrapper.py

@@ -0,0 +1,43 @@
+"""MCPToolWrapper — adapts an MCP-shaped tool spec to the framework Tool protocol.
+
+This is the leakage-isolation boundary: everything inside `mcp/` may speak MCP,
+but the wrapper exported here is a plain `Tool` and is indistinguishable from a
+native tool at the framework boundary.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from petfishframework.core.contracts import RiskLevel
+from petfishframework.core.types import ToolResult
+
+
+@dataclass
+class MCPToolWrapper:
+    """A Tool-protocol adapter around an MCP tool specification.
+
+    The constructor mirrors the fields expected by the `Tool` protocol. The
+    bundled `call_fn` is the only MCP-specific artifact and is not part of the
+    public Tool surface.
+    """
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    call_fn: Callable[[dict[str, Any]], Any] = field(compare=False, repr=False)
+    risk_level: RiskLevel = RiskLevel.LOW
+    capabilities: tuple[str, ...] = ()
+
+    def execute(self, args: dict[str, Any]) -> ToolResult:
+        """Invoke the wrapped MCP call and translate the outcome.
+
+        A successful call becomes ``ToolResult(value=...)``. Any exception is
+        caught and returned as ``ToolResult(error=...)`` so callers never need
+        to know whether the underlying implementation is native or MCP.
+        """
+        try:
+            value = self.call_fn(args)
+        except Exception as exc:  # noqa: BLE001
+            return ToolResult(error=str(exc))
+        return ToolResult(value=value)

petfishframework/models/__init__.py

@@ -0,0 +1,14 @@
+"""Model adapters — concrete implementations of the ModelAdapter protocol.
+
+Provides ``FakeModel`` for deterministic testing, ``OpenAIModel`` for live
+OpenAI API calls, and ``AnthropicModel`` for Anthropic's Messages API.
+All provider dependencies are imported lazily at runtime so the framework core
+remains optional-dependency free.
+"""
+from __future__ import annotations
+
+from .anthropic import AnthropicModel
+from .fake import AsyncFakeModel, FakeModel
+from .openai import OpenAIModel
+
+__all__ = ["AnthropicModel", "AsyncFakeModel", "FakeModel", "OpenAIModel"]

petfishframework/models/anthropic.py

@@ -0,0 +1,194 @@
+"""Anthropic (Claude) model adapter for the ModelAdapter protocol.
+
+The ``anthropic`` package is imported lazily inside ``AnthropicModel.__init__`` so
+framework core remains free of the optional Anthropic dependency at import time.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from petfishframework.core.contracts import ModelAdapter
+from petfishframework.core.types import (
+    Message,
+    ModelRequest,
+    ModelResponse,
+    Role,
+    ToolCall,
+    Usage,
+)
+
+
+class AnthropicModel(ModelAdapter):
+    """Adapter that queries Anthropic's Messages API."""
+
+    def __init__(
+        self,
+        model: str = "claude-sonnet-4-5-20250514",
+        api_key: str | None = None,
+        base_url: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Create an Anthropic adapter with a lazily imported Anthropic client.
+
+        Args:
+            model: The Anthropic model name (e.g. ``claude-sonnet-4-5-20250514``).
+            api_key: Anthropic API key. If not provided, ``ANTHROPIC_API_KEY`` is used.
+            base_url: Optional custom base URL for the Anthropic API.
+            **kwargs: Additional keyword arguments forwarded to ``anthropic.Anthropic``.
+
+        Raises:
+            ImportError: If the ``anthropic`` package is not installed.
+            ValueError: If no API key is available.
+        """
+        try:
+            import anthropic
+            from anthropic import Anthropic
+        except ImportError as exc:
+            raise ImportError(
+                "The 'anthropic' package is required to use AnthropicModel. "
+                "Install it with 'pip install petfishframework[anthropic]'."
+            ) from exc
+
+        resolved_key = api_key if api_key is not None else os.environ.get("ANTHROPIC_API_KEY")
+        if resolved_key is None:
+            raise ValueError(
+                "AnthropicModel requires an api_key or the ANTHROPIC_API_KEY environment variable."
+            )
+
+        self.name = model
+        self._model = model
+        self._anthropic = anthropic
+        self._client = Anthropic(api_key=resolved_key, base_url=base_url, **kwargs)
+
+    def query(self, request: ModelRequest) -> ModelResponse:
+        """Send a Messages API request and convert the response."""
+        system, messages = self._build_messages(request.messages)
+        tools = self._build_tools(request.tools)
+
+        max_tokens = request.max_tokens if request.max_tokens is not None else 4096
+        params: dict[str, Any] = {
+            "model": self._model,
+            "max_tokens": max_tokens,
+            "messages": messages,
+            "temperature": request.temperature,
+        }
+        if system:
+            params["system"] = system
+        if tools:
+            params["tools"] = tools
+
+        try:
+            response = self._client.messages.create(**params)
+        except self._anthropic.APIError as exc:
+            raise RuntimeError(f"Anthropic API error: {exc}") from exc
+
+        return self._build_response(response)
+
+    def _build_messages(
+        self,
+        messages: tuple[Message, ...],
+    ) -> tuple[str | None, list[dict[str, Any]]]:
+        """Convert framework messages to Anthropic Messages API format.
+
+        Anthropic requires system messages to be passed in a separate ``system``
+        parameter and supports only ``user`` and ``assistant`` roles in the
+        messages list. Tool result messages are emitted as ``tool_result``
+        content blocks inside a ``user`` message.
+        """
+        system_parts: list[str] = []
+        anthropic_messages: list[dict[str, Any]] = []
+
+        for msg in messages:
+            if msg.role is Role.SYSTEM:
+                system_parts.append(msg.content)
+                continue
+
+            if msg.role is Role.TOOL:
+                entry: dict[str, Any] = {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": msg.tool_call_id or "",
+                            "content": msg.content,
+                        },
+                    ],
+                }
+                anthropic_messages.append(entry)
+                continue
+
+            if msg.role is Role.ASSISTANT and msg.tool_calls:
+                content_blocks: list[dict[str, Any]] = []
+                if msg.content:
+                    content_blocks.append({"type": "text", "text": msg.content})
+                for tool_call in msg.tool_calls:
+                    content_blocks.append(
+                        {
+                            "type": "tool_use",
+                            "id": tool_call.id,
+                            "name": tool_call.name,
+                            "input": tool_call.arguments,
+                        }
+                    )
+                anthropic_messages.append({"role": "assistant", "content": content_blocks})
+                continue
+
+            anthropic_messages.append(
+                {"role": msg.role.value, "content": msg.content}
+            )
+
+        system = "\n".join(system_parts) if system_parts else None
+        return system, anthropic_messages
+
+    def _build_tools(self, tool_names: tuple[str, ...]) -> list[dict[str, Any]] | None:
+        """Convert tool names to Anthropic tool definitions."""
+        if not tool_names:
+            return None
+        return [
+            {
+                "name": name,
+                "description": "",
+                "input_schema": {"type": "object", "properties": {}},
+            }
+            for name in tool_names
+        ]
+
+    def _usage_from_response(self, response: Any) -> Usage:
+        """Extract token usage from an Anthropic response."""
+        usage = response.usage
+        return Usage(
+            input_tokens=getattr(usage, "input_tokens", 0),
+            output_tokens=getattr(usage, "output_tokens", 0),
+            total_tokens=getattr(usage, "input_tokens", 0) + getattr(usage, "output_tokens", 0),
+        )
+
+    def _build_response(self, response: Any) -> ModelResponse:
+        """Convert an Anthropic Messages API response to a ModelResponse."""
+        text_parts: list[str] = []
+        tool_calls: list[ToolCall] = []
+
+        for block in response.content:
+            block_type = getattr(block, "type", None)
+            if block_type == "text":
+                text_parts.append(getattr(block, "text", ""))
+            elif block_type == "tool_use":
+                tool_input = getattr(block, "input", {})
+                if isinstance(tool_input, str):
+                    tool_input = json.loads(tool_input)
+                tool_calls.append(
+                    ToolCall(
+                        id=getattr(block, "id", ""),
+                        name=getattr(block, "name", ""),
+                        arguments=tool_input,
+                    )
+                )
+
+        return ModelResponse(
+            content="".join(text_parts),
+            tool_calls=tuple(tool_calls),
+            usage=self._usage_from_response(response),
+            finish_reason=response.stop_reason or "stop",
+            raw=response,
+        )

petfishframework/models/fake.py

@@ -0,0 +1,202 @@
+"""Fake model adapter for deterministic tests and offline development."""
+from __future__ import annotations
+
+import re
+import uuid
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from typing import Any
+
+from petfishframework.core.contracts import ModelAdapter
+from petfishframework.core.types import ModelRequest, ModelResponse, ToolCall, Usage
+
+
+@dataclass
+class FakeModel(ModelAdapter):
+    """A scripted model that replays pre-defined responses in order.
+
+    Useful for unit tests: you can script a tool call followed by a final answer
+    and verify the end-to-end agent behavior without network calls.
+    """
+
+    responses: tuple[ModelResponse, ...] = ()
+    name: str = "fake"
+    _index: int = field(default=0, repr=False)
+    _calls: int = field(default=0, repr=False)
+    _requests: list[ModelRequest] = field(default_factory=list, repr=False)
+
+    def query(self, request: ModelRequest) -> ModelResponse:
+        """Return the next scripted response, or the last one available."""
+        self._requests.append(request)
+        if not self.responses:
+            return ModelResponse(content="", usage=self._per_call_usage())
+
+        if self._index >= len(self.responses):
+            response = self.responses[-1]
+        else:
+            response = self.responses[self._index]
+            self._index += 1
+
+        self._calls += 1
+        # If the scripted response did not set usage, apply deterministic usage.
+        usage = response.usage if response.usage.total_tokens > 0 else self._per_call_usage()
+        # Ensure every returned response carries deterministic usage.
+        return ModelResponse(
+            content=response.content,
+            tool_calls=response.tool_calls,
+            usage=usage,
+            finish_reason=response.finish_reason,
+            raw=response.raw,
+        )
+
+    def query_stream(self, request: ModelRequest) -> Iterator[str]:
+        """Return the scripted response content as a stream of text chunks.
+
+        Chunks are contiguous words or whitespace slices, so joining them
+        reproduces the exact response content from :meth:`query`.
+        """
+        response = self.query(request)
+        return (match.group(0) for match in re.finditer(r"\S+|\s+", response.content))
+
+    def _per_call_usage(self) -> Usage:
+        """Deterministic per-call usage for testing budget enforcement."""
+        return Usage(input_tokens=10, output_tokens=20, total_tokens=30)
+
+    @property
+    def call_count(self) -> int:
+        """Number of times query() has been invoked."""
+        return self._calls
+
+    @property
+    def requests(self) -> tuple[ModelRequest, ...]:
+        """All model requests received by query(), in order."""
+        return tuple(self._requests)
+
+    @classmethod
+    def script_tool_then_answer(
+        cls,
+        tool_name: str,
+        tool_args: dict[str, Any],
+        final_answer: str,
+    ) -> "FakeModel":
+        """Create a two-response script: one tool call, then a final answer."""
+        return cls(
+            responses=(
+                ModelResponse(
+                    content=f"I will use the {tool_name} tool.",
+                    tool_calls=(
+                        ToolCall(
+                            id=uuid.uuid4().hex[:12],
+                            name=tool_name,
+                            arguments=tool_args,
+                        ),
+                    ),
+                ),
+                ModelResponse(content=final_answer),
+            )
+        )
+
+    @classmethod
+    def lats_scenario(
+        cls,
+        tool_name: str = "calculator",
+        candidate_groups: tuple[tuple[dict[str, Any], ...], ...] = (
+            ({"expression": "2+3"}, {"expression": "2*4"}, {"expression": "3+4"}),
+            ({"expression": "5*4"}, {"expression": "5+4"}, {"expression": "5-4"}),
+        ),
+        score_groups: tuple[tuple[int | float, ...], ...] = (
+            (9, 3, 4),
+            (9, 4, 2),
+        ),
+        final_answer: str = "The answer is 20.",
+    ) -> "FakeModel":
+        """Create a FakeModel scripted for the LATS search scenario.
+
+        The returned model alternates: candidate generation responses
+        (each carrying multiple tool_calls), value-scoring responses
+        (one per candidate), and a final plain-text answer.
+        """
+        responses: list[ModelResponse] = []
+        for candidates, scores in zip(candidate_groups, score_groups, strict=True):
+            tool_calls = tuple(
+                ToolCall(
+                    id=uuid.uuid4().hex[:12],
+                    name=tool_name,
+                    arguments=args,
+                )
+                for args in candidates
+            )
+            responses.append(
+                ModelResponse(
+                    content="Here are candidate next actions.",
+                    tool_calls=tool_calls,
+                )
+            )
+            for score in scores:
+                responses.append(ModelResponse(content=f"Score: {score}"))
+        responses.append(ModelResponse(content=final_answer))
+        return cls(responses=tuple(responses))
+
+    @classmethod
+    def llm_plus_p_scenario(
+        cls,
+        translate_content: str = '{"start": "A", "goal": "C", "edges": [["A", "B"], ["B", "C"]]}',
+        backtranslate_content: str = "The shortest path is A -> B -> C.",
+    ) -> "FakeModel":
+        """Create a FakeModel scripted for the LLM+P three-phase scenario.
+
+        Response 1: structured problem extraction (used as planner input).
+        Response 2: natural-language answer derived from the planner output.
+        """
+        return cls(
+            responses=(
+                ModelResponse(content=translate_content),
+                ModelResponse(content=backtranslate_content),
+            )
+        )
+
+
+@dataclass
+class AsyncFakeModel(ModelAdapter):
+    """Async scripted model adapter for deterministic async tests.
+
+    Wraps a sync FakeModel so all scripting utilities are reused; only the
+    query() coroutine wrapper is added. This makes AsyncFakeModel compatible
+    with RuntimeEnvironment.query_model_async() via
+    ``asyncio.iscoroutinefunction()`` detection.
+    """
+
+    _inner: FakeModel = field(default_factory=FakeModel)
+    name: str = "async_fake"
+
+    def query(self, request: ModelRequest) -> ModelResponse:
+        """Return the next scripted response (synchronous protocol hook)."""
+        return self._inner.query(request)
+
+    async def query_async(self, request: ModelRequest) -> ModelResponse:
+        """Return the next scripted response asynchronously."""
+        return self._inner.query(request)
+
+    def query_stream(self, request: ModelRequest) -> Iterator[str]:
+        """Return the scripted response content as a synchronous text stream."""
+        return self._inner.query_stream(request)
+
+    @property
+    def call_count(self) -> int:
+        """Number of times query() has been invoked on the underlying model."""
+        return self._inner.call_count
+
+    @property
+    def requests(self) -> tuple[ModelRequest, ...]:
+        """All model requests received by the underlying query()."""
+        return tuple(self._inner.requests)
+
+    @classmethod
+    def script_tool_then_answer(
+        cls,
+        tool_name: str,
+        tool_args: dict[str, Any],
+        final_answer: str,
+    ) -> "AsyncFakeModel":
+        """Create a two-response async script: one tool call, then a final answer."""
+        return cls(_inner=FakeModel.script_tool_then_answer(tool_name, tool_args, final_answer))