bantamkit 0.27.0__py3-none-any.whl

bantamkit/assets/tools/skill_audit.json

@@ -0,0 +1,70 @@
+{
+  "name": "skill_audit",
+  "description": "Price the skill catalogue every session pays for, and name the collisions in it. A skill's `description:` frontmatter is loaded into the agent's context in EVERY session; its body is read only when the skill is invoked, so the descriptions are the standing bill. Walks `root` for `<marketplace>/<plugin>/<version>/skills/<name>/SKILL.md` and answers one JSON document: `roots` (what was scanned), `skills` (how many were counted), `catalogue_bytes` (UTF-8 bytes of their `description:` values), `findings` and `omissions`. Counted skills plus omissions account for every SKILL.md found — an omission is `{subject, count, size, what}` with subject one of `plugin-not-enabled`, `duplicate-skill`, `stale-version`, `unreadable-file`, `unparsed-frontmatter`, and `what` naming the paths. Pass `enabled` with the plugin ids the host has switched on (`<plugin>@<marketplace>`, as settings.json spells them): the plugin cache also holds disabled plugins and stale version directories, and counting those inflated a real audit to 41 skills / 19,065 B against a true 34 / 14,515. Identity comes from the path: `<marketplace>/<plugin>/<version>/skills/<name>/SKILL.md` relative to `root`; any other shape is a skill outside a plugin, identified by its directory name alone and never excluded by `enabled`. Exactly ONE version directory is resolved per (marketplace, plugin) BEFORE anything is counted, and its skills are that plugin's skills: a name absent from the resolved version is absent, never merged in from another version directory. The winner is the version directory name that sorts LAST in byte order — a byte order and deliberately not a semver comparison, so two runtimes cannot disagree about which directory was read, and so that names which are not versions at all still have a total order (a real cache spells nine of one plugin's directories as content hashes plus the literal `unknown`). What byte order gets wrong is stated rather than hidden: `10.0.0` loses to `9.0.0`, and among non-version names the winner is deterministic but arbitrary; both losers are named in an omission record. Pass `versions` with the version directory the host actually serves, per `<plugin>@<marketplace>` — the `installPath` recorded in the same `installed_plugins.json` the caller reads `enabled` out of — and that plugin is resolved to the named directory whatever byte order would have said; a plugin absent from `versions` falls back to byte order. It is host truth the caller supplies, exactly as `enabled` is, and it is not refused when it names a plugin or a directory this `root` does not hold: a plugin with no version directory here is not resolved at all, and a directory that is not here means every directory that IS here loses and is named in a `stale-version` record. Measured 2026-09-05 on a real cache, byte order picks `unknown` for a plugin whose host serves `1dd995193ba2`, so the installed copy is discarded as a duplicate. The candidates are the version DIRECTORIES on disk — every path spelled `<marketplace>/<plugin>/<version>/skills` — and not the skills that survived reading: a version directory holding no `SKILL.md`, or only files that will not decode or will not parse, still exists and the host still serves it, so an older directory must not win by default. Every SKILL.md under a version directory that did not win is omitted, under one of two subjects: `duplicate-skill` when the resolved version has a skill of the same name standing in for it, `stale-version` when it does not — a skill the resolved version DROPPED, which is on disk, in nobody's bill, and would otherwise be resurrected by the audit. Deduping by the (marketplace, plugin, name) triple instead merges versions rather than choosing between them, and measured 2026-09-05 over a real cache holding a plugin's `0.4.0` (14 skills) and `0.5.0` (5, nine having moved to another plugin) it answered 31 skills / 9,280 bytes where the host serves 22 / 3,396. Inside the resolved version `duplicate-skill` still covers two files claiming the same (marketplace, plugin, name), which is reachable only for skills outside a plugin; the last in scan order wins. Every omission carries the bytes it would have added. A skill is identified as `<plugin>:<name>`, the spelling the host uses and the key `usage` is looked up by, or as `<name>` when it has no plugin. A `description:` folded over several lines is joined with single spaces before it is counted or scanned, and a value written as a whole-value quoted YAML scalar is UNWRAPPED after that fold and before either — the host's parser strips those quotes before a session sees the description, so they are not `catalogue_bytes`, and only quotes INSIDE the value delimit a trigger phrase. The unwrap applies to every frontmatter key, not just `description:`, so `name: \"s\"` is the name `s` and `router: \"true\"` is a router. A value is a whole-value scalar only when it begins with `\"` or `'` AND that opening quote's own closing quote is the value's LAST character, judged by YAML's two escape rules and no others: inside a `\"` scalar a backslash escapes the character after it, so `\\\"` does not close it and the sequences `\\\"` and `\\\\` resolve to `\"` and `\\` while every other `\\x` is left exactly as written; inside a `'` scalar a doubled `''` is one literal apostrophe, so it does not close it and resolves to `'`. Every other value is left as written and scanned literally: `\"a\" and \"b\"` begins and ends with `\"` and is NOT one scalar, because its opening quote closes at index 2, and stripping it would weld the value into one junk phrase and destroy both real ones. A value that OPENS with a quote and never closes one — including one whose last quote is escaped — is a LITERAL: it is not unwrapped, its quote character is counted, its unpaired quote opens no phrase, and it is not a `frontmatter-malformed` finding, which names failures of the BLOCK and not of one value. Measured 2026-09-05 over a real plugin cache: 17 of 31 enabled skills write `description: \"...\"`, so a reader that takes those quotes literally over-prices the majority of a catalogue and buries any phrase quoted inside them. Five findings, each `{kind, severity, skills, detail}`, severity fixed per kind: `shared-trigger-phrase` (high) — two or more skills quote the same literal phrase, so which one fires is a coin flip; `catalogue-over-budget` (high) — `catalogue_bytes` exceeds `budget`; `never-invoked` (low) — a counted skill has zero calls in `usage`; `frontmatter-malformed` (medium) — no frontmatter block, an unterminated one, or no `description:` key, where a block that cannot be parsed at all is also omitted as `unparsed-frontmatter` and adds nothing to `skills` while a parsed block with no description is a skill costing zero bytes; `name-mismatch` (medium) — the frontmatter `name:` is not the skill's directory name. Collisions are EXACT matches on literal quoted phrases and never a similarity score: Jaccard over description tokens was measured across 820 real pairs and refuted, topping out at 0.239 and ranking the two real collisions 118th and 791st of 820. Phrases are the text of the UNWRAPPED value between `\"` pairs, or between `'` pairs where the quote is not flanked by letters — `'don't'` is a contraction, not a phrase — and a phrase with no letter or digit in it is ignored. A router, a skill whose frontmatter carries `router: true`, quotes its siblings' phrases by design and is left out of the phrase index entirely. Four argument failures are refused with their own sentences and never as a partial answer: an unknown `check`, a negative `budget`, a `root` that is missing or is a file, and an EMPTY `root` — which passes JSON-schema `string` and would otherwise resolve to the server's own working directory. Nothing about the CONTENT of the tree refuses. Deterministic: the tool reads nothing but `root`. The three facts a directory of files cannot answer arrive from the caller — call counts in `usage` (`node tools/ledger/tool-usage.mjs --group skill --json`), switched-on plugins in `enabled`, served version directories in `versions` — never by reading the host's transcripts, settings or plugin registry.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "type": "object",
+    "required": [
+      "root"
+    ],
+    "properties": {
+      "root": {
+        "type": "string",
+        "description": "Directory to scan for SKILL.md files, absolute or relative to the server's working directory. It must name a directory: the empty string is refused rather than resolved, because resolving it would audit whatever directory the server happens to be standing in"
+      },
+      "enabled": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Plugin ids that are switched on, `<plugin>@<marketplace>`; when given only skills under those plugins are counted, when omitted every skill under `root` counts"
+      },
+      "usage": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "description": "Skill id (`<plugin>:<name>`) to call count, the caller's own measurement; a counted skill absent from a supplied map is treated as zero"
+      },
+      "check": {
+        "type": "string",
+        "enum": [
+          "all",
+          "phrase",
+          "budget",
+          "frontmatter"
+        ],
+        "description": "Which family of findings to report; default `all`. `skills`, `catalogue_bytes` and `omissions` are reported whatever this says"
+      },
+      "budget": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 9007199254740991,
+        "description": "Catalogue byte budget; `catalogue-over-budget` is only reported when this is given"
+      },
+      "versions": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string"
+        },
+        "description": "Plugin id (`<plugin>@<marketplace>`) to the version directory name the host actually serves; when a plugin is named here that directory is resolved whatever byte order would have said, and a plugin absent from it falls back to byte order"
+      }
+    }
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "skill_auditOutput"
+  }
+}

bantamkit/assets/tools/validate_json.json

@@ -0,0 +1,31 @@
+{
+  "name": "validate_json",
+  "description": "Validate candidate output text against a JSON Schema. Returns {valid, feedback}; when invalid, feed the feedback back to the model and retry.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "output": {
+        "title": "Output",
+        "type": "string"
+      },
+      "schema": {
+        "additionalProperties": true,
+        "title": "Schema",
+        "type": "object"
+      }
+    },
+    "required": [
+      "output",
+      "schema"
+    ],
+    "type": "object",
+    "title": "validate_jsonArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "validate_jsonDictOutput"
+  }
+}

bantamkit/assets.py

@@ -0,0 +1,67 @@
+"""Locate and load the language-agnostic asset pack."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from bantamkit.client import BantamError, Tool
+
+
+class AssetNotFound(BantamError):
+    pass
+
+
+def assets_root() -> Path:
+    env = os.environ.get("BANTAMKIT_ASSETS")
+    if env:
+        return Path(env)
+    packaged = Path(__file__).parent / "assets"
+    if packaged.exists():
+        return packaged
+    repo = Path(__file__).resolve().parents[3] / "assets"
+    if repo.exists():
+        return repo
+    raise AssetNotFound("no assets directory found; set BANTAMKIT_ASSETS")
+
+
+def load_tool_asset(name: str) -> dict:
+    """Return one tool asset VERBATIM — every key, including the ones no surface uses.
+
+    `load_tool` below narrows the same file to the three fields a model is shown. This
+    returns the whole manifest entry, because a server has to read `surfaces` (may I
+    register this at all?) and `output_schema` (what do I advertise as the return shape?)
+    and neither belongs on the agent-facing `Tool`.
+    """
+    path = assets_root() / "tools" / f"{name}.json"
+    if not path.exists():
+        raise AssetNotFound(f"tool asset not found: {path}")
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def load_tool(name: str) -> Tool:
+    """The agent-facing view of a tool asset: name, description, input schema.
+
+    The three keys are named EXPLICITLY rather than splatted. `assets/tools/` is shared by
+    two tool surfaces and carries fields that only the MCP one consumes; a loader that
+    passed the dict through would add them to every tool definition an eval-run model is
+    shown, changing the agent surface every time the manifest grows.
+    """
+    data = load_tool_asset(name)
+    return Tool(name=data["name"], description=data["description"], parameters=data["parameters"])
+
+
+def load_schema(name: str) -> dict:
+    """Return a JSON Schema asset (parsed) — e.g. the shift-work checkpoint contract."""
+    path = assets_root() / "schemas" / f"{name}.json"
+    if not path.exists():
+        raise AssetNotFound(f"schema asset not found: {path}")
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def load_skill(name: str) -> str:
+    path = assets_root() / "skills" / f"{name}.md"
+    if not path.exists():
+        raise AssetNotFound(f"skill asset not found: {path}")
+    return path.read_text(encoding="utf-8")

bantamkit/budget.py

@@ -0,0 +1,114 @@
+"""Layer 1 — a global spend governor for one agent run: `TokenBudget`."""
+
+from __future__ import annotations
+
+from bantamkit.client import Usage
+from bantamkit.profile import default as profile_default
+from bantamkit.profile import default_float as profile_default_float
+
+__all__ = ["TokenBudget"]
+
+
+class _BudgetedClient:
+    """The recording point: every chat through the agent's client books its usage.
+
+    A proxy rather than a subclass, because the thing being wrapped is whatever
+    the caller handed the agent (a raw adapter, the eval harness's tracking
+    client, a fake). `__getattr__` passes everything else through, so the
+    duck-typed contracts callers test for — `seed`, `model`,
+    `_response_format_unsupported` — read the inner client unchanged.
+    """
+
+    def __init__(self, inner, budget: TokenBudget):
+        self.inner = inner
+        self.budget = budget
+
+    def chat(self, *args, **kwargs):
+        resp = self.inner.chat(*args, **kwargs)
+        self.budget.record(resp.usage)
+        return resp
+
+    def __getattr__(self, name: str):
+        return getattr(self.inner, name)
+
+
+class TokenBudget:
+    """A governor, not an odometer: it decides what a run may still spend.
+
+    Every gate already caps its own retries; composition multiplies those caps
+    and nothing bounded the total (3b `full`: 214,698 tokens for 15/66). This
+    component bounds the run and degrades it in two steps instead of one:
+
+    - past ``ceiling * optional_cutoff`` spent, ``allow("optional")`` is denied,
+      so optional work is skipped and a `full` run degrades toward `lean`/`bare`;
+    - past ``ceiling``, everything is denied and `Agent.run` stops at the top of
+      the next turn, returning the last assistant content as a best-effort result.
+
+    The gap between the cutoff and the ceiling **is** the reserve: the final
+    answer emission always fits.
+
+    Priority classification (v1, deliberately coarse — no cost estimation, which
+    would be guesswork until a measured need exists):
+
+    - ``"optional"`` — critique rounds, blind and grounded. Denied means "accept
+      the answer", never an exception.
+    - ``"required"`` — the agent's own turns and the schema / json-answer retries.
+      Cheap, high-value, and denied only past the hard ceiling.
+
+    Spend is booked at the client boundary: `setup` wraps `agent.client` in a
+    `_BudgetedClient`, so every call made through the agent's client moves
+    `spent` — the agent's own turns *and* the critic calls the gates issue
+    through `structured()` on that same client. That is the point: the critique
+    rounds are the dominant optional spend the cutoff exists to govern, and
+    while `Agent.run` was the only recording point they were invisible to the
+    governor.
+
+    `structured()` is still not budgeted as a *loop*: it never asks `allow()`
+    between its own retries, which stay bounded by `max_retries`. What changed
+    is visibility, not control.
+
+    Attach with `Agent.use(...)`; `setup` resets per-run state, so one instance
+    may not measure two runs at once but can be reused across sequential ones.
+    """
+
+    def __init__(self, ceiling: int | None = None, optional_cutoff: float | None = None):
+        self.ceiling = (
+            ceiling if ceiling is not None else profile_default("token_budget", "ceiling")
+        )
+        self.optional_cutoff = (
+            optional_cutoff
+            if optional_cutoff is not None
+            else profile_default_float("token_budget", "optional_cutoff")
+        )
+        self.spent = 0
+        self.exhausted = False
+
+    def setup(self, agent) -> None:
+        self.spent = 0
+        self.exhausted = False
+        # Unwrap first: setting up twice on the same agent (or reusing an agent
+        # across budgets) must leave exactly one wrapper, or every call would be
+        # booked once per layer.
+        inner = agent.client
+        if isinstance(inner, _BudgetedClient):
+            inner = inner.inner
+        agent.client = _BudgetedClient(inner, self)
+        agent.budget = self
+
+    def record(self, usage: Usage) -> None:
+        """Book one chat response against the budget. Called by `_BudgetedClient`."""
+        self.spent += usage.total
+
+    def allow(self, priority: str) -> bool:
+        """Ask before spending. `priority` is ``"required"`` or ``"optional"``."""
+        if priority not in ("required", "optional"):
+            raise ValueError(f"unknown budget priority {priority!r}")
+        if self.spent >= self.ceiling:
+            # Latched for the run: the hard ceiling denied work, which is what
+            # `budget-exhausted` reports. Cutoff-band denials are degradation,
+            # not exhaustion, and deliberately do not set this.
+            self.exhausted = True
+            return False
+        if priority == "optional":
+            return self.spent < self.ceiling * self.optional_cutoff
+        return True

bantamkit/client.py

@@ -0,0 +1,329 @@
+"""Core types + ModelClient protocol + OpenAI-compatible adapter."""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Protocol
+
+import httpx
+
+BODY_SNIPPET = 200
+
+
+class BantamError(Exception):
+    """Base for all bantamkit errors."""
+
+
+class TransportError(BantamError):
+    """HTTP-level failure after bounded retries."""
+
+
+class APIError(BantamError):
+    """Non-retryable, non-success response from the model endpoint."""
+
+    def __init__(self, status_code: int, body: str):
+        self.status_code = status_code
+        self.body = body[:BODY_SNIPPET]
+        super().__init__(f"API error {status_code}: {self.body!r}")
+
+
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    arguments: dict
+
+
+@dataclass
+class Message:
+    role: str  # "system" | "user" | "assistant" | "tool"
+    content: str | None = None
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    tool_call_id: str | None = None
+
+    def to_wire(self) -> dict:
+        wire: dict = {"role": self.role, "content": self.content}
+        if self.tool_calls:
+            wire["tool_calls"] = [
+                {
+                    "id": tc.id,
+                    "type": "function",
+                    "function": {"name": tc.name, "arguments": json.dumps(tc.arguments)},
+                }
+                for tc in self.tool_calls
+            ]
+        if self.tool_call_id is not None:
+            wire["tool_call_id"] = self.tool_call_id
+        return wire
+
+
+@dataclass
+class Tool:
+    name: str
+    description: str
+    parameters: dict  # JSON Schema
+
+    def to_wire(self) -> dict:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+
+# RB-P53's class, site S4. The four states `prompt_tokens` can be in, as data, because
+# a check has to be able to name one. MEASURED is the only one that licenses arithmetic.
+MEASURED = "MEASURED"
+#: The response carried no usable `usage.prompt_tokens` at all — no `usage` object, an
+#: empty or null one, or one that omits the field. The 0 in `Usage.prompt_tokens` is then
+#: THIS PROGRAM'S DEFAULT and not anything the endpoint said. It needs its own state
+#: because a fabricated zero compares unequal to any declared window, so without this
+#: branch the emptiest possible response read `MEASURED` — RB-P51's defect inside the
+#: code written to honour RB-P51.
+UNREPORTED = "UNREPORTED"
+#: `prompt_tokens` equals the window the caller declared. RB-P53 measured ollama's `/v1`
+#: endpoint reporting the CONTEXT WINDOW in that field when it silently clamps a prompt,
+#: so at the window the number is the window and not a measurement of anything.
+VOID = "VOID"
+#: No window was declared, so nothing could be compared. RB-P51: unmeasured is a verdict,
+#: and it is a different verdict from MEASURED.
+UNCHECKED = "UNCHECKED"
+
+# Worst first. A sum containing a non-measurement is a non-measurement, and a sum
+# containing an unchecked component is not a measured total either. UNREPORTED outranks
+# VOID: a VOID call at least returned a number the endpoint chose, while an UNREPORTED one
+# contributed a zero this module invented, so a total containing one is short by an
+# unknown amount rather than merely untrustworthy.
+_VERDICT_SEVERITY = (UNREPORTED, VOID, UNCHECKED, MEASURED)
+
+#: Stop reasons that mean the generation was CUT rather than finished. A completion that
+#: hit the cap is not a shorter answer, it is an unfinished one, and the difference is
+#: invisible unless something carries it.
+TRUNCATING_FINISH_REASONS = frozenset({"length"})
+
+
+def _worse_verdict(a: str | None, b: str | None) -> str | None:
+    """The worse of two `prompt_tokens` verdicts; `None` contributes nothing.
+
+    `None` is the zero value's state and it is NOT the same as `UNCHECKED`: `Usage()` is
+    the accumulator seed in the agent loop and in `evalrun`, it carries no tokens and no
+    claim, and it must not poison a fold. `UNCHECKED` means a real response arrived and
+    nobody could check it, which is a claim and does survive the fold.
+    """
+    for verdict in _VERDICT_SEVERITY:
+        if a == verdict or b == verdict:
+            return verdict
+    return a if a is not None else b
+
+
+def _worse_finish_reason(a: str | None, b: str | None) -> str | None:
+    """An aggregate has no single finish reason — but a truncation must not be summed away.
+
+    S5's shape, one repository over: a length stop absorbed into an outcome instead of
+    being reported as an instrument verdict. So a cut anywhere in the fold survives it,
+    and two different non-cut reasons collapse to `None` rather than to whichever came
+    first.
+    """
+    for reason in (a, b):
+        if reason in TRUNCATING_FINISH_REASONS:
+            return reason
+    if a == b:
+        return a
+    return a if b is None else (b if a is None else None)
+
+
+@dataclass
+class Usage:
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    #: What the endpoint said stopped the generation, verbatim, or `None` when it said
+    #: nothing. Read back rather than assumed: before this field existed a length-stopped
+    #: completion and a finished one were the same object.
+    finish_reason: str | None = None
+    #: `MEASURED` / `VOID` / `UNCHECKED` / `UNREPORTED`, or `None` for a `Usage` no
+    #: response produced.
+    prompt_tokens_verdict: str | None = None
+
+    def __add__(self, other: Usage) -> Usage:
+        return Usage(
+            self.prompt_tokens + other.prompt_tokens,
+            self.completion_tokens + other.completion_tokens,
+            _worse_finish_reason(self.finish_reason, other.finish_reason),
+            _worse_verdict(self.prompt_tokens_verdict, other.prompt_tokens_verdict),
+        )
+
+    @property
+    def total(self) -> int:
+        return self.prompt_tokens + self.completion_tokens
+
+    @property
+    def truncated(self) -> bool:
+        """The generation was cut by a cap rather than finished."""
+        return self.finish_reason in TRUNCATING_FINISH_REASONS
+
+
+@dataclass
+class Response:
+    message: Message
+    usage: Usage
+
+
+class ModelClient(Protocol):
+    def chat(self, messages: list[Message], tools: list[Tool] | None = None) -> Response: ...
+
+
+class OpenAICompatible:
+    """One adapter covers Ollama / vLLM / LM Studio / llama.cpp server / OpenRouter."""
+
+    def __init__(
+        self,
+        base_url: str,
+        model: str,
+        api_key: str = "none",
+        timeout: float = 60.0,
+        max_retries: int = 3,
+        transport: httpx.BaseTransport | None = None,
+        seed: int | None = None,
+        context_window: int | None = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.model = model
+        self.api_key = api_key
+        self.max_retries = max_retries
+        # The context window this endpoint is configured with, DECLARED by the caller.
+        # It is never sent: this adapter sets no context length and this field changes no
+        # request. It exists so that `usage.prompt_tokens == context_window` can be given
+        # a verdict, which is RB-P53's shape — a silent clamp reports the window in the
+        # field a reader takes for a prompt size. Left unset, the comparison cannot be
+        # made and every response says `UNCHECKED` rather than `MEASURED`.
+        #
+        # THIS IS A DETECTOR AND NOT A PREVENTER, and calling it protection would be the
+        # failure this job is about. It cannot stop a clamp, it cannot detect one below
+        # the window, and it cannot tell a clamped prompt from a genuine prompt that
+        # happens to be exactly `context_window` tokens long.
+        self.context_window = context_window
+        # Sampling seed, sent only when set. OpenAI chat-completions and Ollama's
+        # OpenAI-compat endpoint both accept it; servers that ignore it degrade to
+        # unseeded sampling. Writable per run — the eval harness pins it per task.
+        self.seed = seed
+        # Capability memo for the constrained-decoding tier, flipped by the first
+        # HTTP 400 on a request that carried `response_format`. Its presence is also
+        # the duck-typed signal callers test before sending the kwarg at all.
+        self._response_format_unsupported = False
+        self._http = httpx.Client(timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        """Release the underlying HTTP connection pool. Idempotent."""
+        self._http.close()
+
+    def __enter__(self) -> OpenAICompatible:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def _post(self, payload: dict) -> httpx.Response:
+        return self._http.post(
+            f"{self.base_url}/chat/completions",
+            headers={"Authorization": f"Bearer {self.api_key}"},
+            json=payload,
+        )
+
+    def chat(
+        self,
+        messages: list[Message],
+        tools: list[Tool] | None = None,
+        response_format: dict | None = None,
+    ) -> Response:
+        payload: dict = {"model": self.model, "messages": [m.to_wire() for m in messages]}
+        if tools:
+            payload["tools"] = [t.to_wire() for t in tools]
+        if self.seed is not None:
+            payload["seed"] = self.seed
+        if response_format is not None:
+            payload["response_format"] = response_format
+        last_err: Exception | None = None
+        for attempt in range(self.max_retries):
+            try:
+                r = self._post(payload)
+                if r.status_code == 400 and "response_format" in payload:
+                    # That single 400 IS the capability detection — no probe request,
+                    # no server allowlist. Drop the field, remember it for every later
+                    # call on this client, and let this call still succeed. A 400 that
+                    # survives the drop was never about response_format and raises below.
+                    self._response_format_unsupported = True
+                    del payload["response_format"]
+                    r = self._post(payload)
+                if r.status_code == 429 or r.status_code >= 500:
+                    raise TransportError(f"server error {r.status_code}: {r.text[:BODY_SNIPPET]}")
+                if not r.is_success:
+                    # Non-retryable. Covers 1xx/3xx too: redirects are not followed, so
+                    # anything but 2xx would otherwise reach _parse as non-JSON.
+                    raise APIError(r.status_code, r.text)
+                return self._parse(r.json())
+            except (httpx.TransportError, TransportError) as e:
+                last_err = e
+                if attempt < self.max_retries - 1:
+                    # No backoff after the final attempt — nothing follows it but the raise.
+                    time.sleep(0.5 * (2**attempt))
+        raise TransportError(f"chat failed after {self.max_retries} attempts: {last_err}")
+
+    def _parse(self, data: dict) -> Response:
+        try:
+            # `finish_reason` lives on the CHOICE, not on the message inside it, which is
+            # why reading it back needs the enclosing object and not just `["message"]`.
+            raw_choice = data["choices"][0]
+            choice = raw_choice["message"]
+        except (KeyError, IndexError) as e:
+            raise BantamError(f"malformed chat response: {data!r:.200}") from e
+
+        tool_calls = []
+        for tc in choice.get("tool_calls") or []:
+            try:
+                name = tc["function"]["name"]
+                raw_args = tc["function"]["arguments"]
+                # Support dict-form arguments (already a dict) or JSON string
+                if isinstance(raw_args, dict):
+                    arguments = raw_args
+                else:
+                    arguments = json.loads(raw_args)
+                tool_calls.append(ToolCall(id=tc["id"], name=name, arguments=arguments))
+            except (json.JSONDecodeError, ValueError) as e:
+                raw = tc["function"]["arguments"]
+                name = tc["function"]["name"]
+                raise BantamError(
+                    f"tool call '{name}' has malformed JSON arguments: {raw!r:.200}"
+                ) from e
+
+        raw_usage = data.get("usage")
+        usage = raw_usage if isinstance(raw_usage, dict) else {}
+        reported = usage.get("prompt_tokens")
+        # `bool` is an `int` and `True` is not a token count.
+        usable = isinstance(reported, int) and not isinstance(reported, bool)
+        prompt_tokens = reported if usable else 0
+        # The classifier. Four states, one branch each, and no branch is a message: a
+        # mutation that rewrites the docstrings above cannot move any of them (N-12).
+        # UNREPORTED is tested FIRST because it is a fact about what arrived, and the
+        # window question does not arise for a number that was never sent.
+        if not usable:
+            verdict = UNREPORTED
+        elif self.context_window is None:
+            verdict = UNCHECKED
+        elif prompt_tokens == self.context_window:
+            verdict = VOID
+        else:
+            verdict = MEASURED
+        return Response(
+            message=Message(role="assistant", content=choice.get("content"), tool_calls=tool_calls),
+            usage=Usage(
+                prompt_tokens,
+                usage.get("completion_tokens", 0),
+                raw_choice.get("finish_reason"),
+                verdict,
+            ),
+        )