toolrank 0.1.0__py3-none-any.whl

toolrank/__init__.py

@@ -0,0 +1,20 @@
+"""Toolrank: tool retrieval for LLM agents with hundreds of tools.
+
+The package is organised as ports and adapters:
+
+* ``toolrank.domain``       - plain dataclasses (Tool, Query, RankedList, EvalReport).
+* ``toolrank.ports``        - Protocols every adapter implements (Scorer, TextEncoder, VectorIndex, ...).
+* ``toolrank.adapters``     - BM25, dense (any OpenAI-compatible embeddings endpoint), heads, indexes,
+  the MCP proxy and REST API, MCP and OpenAPI backends.
+* ``toolrank.ingest``       - MCP servers and OpenAPI specs -> an ingest dir (``tools.jsonl``).
+* ``toolrank.retriever``    - query-time retrieval over an ingest dir, shared by search and serve.
+* ``toolrank.client``       - a standard-library client for ``toolrank serve``'s REST API.
+* ``toolrank.integrations`` - Claude's and OpenAI's tool search, LangGraph, LlamaIndex, LiteLLM.
+* ``toolrank.datasets``     - benchmark converters and the on-disk JSONL format.
+* ``toolrank.eval``         - trec_eval-compatible metrics and the benchmark runner.
+"""
+
+from toolrank.domain import EvalReport, Query, RankedList, Tool
+
+__all__ = ["EvalReport", "Query", "RankedList", "Tool", "__version__"]
+__version__ = "0.1.0"

toolrank/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Adapters: concrete Scorers and TextEncoders behind the ports in ``toolrank.ports``."""
+
+from toolrank.adapters.bm25 import BM25Scorer
+from toolrank.adapters.dense import DenseScorer
+from toolrank.adapters.embeddings_api import EmbeddingCache, OpenAIEmbeddings
+
+__all__ = ["BM25Scorer", "DenseScorer", "EmbeddingCache", "OpenAIEmbeddings"]

toolrank/adapters/backends.py

@@ -0,0 +1,426 @@
+"""Where ``call_tool`` goes: MCP servers (long-lived client sessions) and OpenAPI operations (HTTP).
+
+MCP: one ``MCPBackend`` per configured server. Its task, started on the first call inside the
+proxy's task group (``Backends.running()``), owns the ``mcp.Client``: connect (bounded by
+``connect_timeout``), list the tools once, stay connected, and after a failure wait for the next
+caller before reconnecting (with backoff). Callers use the session directly with
+``read_timeout_seconds``, so a timed-out call stops there, and a call in flight when the backend
+failed is never resent. Every failure becomes an ``isError`` result naming the server; the
+backend's ``serverInfo`` stamp is removed so clients see the proxy's.
+
+OpenAPI: ``OpenAPIExecutor`` turns a tool's ``doc["http"]`` routing and the agent's arguments into
+one HTTP request (``httpx2``): path parameters percent-encoded, query parameters by their OpenAPI
+style (``form`` explode → repeated keys, ``deepObject`` → ``k[sub]=v`` / ``k[0]=v``), booleans as
+``true``/``false``, JSON bodies, and form bodies nested with brackets the way Stripe reads them.
+Safety: only GET and HEAD unless ``allow_write``; configured headers (credentials) go only to the
+configured base URL (a path that does not start with ``/`` is refused: appended to the base URL it
+could name another host; and the composed URL must have the base URL's origin); redirects are not followed; responses are cut at ``max_chars``. Multipart,
+header and cookie parameters are refused for now.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import tempfile
+import urllib.parse
+from collections.abc import AsyncIterator, Sequence
+from contextlib import AsyncExitStack, asynccontextmanager
+from dataclasses import dataclass
+from typing import Any
+
+from toolrank.domain import Tool
+from toolrank.ingest.mcp import OpenAPIBackend, ServerConfig
+
+SAFE_METHODS = ("GET", "HEAD")
+MAX_RESPONSE_CHARS = 25_000
+
+
+@dataclass(frozen=True)
+class CallOutcome:
+    result: Any  # mcp_types.CallToolResult
+    outcome: str  # one of toolrank.usage.OUTCOMES
+    http_status: int | None = None
+
+
+class Refused(ValueError):
+    """The proxy will not make this call (policy or an unsupported shape), whatever the backend says."""
+
+
+def error_result(text: str) -> Any:
+    from mcp_types import CallToolResult, TextContent
+
+    return CallToolResult(content=[TextContent(type="text", text=text)], is_error=True)
+
+
+def _strip_server_info(result: Any) -> Any:
+    from mcp_types import SERVER_INFO_META_KEY
+
+    meta = getattr(result, "meta", None)
+    if isinstance(meta, dict) and SERVER_INFO_META_KEY in meta:
+        rest = {k: v for k, v in meta.items() if k != SERVER_INFO_META_KEY}
+        return result.model_copy(update={"meta": rest or None})
+    return result
+
+
+# -- MCP --------------------------------------------------------------------------------------
+class MCPBackend:
+    """One MCP server behind the proxy. State changes happen under ``_cond``: callers raise
+    ``_want`` and wait until a connection exists or an attempt that started after them failed; the
+    worker connects when wanted. A caller that sees the transport break sets that connection's own
+    ``broken`` event, so a late failure never tears down a newer connection."""
+
+    def __init__(self, cfg: ServerConfig, *, connect_timeout: float = 60.0):
+        self.cfg, self.connect_timeout = cfg, connect_timeout
+        self._session: tuple[Any, Any] | None = None  # (client, its broken event)
+        self._error: str | None = None
+        self._delay = 0.0
+        self._want = False
+        self._attempt = 0  # attempts started
+        self._failed = 0  # the latest attempt that failed
+        self._started = False
+
+    def _start(self, tg: Any) -> None:
+        if self._started:
+            return
+        import anyio
+
+        self._cond = anyio.Condition()
+        self._started = True
+        tg.start_soon(self._run, name=f"toolrank-backend-{self.cfg.name}")
+
+    async def _run(self) -> None:
+        import shutil
+
+        import anyio
+        import httpx2
+        from mcp import Client
+
+        from toolrank.adapters.mcp_client import _reason, _stderr_tail, _transport, list_all
+
+        while True:
+            async with self._cond:
+                while not self._want:
+                    await self._cond.wait()
+                self._want = False
+                self._attempt += 1
+                attempt = self._attempt
+            if self._delay:
+                await anyio.sleep(self._delay)
+            failure = None
+            broken = anyio.Event()
+            with tempfile.TemporaryFile("w+", encoding="utf-8") as errlog:
+                try:
+                    if self.cfg.transport == "stdio" and shutil.which(self.cfg.command) is None:
+                        raise FileNotFoundError(f"command not found: {self.cfg.command}")
+                    # the deadline bounds the connection only; it is lifted once connected
+                    with anyio.CancelScope(deadline=anyio.current_time() + self.connect_timeout) as scope:
+                        async with AsyncExitStack() as stack:
+                            http = None
+                            if self.cfg.transport == "http":
+                                http = await stack.enter_async_context(
+                                    httpx2.AsyncClient(
+                                        headers=dict(self.cfg.headers), timeout=httpx2.Timeout(30, read=None)
+                                    )
+                                )
+                            client = await stack.enter_async_context(
+                                Client(_transport(self.cfg, errlog, http), cache=None)
+                            )
+                            await list_all(client)
+                            scope.deadline = math.inf
+                            async with self._cond:
+                                self._session, self._error, self._delay = (client, broken), None, 0.0
+                                self._cond.notify_all()
+                            await broken.wait()
+                    if scope.cancelled_caught:
+                        failure = _reason(self.cfg, TimeoutError(), self.connect_timeout) + _stderr_tail(
+                            errlog
+                        )
+                except FileNotFoundError as e:
+                    failure = f"{self.cfg.name}: {e}"
+                except Exception as e:  # the SDK raises exception groups, transport and validation errors
+                    failure = _reason(self.cfg, e, self.connect_timeout) + _stderr_tail(errlog)
+            async with self._cond:
+                self._session = None
+                if failure:
+                    self._error, self._failed = failure, attempt
+                    self._delay = min(max(self._delay * 2, 1.0), 30.0)
+                self._cond.notify_all()
+
+    async def _connection(self) -> tuple[Any, Any] | None:
+        import anyio
+
+        session = self._session
+        if session is not None:
+            return session
+        async with self._cond:
+            self._want = True
+            first = self._attempt + 1  # the next attempt to start is (also) ours
+            self._cond.notify_all()
+            with anyio.move_on_after(self.connect_timeout + self._delay + 5):
+                while self._session is None and self._failed < first:
+                    await self._cond.wait()
+            return self._session
+
+    async def call(self, tg: Any, name: str, arguments: dict[str, Any], *, timeout: float) -> CallOutcome:
+        from mcp.shared.exceptions import MCPError
+        from mcp_types import CONNECTION_CLOSED, REQUEST_TIMEOUT
+
+        self._start(tg)
+        server = self.cfg.name
+        session = await self._connection()
+        if session is None:
+            return CallOutcome(error_result(self._error or f"{server}: not connected yet"), "protocol_error")
+        client, broken = session
+        try:
+            result = await client.call_tool(name, arguments, read_timeout_seconds=timeout)
+        except MCPError as e:
+            if e.code == REQUEST_TIMEOUT:
+                return CallOutcome(
+                    error_result(f"{server}: {name} did not answer within {timeout:g} s"), "timeout"
+                )
+            if e.code == CONNECTION_CLOSED:
+                self._drop(session)
+                return CallOutcome(
+                    error_result(f"{server}: the connection closed during the call; it was not retried"),
+                    "protocol_error",
+                )
+            return CallOutcome(error_result(f"{server}: {e.message}"), "protocol_error")
+        except (RuntimeError, ValueError) as e:  # output-schema checks, validation: the session is fine
+            return CallOutcome(error_result(f"{server}: {type(e).__name__}: {e}"), "protocol_error")
+        except Exception as e:  # a broken transport: reconnect on the next call
+            self._drop(session)
+            return CallOutcome(
+                error_result(f"{server}: {type(e).__name__}: {e}; the call was not retried"), "protocol_error"
+            )
+        return CallOutcome(_strip_server_info(result), "tool_error" if result.is_error else "ok")
+
+    def _drop(self, session: tuple[Any, Any]) -> None:
+        """Retire ``session`` (only if it is still current); the next caller reconnects."""
+        if self._session is session:
+            self._session = None
+        session[1].set()
+
+
+# -- OpenAPI ----------------------------------------------------------------------------------
+def _scalar(v: Any) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    return "" if v is None else str(v)
+
+
+def _bracket(prefix: str, value: Any) -> list[tuple[str, str]]:
+    """``{"a": {"b": 1}, "c": [2]}`` -> ``a[b]=1``, ``c[0]=2`` (Stripe's nesting, deepObject)."""
+    if isinstance(value, dict):
+        return [p for k, v in value.items() for p in _bracket(f"{prefix}[{k}]", v)]
+    if isinstance(value, list):
+        return [p for i, v in enumerate(value) for p in _bracket(f"{prefix}[{i}]", v)]
+    return [(prefix, _scalar(value))]
+
+
+def _query_pairs(name: str, value: Any, style: str, explode: bool) -> list[tuple[str, str]]:
+    if style == "deepObject":
+        return _bracket(name, value)
+    if isinstance(value, list):
+        if style == "form" and explode:
+            return [(name, _scalar(v)) for v in value]
+        sep = {"spaceDelimited": " ", "pipeDelimited": "|"}.get(style, ",")
+        return [(name, sep.join(_scalar(v) for v in value))]
+    if isinstance(value, dict):
+        if style == "form" and explode:
+            return [(str(k), _scalar(v)) for k, v in value.items()]
+        return [(name, ",".join(f"{k},{_scalar(v)}" for k, v in value.items()))]
+    return [(name, _scalar(value))]
+
+
+def same_origin(url: str, base: str) -> bool:
+    """Whether a request to ``url`` goes to ``base``'s scheme, host and port, as the HTTP client
+    reads the two: the guard that keeps a source's headers (credentials) on its own base URL."""
+    import httpx2
+
+    try:
+        a, b = httpx2.URL(url), httpx2.URL(base)
+    except httpx2.InvalidURL:
+        return False
+    return (a.scheme, a.host, a.port) == (b.scheme, b.host, b.port)
+
+
+class OpenAPIExecutor:
+    def __init__(
+        self,
+        configs: dict[str, OpenAPIBackend],
+        *,
+        allow_write: bool = False,
+        timeout: float = 60.0,
+        transport: Any = None,
+        max_chars: int = MAX_RESPONSE_CHARS,
+    ):
+        self.configs, self.allow_write, self.timeout = configs, allow_write, timeout
+        self.transport, self.max_chars = transport, max_chars
+        self._client: Any = None
+
+    def build(self, tool: Tool, arguments: dict[str, Any] | None) -> dict[str, Any]:
+        """The request (``httpx2.AsyncClient.request`` keyword arguments) for one call; raises
+        ``Refused`` for policy and unsupported shapes, ``ValueError`` for bad arguments."""
+        http = tool.doc.get("http") or {}
+        method = str(http.get("method") or "GET").upper()
+        source = tool.category
+        if method not in SAFE_METHODS and not self.allow_write:
+            raise Refused(
+                f"{tool.id} is a {method} operation; this proxy only sends GET and HEAD "
+                "(start it with --allow-write to allow changes)"
+            )
+        cfg = self.configs.get(source)
+        base = cfg.base_url if cfg is not None and cfg.base_url else str(http.get("base_url") or "")
+        if not re.match(r"https?://", base):
+            raise Refused(
+                f"{source}: no absolute base URL ({base!r}); set openapi.{source}.base_url in the config"
+            )
+        headers = dict(cfg.headers) if cfg is not None and cfg.base_url else {}
+        spec = http.get("args") or {}
+        path = str(http.get("path") or "")
+        if not path.startswith("/"):  # "@host/x" or ".host/x" after the base URL names another host
+            raise Refused(f"{tool.id}: the path {path!r} does not start with '/'")
+        query: list[tuple[str, str]] = []
+        body: dict[str, Any] = {}
+        whole, has_whole = None, False
+        for key, value in (arguments or {}).items():
+            arg = spec.get(key)
+            if arg is None:
+                raise ValueError(f"{tool.id} has no argument {key!r}")
+            where, name = arg.get("in"), str(arg.get("name", key))
+            if where == "path":
+                text = _scalar(value)
+                if text in (".", ".."):  # a dot segment would move the request up the path
+                    raise ValueError(f"{tool.id}: path parameter {name!r} cannot be {text!r}")
+                path = path.replace("{" + name + "}", urllib.parse.quote(text, safe=""))
+            elif where == "query":
+                if isinstance(value, (list, dict)) and "style" not in arg:
+                    raise Refused(f"{tool.id}: re-ingest the spec to pass a list or an object in {key!r}")
+                query += _query_pairs(
+                    name, value, str(arg.get("style", "form")), bool(arg.get("explode", True))
+                )
+            elif where == "body":
+                if name:
+                    body[name] = value
+                else:
+                    whole, has_whole = value, True
+            else:
+                raise Refused(f"{tool.id}: {where} parameters are not supported by the proxy yet")
+        missing = re.findall(r"\{([^}]+)\}", path)
+        if missing:
+            raise ValueError(f"{tool.id} is missing path parameter(s): {', '.join(missing)}")
+        url = base.rstrip("/") + path
+        if not same_origin(url, base):  # the URL that is sent, however it came to be composed
+            raise Refused(f"{tool.id}: {url!r} is not a URL on {base}")
+        req: dict[str, Any] = {"method": method, "url": url, "params": query, "headers": headers}
+        payload = whole if has_whole else (body or None)
+        if payload is not None:
+            media = str(http.get("body_media_type") or "application/json")
+            if "json" in media:
+                req["json"] = payload
+            elif media == "application/x-www-form-urlencoded" and isinstance(payload, dict):
+                pairs = [p for k, v in payload.items() for p in _bracket(k, v)]
+                req["content"] = urllib.parse.urlencode(pairs).encode("utf-8")
+                req["headers"] = {**headers, "Content-Type": media}
+            else:
+                raise Refused(f"{tool.id}: {media} bodies are not supported by the proxy yet")
+        return req
+
+    def _http(self) -> Any:
+        import httpx2
+
+        if self._client is None:
+            self._client = httpx2.AsyncClient(
+                timeout=httpx2.Timeout(self.timeout), follow_redirects=False, transport=self.transport
+            )
+        return self._client
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def call(self, tool: Tool, arguments: dict[str, Any] | None) -> CallOutcome:
+        import httpx2
+        from mcp_types import CallToolResult, TextContent
+
+        try:
+            req = self.build(tool, arguments)
+        except Refused as e:
+            return CallOutcome(error_result(str(e)), "refused")
+        except ValueError as e:
+            return CallOutcome(error_result(str(e)), "tool_error")
+        try:
+            resp = await self._http().request(**req)
+        except httpx2.TimeoutException:
+            return CallOutcome(
+                error_result(f"{tool.category}: no answer within {self.timeout:g} s"), "timeout"
+            )
+        except httpx2.HTTPError as e:
+            return CallOutcome(error_result(f"{tool.category}: {type(e).__name__}: {e}"), "protocol_error")
+        status = resp.status_code
+        if 300 <= status < 400:
+            text = f"HTTP {status}: redirect to {resp.headers.get('location', '?')} (not followed)"
+        else:
+            body = resp.text
+            if len(body) > self.max_chars:
+                body = body[: self.max_chars] + f"\n… truncated: {len(body)} characters in total"
+            text = f"HTTP {status}\n{body}"
+        failed = status >= 300
+        result = CallToolResult(content=[TextContent(type="text", text=text)], is_error=failed)
+        return CallOutcome(result, "tool_error" if failed else "ok", status)
+
+
+# -- router -----------------------------------------------------------------------------------
+class Backends:
+    """``call_tool``'s router: MCP tools to their server's session, OpenAPI tools over HTTP."""
+
+    def __init__(
+        self,
+        servers: Sequence[ServerConfig] = (),
+        openapi: dict[str, OpenAPIBackend] | None = None,
+        *,
+        allow_write: bool = False,
+        call_timeout: float = 60.0,
+        connect_timeout: float = 60.0,
+        transport: Any = None,
+    ):
+        self.mcp = {c.name: MCPBackend(c, connect_timeout=connect_timeout) for c in servers}
+        self.http = OpenAPIExecutor(
+            openapi or {}, allow_write=allow_write, timeout=call_timeout, transport=transport
+        )
+        self.call_timeout = call_timeout
+        self._tg: Any = None
+
+    @asynccontextmanager
+    async def running(self) -> AsyncIterator[Backends]:
+        """The task group the MCP sessions live in; leaving it closes every backend."""
+        import anyio
+
+        try:
+            async with anyio.create_task_group() as tg:
+                self._tg = tg
+                try:
+                    yield self
+                finally:
+                    tg.cancel_scope.cancel()
+        finally:
+            self._tg = None
+            await self.http.aclose()
+
+    async def call(self, tool: Tool, arguments: dict[str, Any] | None) -> CallOutcome:
+        if "http" in tool.doc:
+            return await self.http.call(tool, arguments)
+        backend = self.mcp.get(tool.category)
+        if backend is None:
+            return CallOutcome(
+                error_result(
+                    f"{tool.category}: this MCP server is not configured for the proxy (--config or --server)"
+                ),
+                "refused",
+            )
+        if self._tg is None:
+            raise RuntimeError("Backends.call() outside Backends.running()")
+        name = str(tool.doc.get("name") or tool.id)
+        return await backend.call(self._tg, name, dict(arguments or {}), timeout=self.call_timeout)

toolrank/adapters/bm25.py

@@ -0,0 +1,78 @@
+"""Lexical baseline: BM25 via ``bm25s`` (the ToolRet paper's "BM25s" row).
+
+Tokenisation: lowercase, English stopwords, optional Snowball stemming when ``PyStemmer`` is
+installed (``pip install toolrank[stem]``). Anthropic's Tool Search Tool BM25 variant and most
+gateways' "keyword search" are this class of model, so this row is the floor every learned
+scorer must clear.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Iterable, Sequence
+
+import numpy as np
+
+from toolrank.domain import Query, RankedList, Tool
+from toolrank.formats import QUERY_FORMATS, TOOL_FORMATS, NamedFormatter
+
+
+def _stemmer(lang: str = "english"):
+    try:
+        import Stemmer  # PyStemmer
+
+        return Stemmer.Stemmer(lang)
+    except ImportError:
+        return None
+
+
+class BM25Scorer:
+    name = "bm25"
+    score_kind = "bm25"
+
+    def __init__(
+        self,
+        tool_format: NamedFormatter | str = "documentation",
+        query_format: NamedFormatter | str = "plain",
+        *,
+        k1: float = 1.5,
+        b: float = 0.75,
+        stem: bool = True,
+        stopwords: str | None = "en",
+    ):
+        self.tool_format = TOOL_FORMATS[tool_format] if isinstance(tool_format, str) else tool_format
+        self.query_format = QUERY_FORMATS[query_format] if isinstance(query_format, str) else query_format
+        self.k1, self.b, self.stopwords = k1, b, stopwords
+        self.stemmer = _stemmer() if stem else None
+        self.name = f"bm25/{self.tool_format.name}/{self.query_format.name}" + (
+            "" if self.stemmer else "/nostem"
+        )
+        self._ids: list[str] = []
+        self._bm25 = None
+        self._lock = threading.Lock()  # a server ranks from several threads; the stemmer is not shared-safe
+
+    def index(self, tools: Iterable[Tool]) -> None:
+        import bm25s
+
+        tools = list(tools)
+        self._ids = [t.id for t in tools]
+        texts = [self.tool_format(t) for t in tools]
+        toks = bm25s.tokenize(texts, stopwords=self.stopwords, stemmer=self.stemmer, show_progress=False)
+        self._bm25 = bm25s.BM25(k1=self.k1, b=self.b)
+        self._bm25.index(toks, show_progress=False)
+
+    def rank(self, queries: Sequence[Query], k: int) -> list[RankedList]:
+        import bm25s
+
+        if self._bm25 is None:
+            raise RuntimeError("call index() before rank()")
+        texts = [self.query_format(q) for q in queries]
+        kk = min(k, len(self._ids))
+        with self._lock:
+            toks = bm25s.tokenize(texts, stopwords=self.stopwords, stemmer=self.stemmer, show_progress=False)
+            docs, scores = self._bm25.retrieve(toks, k=kk, show_progress=False, n_threads=1)
+        docs, scores = np.asarray(docs), np.asarray(scores, dtype=np.float32)
+        return [
+            RankedList(q.id, [self._ids[int(j)] for j in docs[i]], [float(s) for s in scores[i]])
+            for i, q in enumerate(queries)
+        ]

toolrank/adapters/chat_api.py

@@ -0,0 +1,69 @@
+"""A ``ChatModel`` over any OpenAI-compatible ``/v1/chat/completions`` endpoint.
+
+Used to generate benchmark queries (MCP-Zero) with a local model, e.g. ``vllm serve
+Qwen/Qwen3-8B`` in the default (generate) runner. Greedy by default so a rerun asks the same
+questions. ``extra_body`` is merged into every request for server-specific switches, such as
+``{"chat_template_kwargs": {"enable_thinking": False}}`` to turn off Qwen3's thinking on vLLM.
+
+Standard library only (``urllib``), like the embeddings adapter.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+from toolrank.adapters.embeddings_api import env_api_key
+
+
+class OpenAIChat:
+    def __init__(
+        self,
+        model: str,
+        base_url: str = "http://127.0.0.1:8093/v1",
+        *,
+        api_key: str | None = None,
+        temperature: float = 0.0,
+        max_tokens: int = 256,
+        extra_body: dict[str, Any] | None = None,
+        timeout: float = 300.0,
+        max_retries: int = 3,
+    ):
+        self.model, self.base_url = model, base_url.rstrip("/")
+        self.api_key = api_key or env_api_key(self.base_url, "TOOLRANK_CHAT_API_KEY")
+        self.temperature, self.max_tokens = temperature, max_tokens
+        self.extra_body = dict(extra_body or {})
+        self.timeout, self.max_retries = timeout, max_retries
+        self.name = f"chat/{model}"
+
+    def complete(self, system: str, user: str) -> str:
+        body: dict[str, Any] = {
+            "model": self.model,
+            "messages": [{"role": "system", "content": system}, {"role": "user", "content": user}],
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+            **self.extra_body,
+        }
+        req = urllib.request.Request(
+            f"{self.base_url}/chat/completions",
+            data=json.dumps(body).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        if self.api_key:  # never copied onto a redirect, which may point anywhere
+            req.add_unredirected_header("Authorization", f"Bearer {self.api_key}")
+        last: Exception | None = None
+        for attempt in range(self.max_retries):
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                    j = json.loads(r.read().decode("utf-8"))
+                break
+            except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError) as e:  # noqa: PERF203
+                last = e
+                time.sleep(1.5 * (attempt + 1))
+        else:
+            raise RuntimeError(f"chat endpoint {self.base_url} unreachable: {last}") from last
+        return str(j["choices"][0]["message"].get("content") or "")