velophex 0.2.0__py3-none-any.whl

velophex/agents/testing.py

@@ -0,0 +1,249 @@
+"""Fakes for testing an agent without a model, an Orchestrator or a Robot.
+
+* :class:`FakeChatServer` - a real local HTTP server in the shape of the LLM gateway's
+  ``POST .../chat/completions`` (OpenAI chat completions, non-streaming), answering from a
+  script and recording every request;
+* :class:`FakeTools` - tool calls answered by plain functions, approvals by a table;
+* :class:`RecordingTracer` - keeps the spans a run produced.
+
+    >>> from velophex import agents
+    >>> from velophex.agents.testing import FakeChatServer, FakeTools, RecordingTracer
+    >>>
+    >>> with FakeChatServer(FakeChatServer.text('{"answer": "42"}')) as server:
+    ...     output = agents.run(definition, {}, chat=server.endpoint, tools=FakeTools(), tracer=RecordingTracer())
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+from velophex.agents._loop import ChatEndpoint
+from velophex.agents._tools import ToolOutcome
+from velophex.contracts.agents import AgentTool
+
+__all__ = ["FakeChatServer", "FakeTools", "RecordingTracer", "ToolCall"]
+
+
+class FakeChatServer:
+    """A scripted, OpenAI-shaped chat completions endpoint on ``127.0.0.1``.
+
+    Each reply is a message (from :meth:`text` or :meth:`tool_calls`) or a refusal (from
+    :meth:`refusal`); replies are used in order and a request past the script gets a 500.
+    """
+
+    def __init__(
+        self,
+        *replies: dict[str, Any] | tuple[int, dict[str, Any]],
+        routes: dict[str, Any] | None = None,
+    ) -> None:
+        self.replies: list[dict[str, Any] | tuple[int, dict[str, Any]]] = list(replies)
+        self.requests: list[dict[str, Any]] = []
+        self.headers: list[dict[str, str]] = []
+        #: Other Runtime API answers, by ``"<METHOD> <path under /api/v1/runtime>"``.
+        self.routes: dict[str, Any] = dict(routes or {})
+        #: Spans posted to ``traces/spans``, which is always answered.
+        self.spans: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._server: ThreadingHTTPServer | None = None
+
+    # ---------------------------------------------------------------- replies
+
+    @staticmethod
+    def text(content: str, *, prompt_tokens: int = 10, completion_tokens: int = 5) -> dict[str, Any]:
+        """An assistant message with text and no tool call."""
+        return {
+            "message": {"role": "assistant", "content": content},
+            "finish_reason": "stop",
+            "usage": (prompt_tokens, completion_tokens),
+        }
+
+    @staticmethod
+    def tool_calls(
+        *calls: tuple[str, dict[str, Any] | str], prompt_tokens: int = 10, completion_tokens: int = 5
+    ) -> dict[str, Any]:
+        """An assistant message calling tools; arguments given as a string are sent as is."""
+        return {
+            "message": {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": f"call_{uuid.uuid4().hex[:12]}",
+                        "type": "function",
+                        "function": {
+                            "name": name,
+                            "arguments": arguments if isinstance(arguments, str) else json.dumps(arguments),
+                        },
+                    }
+                    for name, arguments in calls
+                ],
+            },
+            "finish_reason": "tool_calls",
+            "usage": (prompt_tokens, completion_tokens),
+        }
+
+    @staticmethod
+    def refusal(status: int, code: str, **problem: Any) -> tuple[int, dict[str, Any]]:
+        """A gateway refusal: RFC 9457 problem details with ``code``."""
+        return status, {"title": code, "status": status, "code": code, **problem}
+
+    # ---------------------------------------------------------------- server
+
+    @property
+    def base_url(self) -> str:
+        """The gateway base the client appends ``/chat/completions`` to."""
+        assert self._server is not None, "use the server as a context manager"
+        return f"http://127.0.0.1:{self._server.server_address[1]}/api/v1/runtime/ai"
+
+    @property
+    def runtime_url(self) -> str:
+        """The Runtime API base, for a ``start`` context's ``orchestratorUrl``."""
+        return self.base_url.removesuffix("/ai")
+
+    @property
+    def endpoint(self) -> ChatEndpoint:
+        """A :class:`ChatEndpoint` for :func:`velophex.agents.run`."""
+        return ChatEndpoint(self.base_url, "vpx_rt_test")
+
+    def __enter__(self) -> FakeChatServer:
+        fake = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_GET(self) -> None:
+                self._route("GET", None)
+
+            def do_POST(self) -> None:
+                length = int(self.headers.get("Content-Length") or 0)
+                body = json.loads(self.rfile.read(length) or b"{}")
+
+                if not self.path.endswith("/chat/completions"):
+                    self._route("POST", body)
+                    return
+
+                with fake._lock:
+                    fake.requests.append(body)
+                    fake.headers.append({name.lower(): value for name, value in self.headers.items()})
+                    reply = fake.replies.pop(0) if fake.replies else (500, {"title": "No scripted reply left."})
+
+                if isinstance(reply, tuple):
+                    self._send(reply[0], reply[1], "application/problem+json")
+                    return
+
+                prompt, completion = reply["usage"]
+                self._send(
+                    200,
+                    {
+                        "id": f"chatcmpl-{uuid.uuid4().hex[:12]}",
+                        "object": "chat.completion",
+                        "created": 0,
+                        "model": body.get("model"),
+                        "choices": [{"index": 0, "message": reply["message"], "finish_reason": reply["finish_reason"]}],
+                        "usage": {
+                            "prompt_tokens": prompt,
+                            "completion_tokens": completion,
+                            "total_tokens": prompt + completion,
+                        },
+                    },
+                    "application/json",
+                )
+
+            def _route(self, method: str, body: Any) -> None:
+                path = self.path.split("?", 1)[0].removeprefix("/api/v1/runtime")
+
+                if method == "POST" and path == "/traces/spans":
+                    with fake._lock:
+                        fake.spans.extend(body.get("spans") or [])
+
+                    self._send(202, {"status": "accepted"}, "application/json")
+                    return
+
+                answer = fake.routes.get(f"{method} {path}")
+
+                if answer is None:
+                    self._send(404, {"title": f"No route for {method} {path}."}, "application/problem+json")
+                else:
+                    self._send(200, answer, "application/json")
+
+            def _send(self, status: int, payload: dict[str, Any], content_type: str) -> None:
+                data = json.dumps(payload).encode()
+                self.send_response(status)
+                self.send_header("Content-Type", content_type)
+                self.send_header("Content-Length", str(len(data)))
+                self.end_headers()
+                self.wfile.write(data)
+
+            def log_message(self, format: str, *args: Any) -> None:
+                pass
+
+        self._server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        threading.Thread(target=self._server.serve_forever, daemon=True).start()
+        return self
+
+    def __exit__(self, *exception: object) -> None:
+        if self._server is not None:
+            self._server.shutdown()
+            self._server.server_close()
+
+
+@dataclass(frozen=True, slots=True)
+class ToolCall:
+    """One call :class:`FakeTools` received."""
+
+    name: str
+    arguments: dict[str, Any]
+    idempotency_key: str
+    timeout_seconds: int
+
+
+@dataclass
+class FakeTools:
+    """Tool calls answered by ``handlers[name](arguments)``; approvals by ``approvals[name]``.
+
+    A handler returns the tool's data, or a :class:`ToolOutcome` to answer a failure or an
+    unknown outcome; an exception it raises becomes a failed call. Approvals default to
+    ``approved``.
+    """
+
+    handlers: dict[str, Callable[[dict[str, Any]], Any]] = field(default_factory=dict)
+    approvals: dict[str, str] = field(default_factory=dict)
+    calls: list[ToolCall] = field(default_factory=list)
+    approval_requests: list[ToolCall] = field(default_factory=list)
+
+    def call(
+        self, tool: AgentTool, arguments: dict[str, Any], *, idempotency_key: str, timeout_seconds: int
+    ) -> ToolOutcome:
+        """Answer from the handler."""
+        self.calls.append(ToolCall(tool.name, arguments, idempotency_key, timeout_seconds))
+        handler = self.handlers.get(tool.name)
+
+        if handler is None:
+            return ToolOutcome(ok=False, error=f"FakeTools has no handler for '{tool.name}'.")
+
+        try:
+            result = handler(arguments)
+        except Exception as error:
+            return ToolOutcome(ok=False, error=str(error))
+
+        return result if isinstance(result, ToolOutcome) else ToolOutcome(ok=True, data=result)
+
+    def approve(self, tool: AgentTool, arguments: dict[str, Any], *, idempotency_key: str, timeout_seconds: int) -> str:
+        """Answer from the approval table."""
+        self.approval_requests.append(ToolCall(tool.name, arguments, idempotency_key, timeout_seconds))
+        return self.approvals.get(tool.name, "approved")
+
+
+@dataclass
+class RecordingTracer:
+    """Keeps every span in :attr:`spans`."""
+
+    spans: list[dict[str, Any]] = field(default_factory=list)
+
+    def record(self, span: dict[str, Any]) -> None:
+        """Keep the span."""
+        self.spans.append(span)

velophex/cli/__init__.py

@@ -0,0 +1,5 @@
+"""The ``velophex`` command line: ``init``, ``run``, ``pack`` and ``publish``."""
+
+from velophex.cli.main import app, main
+
+__all__ = ["app", "main"]