bantamkit 0.27.0__py3-none-any.whl

bantamkit/__init__.py

@@ -0,0 +1,32 @@
+from bantamkit.agent import Agent, AgentResult, MaxTurnsExceeded, ToolDef
+from bantamkit.client import (
+    APIError,
+    BantamError,
+    Message,
+    ModelClient,
+    OpenAICompatible,
+    Response,
+    Tool,
+    ToolCall,
+    TransportError,
+    Usage,
+)
+from bantamkit.critique import (
+    CritiqueExhausted,
+    CritiqueGate,
+    GroundedCritiqueGate,
+    Rubric,
+    load_rubric,
+    render_evidence,
+)
+from bantamkit.evalrun import CONFIGS, format_report, run_suite
+from bantamkit.filegraph import FileAccessGraph
+from bantamkit.loopguard import LoopGuard
+from bantamkit.memory import Memory, MemoryStore
+from bantamkit.structured import StructuredOutputError, extract_json, structured
+
+# RB-P45. The one place this checkout declares its version. `pyproject.toml` names this
+# file as its dynamic version source, so the wheel's metadata and the string the MCP
+# server advertises are the same committed bytes, and neither is a function of when
+# someone last ran `pip`.
+__version__ = "0.27.0"

bantamkit/agent.py

@@ -0,0 +1,458 @@
+"""Core agentic loop: chat → tool call → observe → repeat, within budgets."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from contextlib import AbstractContextManager, ExitStack
+from dataclasses import dataclass, field
+
+from bantamkit.client import BantamError, Message, ModelClient, Tool, Usage
+from bantamkit.contract import tool_argument_types, tool_arguments, tool_failed
+from bantamkit.profile import default as profile_default
+from bantamkit.textutil import truncate_counted
+
+
+def response_format_for(schema: dict) -> dict:
+    """The wire shape of the constrained-decoding tier, in one place.
+
+    Lives here rather than in `structured.py` so both core callers — the one-shot
+    `structured()` loop and the agent loop — send byte-identical bodies; a second
+    spelling would make "same tier" unfalsifiable across the two paths.
+    """
+    return {"type": "json_schema", "json_schema": {"name": "output", "schema": schema}}
+
+
+def _supports_response_format(client: ModelClient) -> bool:
+    """Duck-typed capability check, same spirit as `seed`.
+
+    A client that understands the kwarg exposes the memo (`OpenAICompatible`
+    initializes it `False`); one that has met a 400 has flipped it to `True`.
+    Fake clients and adapters that never heard of the kwarg lack the attribute
+    entirely and are never sent it.
+    """
+    return hasattr(client, "_response_format_unsupported") and not (
+        client._response_format_unsupported
+    )
+
+
+class MaxTurnsExceeded(BantamError):
+    """The loop ended without a final answer inside the turn budget.
+
+    Carries the transcript up to the raise. Without it, the runs most worth
+    diagnosing are the ones that record nothing: v0.8.1's probes wrote
+    `messages: []` for every turns-exhausted run.
+    """
+
+    def __init__(self, message: str, messages: list[Message] | None = None):
+        super().__init__(message)
+        self.messages: list[Message] = list(messages or [])
+
+
+def _attach_transcript(error: BantamError, messages: list[Message]) -> None:
+    """Fill in a gate-raised error's transcript slot from the agent's own messages.
+
+    A post hook raises from inside `_first_feedback`, where the agent is the last
+    holder of the transcript — the hook was never handed one, and `run_task`'s own
+    `messages` list is still empty. Without this, every `schema-exhausted` and
+    `critique-exhausted` run recorded `messages: []`.
+
+    Opt-in by declaration, and fill-once: only an error that already carries a
+    `messages` list (the `MaxTurnsExceeded` shape) is filled, and only while that
+    list is empty. An error that declares no slot is left exactly as raised — a
+    transport failure is not a gate giving up, and measurement must not invent a
+    payload for it.
+    """
+    existing = getattr(error, "messages", None)
+    if isinstance(existing, list) and not existing:
+        error.messages = list(messages)
+
+
+@dataclass
+class ToolDef:
+    tool: Tool
+    handler: Callable[..., str]
+
+
+_STRING_COERCIONS: dict[str, Callable[[str], object]] = {
+    "integer": int,
+    "number": float,
+    "boolean": lambda v: {"true": True, "false": False}[v.strip().lower()],
+}
+
+
+def coerce_arguments(arguments: dict, parameters: dict) -> dict:
+    """Adapt string-spelled scalars to the tool's declared parameter schema.
+
+    Small models send `k` as the JSON string `"10"` and the handler dies
+    comparing int to str — 17 of the 18 tool-argument failures in the 3b probe.
+    Only strings under an `integer`/`number`/`boolean` property are touched,
+    top level only; a conversion that fails passes the original value through
+    so today's error observation fires unchanged. Well-typed calls are no-ops.
+    """
+    properties = parameters.get("properties") if isinstance(parameters, dict) else None
+    if not isinstance(properties, dict):
+        return arguments
+    coerced = dict(arguments)
+    for key, value in arguments.items():
+        schema = properties.get(key)
+        if not isinstance(value, str) or not isinstance(schema, dict):
+            continue
+        declared = schema.get("type")
+        convert = _STRING_COERCIONS.get(declared) if isinstance(declared, str) else None
+        if convert is None:
+            continue
+        try:
+            coerced[key] = convert(value)
+        except (ValueError, KeyError):
+            pass  # unconvertible: hand the handler what the model actually sent
+    return coerced
+
+
+def declared_arguments(parameters: dict) -> list[str]:
+    """The argument names a tool's schema declares, or [] if it declares no mapping."""
+    properties = parameters.get("properties") if isinstance(parameters, dict) else None
+    return sorted(properties) if isinstance(properties, dict) else []
+
+
+def select_declared_arguments(arguments: dict, parameters: dict) -> dict:
+    """Drop the arguments a tool's schema does not declare, so an extra key cannot raise.
+
+    Measured need, 2026-08-20: on `document_list` — whose schema declares NO properties —
+    **5 of 5 seeds on the 4b** sent a spurious `document` argument. `handler(**arguments)`
+    raised `TypeError`, the model was told the tool had failed, and 3 of 4 smoke repeats then
+    answered that they were unable to access the workbook. A tool that crashes on a key it
+    never declared is measuring its own handler signature, not the model.
+
+    Ignoring the key rather than lecturing about it is the deliberate choice: an argument the
+    schema does not name is an argument the tool has no way to act on, so there is nothing to
+    negotiate, and the alternative spends one of ten turns telling the model something it
+    could have been shown by simply answering the call. Where the arguments genuinely cannot
+    be honoured — a declared one omitted — `_dispatch` still says so, in `contract`'s words.
+
+    Only a schema that declares a `properties` mapping and does not open itself with
+    `additionalProperties: true` is filtered. Anything else is passed through untouched,
+    because there the handler is the only thing that knows what it takes. Same shape and same
+    top-level-only scope as `coerce_arguments`, and a well-formed call is a no-op.
+    """
+    if not isinstance(arguments, dict) or not isinstance(parameters, dict):
+        return arguments
+    if parameters.get("additionalProperties") is True:
+        return arguments
+    properties = parameters.get("properties")
+    if not isinstance(properties, dict):
+        return arguments
+    return {k: v for k, v in arguments.items() if k in properties}
+
+
+#: The JSON-Schema type names a tool may declare, mapped to what that type looks like once
+#: the wire JSON has been parsed. `number` admits `int` because JSON Schema says an integer is
+#: a number; `integer` does not admit `float`, because a model that sent `4137.0` for a row
+#: offset is telling us something about its own arithmetic and a silent floor would hide it.
+_JSON_TYPES: dict[str, tuple[type, ...]] = {
+    "string": (str,),
+    "integer": (int,),
+    "number": (int, float),
+    "boolean": (bool,),
+    "object": (dict,),
+    "array": (list, tuple),
+}
+
+
+def json_type_of(value: object) -> str:
+    """Name a sent value in the vocabulary the tool's own schema is written in.
+
+    The schema says `"type": "string"`; the model wrote JSON. Reporting `dict` would answer in
+    a third language — Python's — which is the language this whole defect was about. The
+    fallback is deliberately not `type(value).__name__`: an argument comes off a JSON wire and
+    is one of these seven, and a name Python invented is exactly what must not reach a model.
+    """
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, int):
+        return "integer"
+    if isinstance(value, float):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, dict):
+        return "object"
+    if isinstance(value, (list, tuple)):
+        return "array"
+    return "unknown"
+
+
+def mistyped_arguments(arguments: dict, parameters: dict) -> list[tuple[str, str, str]]:
+    """Which DECLARED arguments hold a value of a type the schema does not declare.
+
+    `RB-P86`, measured over J10's 432 graded runs. `select_declared_arguments` drops the keys
+    a schema does not name and type-checks nothing, so `llama3.2:3b` — which emits a
+    JSON-Schema FRAGMENT as the value of a declared parameter,
+    `{"document": {"description": "stock", "type": "string"}}` — had its dict passed straight
+    through to `docs.get(name)`, where a dict is not hashable. 13 observations of
+    `unhashable type: 'dict'`, all on `document_read`, all three `3b` reader cells
+    UNINFORMATIVE. That is the same class Amendment 1 fixed, one layer in.
+
+    REPORTED, not coerced and not dropped, and the three are genuinely different behaviours:
+
+    - **Coerced** is what `coerce_arguments` already does and this runs AFTER it, so the one
+      unambiguous conversion a small model actually needs — `"4137"` for a declared `integer`
+      — is already an `int` by the time anything here looks at it and is never reported. There
+      is no second conversion with that property. `{"type": "string"}` for a string has no
+      value to convert to, and `0` for a declared `string` is worse than unconvertible: to
+      `docread` an int part key is an INDEX and a str part key is a NAME, so `"0"` would ask a
+      different question than `0` did and the model would never be told the question changed.
+    - **Dropped** is right for an UNDECLARED key — the tool has no way to act on it, so there
+      is nothing to negotiate — and wrong here for the opposite reason: the schema names this
+      argument, so dropping it silently substitutes the handler's default. A model that asked
+      for `offset` as an object would be handed page 0 as though it had asked for page 0.
+      This repository already refuses that shape of answer (`document_offset_past_end` exists
+      because an empty page is "a dead end the model cannot tell from a real one").
+    - **Reported** costs one of ten turns and buys a sentence naming the argument, the type
+      the tool declares and the type that arrived. 11 of the 13 measured runs issued no
+      further tool call at all after reading CPython's sentence; a model cannot correct a
+      hash-table error, and can correct a sentence that names `offset` and the type its own
+      schema declares for it. The wording is the asset's; see `contract.tool_argument_types`.
+
+    Two exemptions, both deliberate. `null` is the wire spelling of "omitted" — every handler
+    in this repository already defaults its arguments to `None` and `_document_int` documents
+    None-as-fallback — so a null is passed through rather than reported. And an argument whose
+    schema declares no `type`, or a type name not in `_JSON_TYPES`, is not checked at all,
+    because there the schema has not said anything to hold the value against.
+
+    `True` is reported for a declared `integer` or `number` even though `isinstance(True, int)`
+    is Python-true: JSON Schema does not make a boolean a number, and `limit=true` is a model
+    losing track of its own call rather than asking for one row.
+
+    Same top-level-only scope as `coerce_arguments` and `select_declared_arguments`, and a
+    well-typed call is a no-op returning `[]`.
+    """
+    if not isinstance(arguments, dict) or not isinstance(parameters, dict):
+        return []
+    properties = parameters.get("properties")
+    if not isinstance(properties, dict):
+        return []
+    wrong: list[tuple[str, str, str]] = []
+    for key in sorted(arguments):
+        value = arguments[key]
+        schema = properties.get(key)
+        if not isinstance(schema, dict) or value is None:
+            continue
+        declared = schema.get("type")
+        if not isinstance(declared, str):
+            continue
+        accepted = _JSON_TYPES.get(declared)
+        if accepted is None:
+            continue
+        numeric = declared in ("integer", "number")
+        if isinstance(value, accepted) and not (numeric and isinstance(value, bool)):
+            continue
+        wrong.append((key, declared, json_type_of(value)))
+    return wrong
+
+
+def handler_accepts(handler: Callable[..., str], arguments: dict) -> bool:
+    """Can `handler` be CALLED with these arguments? Answered without calling it.
+
+    The point is the failure mode this replaces: a `TypeError` raised by the call itself
+    carries Python's own sentence, `qualname() missing 1 required positional argument`, and
+    that sentence used to be handed to the model verbatim. Binding the signature first turns
+    every argument-shaped failure into a contract string that names what the tool takes,
+    and leaves the `except` branch for exceptions raised INSIDE a handler.
+
+    A handler that cannot be introspected (a builtin, a C callable) is reported as accepting:
+    there the call is the only check that exists, and refusing it would be a guess.
+    """
+    try:
+        signature = inspect.signature(handler)
+    except (TypeError, ValueError):
+        return True
+    try:
+        signature.bind(**arguments)
+    except TypeError:
+        return False
+    return True
+
+
+@dataclass
+class AgentResult:
+    output: str
+    messages: list[Message]
+    usage: Usage
+    #: C-6, 2026-08-19. How many tool observations this run had cut to fit
+    #: `observation_budget`, and how many bytes went with them. The cut was always
+    #: announced IN BAND — `[truncated N bytes]` inside the string the model reads — and
+    #: nowhere else, so a run whose evidence was cut and one whose was not were the same
+    #: object to every caller, every scorer and every artifact. RB-P51: a run that
+    #: silently proceeded is not the same run as one that reported what it dropped.
+    #:
+    #: Zero on an uncut run, which is what keeps the column from being always-on. It is a
+    #: DISCLOSURE and not a verdict: the loop still proceeds, exactly as it did before,
+    #: and nothing here decides whether a cut run is scorable.
+    observations_truncated: int = 0
+    observation_bytes_dropped: int = 0
+
+
+@dataclass
+class Agent:
+    client: ModelClient
+    tools: list[ToolDef] = field(default_factory=list)
+    system: str | None = None
+    max_turns: int | None = None
+    observation_budget: int | None = None
+    # Optional spend governor (`bantamkit.budget.TokenBudget`), attached by `use(...)`.
+    # Typed loosely and duck-typed at the call sites on purpose: core must not depend
+    # on the component, and an agent without one is byte-identical to before.
+    budget: object | None = None
+    # Optional constrained-decoding request for the loop's own model call
+    # (`response_format_for(schema)`). Unset by default and forwarded only to a client
+    # that understands the kwarg, so every existing caller stays byte-identical.
+    # It has to live on the loop, not on a gate: a gate only ever sees a violation that
+    # already happened, and the decode worth constraining is the first one.
+    response_format: dict | None = None
+    _post_hooks: list[Callable[..., str | None]] = field(default_factory=list)
+    # Component state that must be scoped to one assistant turn's tool calls rather
+    # than to the whole run — see `add_batch_scope`. An agent that registers none
+    # behaves exactly as it did before the hook existed.
+    _batch_scopes: list[Callable[[], AbstractContextManager]] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        self.tools = list(self.tools or [])
+        if self.max_turns is None:
+            self.max_turns = profile_default("agent", "max_turns")
+        if self.observation_budget is None:
+            self.observation_budget = profile_default("agent", "observation_budget")
+
+    def use(self, *components) -> Agent:
+        for component in components:
+            component.setup(self)
+        return self
+
+    def register_tool(self, tooldef: ToolDef) -> None:
+        self.tools.append(tooldef)
+
+    def add_system(self, text: str) -> None:
+        self.system = f"{self.system}\n\n{text}" if self.system else text
+
+    def add_post_hook(self, hook: Callable[..., str | None]) -> None:
+        self._post_hooks.append(hook)
+
+    def add_batch_scope(self, scope: Callable[[], AbstractContextManager]) -> None:
+        """Register a context-manager factory entered around each tool-call batch.
+
+        The model emits a whole batch of tool calls from one view of the world, and
+        this loop then dispatches them one after another — so a write early in the
+        batch is visible to a read later in the same batch, which the model has no
+        way to anticipate. A component whose state must not move under its own feet
+        mid-turn registers the boundary here; only the component knows what "not
+        moving" means for it, and only the loop knows where the turn ends.
+        """
+        self._batch_scopes.append(scope)
+
+    def run(self, prompt: str) -> AgentResult:
+        messages: list[Message] = []
+        if self.system:
+            messages.append(Message(role="system", content=self.system))
+        messages.append(Message(role="user", content=prompt))
+        usage = Usage()
+        last_content = ""
+        observations_truncated = 0
+        observation_bytes_dropped = 0
+
+        for _ in range(self.max_turns):
+            if self.budget is not None and not self.budget.allow("required"):
+                # Past the hard ceiling. Stop iterating and hand back what the run
+                # already produced: a truncated answer is still scorable, and an
+                # exception here would convert a scorable answer into a loss.
+                return AgentResult(
+                    output=last_content,
+                    messages=messages,
+                    usage=usage,
+                    observations_truncated=observations_truncated,
+                    observation_bytes_dropped=observation_bytes_dropped,
+                )
+            resp = self._chat(messages)
+            usage = usage + resp.usage
+            messages.append(resp.message)
+            if resp.message.content:
+                last_content = resp.message.content
+
+            if resp.message.tool_calls:
+                with ExitStack() as stack:
+                    for scope in self._batch_scopes:
+                        stack.enter_context(scope())
+                    for tc in resp.message.tool_calls:
+                        observation, dropped = truncate_counted(
+                            self._dispatch(tc), self.observation_budget
+                        )
+                        if dropped:
+                            observations_truncated += 1
+                            observation_bytes_dropped += dropped
+                        messages.append(
+                            Message(role="tool", content=observation, tool_call_id=tc.id)
+                        )
+                continue
+
+            output = resp.message.content or ""
+            try:
+                feedback = self._first_feedback(prompt, output, messages)
+            except BantamError as e:
+                # Recording only. The exception propagates unchanged — same type,
+                # same message, same traceback — so no verdict can move.
+                _attach_transcript(e, messages)
+                raise
+            if feedback is None:
+                return AgentResult(
+                    output=output,
+                    messages=messages,
+                    usage=usage,
+                    observations_truncated=observations_truncated,
+                    observation_bytes_dropped=observation_bytes_dropped,
+                )
+            messages.append(Message(role="user", content=feedback))
+
+        raise MaxTurnsExceeded(f"no final answer within {self.max_turns} turns", messages)
+
+    def _chat(self, messages: list[Message]):
+        """One model call, with the constrained-decoding tier when it is available.
+
+        Re-checked per turn, as `structured()` does: a 400 on turn 1 flips the client's
+        memo and silently drops the tier from there on.
+        """
+        tools = [t.tool for t in self.tools] or None
+        if self.response_format is not None and _supports_response_format(self.client):
+            return self.client.chat(messages, tools=tools, response_format=self.response_format)
+        return self.client.chat(messages, tools=tools)
+
+    def _dispatch(self, tc) -> str:
+        tooldef = next((t for t in self.tools if t.tool.name == tc.name), None)
+        if tooldef is None:
+            names = [t.tool.name for t in self.tools]
+            return f"error: unknown tool '{tc.name}'. available tools: {names}"
+        try:
+            parameters = tooldef.tool.parameters
+            arguments = select_declared_arguments(
+                coerce_arguments(tc.arguments, parameters), parameters
+            )
+            mistyped = mistyped_arguments(arguments, parameters)
+            if mistyped:
+                return tool_argument_types(tc.name, mistyped)
+            if not handler_accepts(tooldef.handler, arguments):
+                return tool_arguments(tc.name, declared_arguments(parameters))
+            return str(tooldef.handler(**arguments))
+        except Exception as e:
+            return tool_failed(tc.name, e)
+
+    def _first_feedback(
+        self, task: str, output: str, messages: list[Message]
+    ) -> str | None:
+        for hook in self._post_hooks:
+            if getattr(hook, "wants_transcript", False):
+                feedback = hook(task, output, messages)
+            else:
+                feedback = hook(task, output)
+            if feedback is not None:
+                return feedback
+        return None

bantamkit/assets/contracts/default.yaml

@@ -0,0 +1,90 @@
+name: default
+schema_instruction: "Return ONLY a JSON object matching this JSON Schema. No prose.\n"
+schema_retry: "{error}\nReturn ONLY a JSON object matching the schema."
+critique_feedback: "A reviewer scored your answer {score}/10 (needs >= {threshold}). Feedback: {feedback}\nIf the feedback says a value is missing, unverified, or absent from your evidence, that is a fact you never looked up: call your tools and read the source that has it. Do not reword, generalise, or hedge the previous answer to work around the gap. Then answer again."
+parse_error: "output was not parseable JSON: {detail}"
+validation_error: "JSON does not match schema at '{where}': {detail}"
+json_answer_retry: "Your answer contains no JSON. Restate your final answer as ONLY the JSON requested by the task, with no prose around it."
+loop_note: "(you have now received this exact result {count} times; it will not change. Do something different or give your final answer now)"
+loop_warn: "(STOP calling tools. Give your final answer now, in exactly the format the task asked for.)"
+evidence_line: "{name}({arguments}) -> {observation}"
+evidence_no_observation: "(no observation)"
+evidence_empty: "(no tool calls were made)"
+# The document reader pair's observations (`document_list`, `document_read`). Every string a
+# reader hands back to the model lives here and not in the harness, for the reason the layer
+# rule gives: the mechanics measured in `docread.py` transfer across models, this wording is
+# exactly what does not.
+document_manifest_empty: "no documents are attached to this task"
+document_manifest_part: "{document} ({kind}) part {index} \"{part}\": {rows} rows, numbered 0 to {last}"
+document_manifest_header_row: "  row 0 is the header: {row}"
+document_manifest_first_row: "  row 1 is the first data row: {row}"
+document_manifest_last_row: "  row {index} is the last data row: {row}"
+# What the rendering left out, stated in the one place that says what exists. Measured need
+# (J25, the user's real ~/Downloads, 2026-08-20): `step test.xlsx` is 18.62 MB and the manifest
+# said `4 parts, 28 rows` — all 28 of those rows are empty lines and the file's actual content
+# is 56 embedded PNGs. Every line here is a COUNT: an adjective ("some images") tells a model
+# nothing it can decide with, and silence tells it something false.
+document_manifest_package_media: "{document}: the file also holds {count} embedded file(s) ({what}) totalling {bytes} bytes, which no row can carry — this reader renders no image or embedded object"
+document_manifest_omitted_media: "  NOT in those rows: {count} embedded file(s), {bytes} bytes, anchored to this part"
+document_manifest_omitted_blank: "  {count} of those {rows} rows carry no cell value at all and render as an empty line"
+document_manifest_omitted_format: "  column(s) {where}: {count} cell(s) store a NUMBER under the date/time format {what} — this reader renders the stored serial number verbatim and does not convert it to a date; convert it with that format code if you need one"
+# J25-D3, the PDF reader. Two silences a page-addressable reader can produce that a
+# spreadsheet cannot: a page that rendered no row (a scan, or glyphs no font maps), and
+# characters dropped because the file states no mapping for them. An empty page and a page
+# nobody could read are different facts and the model must be able to tell them apart.
+document_manifest_omitted_unread_page: "  this part rendered NO row: {why}. It draws {count} image(s), {bytes} bytes, that no row can carry — no row means this reader recovered no text from the page, which is NOT the same as the page being empty, and there is no OCR here"
+document_manifest_unread_no_operator: "the page ran no text-showing operator at all, so nothing on it was ever text"
+document_manifest_unread_unmapped: "the page ran {show_ops} text-showing operator(s) and every one of the {unmapped} character(s) they showed came through a font that declares no character map, so this reader dropped them rather than guess at them"
+document_manifest_unread_whitespace: "the page ran {show_ops} text-showing operator(s) and this reader mapped every one of the {vouched} character(s) they showed, and every one of those characters is WHITESPACE — the text was recovered and it carries nothing, which is a fact about the page and not a failure of this reader"
+document_manifest_unread_no_character: "the page ran {show_ops} text-showing operator(s) that put no character on the page at all, neither one this reader could map nor one it had to drop"
+document_manifest_omitted_unmapped: "  {count} character(s) shown on this part are NOT in those rows: their codes came from font(s) with no /ToUnicode map ({what}), so the file stores indices into a font's own glyphs and says nowhere which character each glyph draws — this reader drops them rather than guess, because a guess here is indistinguishable from content"
+document_manifest_omitted_other: "  NOT in those rows: {count} {subject} ({what})"
+document_page_header: "{document} \"{part}\" rows {start}-{end} of {rows}; each line below begins with its own row number"
+document_page_next: "more rows follow: call document_read again with offset={next_offset}"
+document_page_end: "that was the last row of \"{part}\""
+document_page_truncated: "row {index} was too long for one page and was cut: {dropped} bytes dropped"
+document_unknown: "error: no document named {name}; this task has: {available}"
+document_offset_past_end: "error: offset {offset} is past the end of \"{part}\", which has {rows} rows numbered 0 to {last}"
+document_error: "error: {detail}"
+# `bantamkit_read` (the MCP reader, job43) reuses every `document_*` sentence above with the
+# path standing in for `{document}`. Two sentences are genuinely its own: its continuation
+# line names ITS tool, and a part it does not have is a fact about the file, not the task.
+bantamkit_read_page_next: "more rows follow: call bantamkit_read again with offset={next_offset}"
+bantamkit_read_unknown_part: "error: no part named \"{part}\" in {path}; it has: {available}"
+# The `paste` arm's system message (`docs/eval-data/2026-08-20-document-read-bar.md` §10.2,
+# PASTE_MAX_BYTES = 8621 under Amendment 1, 2026-08-20). The arm registers NO tools, so these four lines are the whole of
+# what the model is told ABOUT the corpus; the rows themselves are docread's own rendering,
+# unprefixed and unreformatted, so `paste` and `document_read` differ in DELIVERY and not in
+# content. Clause 4 makes stating the paste's own completeness part of the contract, and
+# `paste_truncated` says the missing rows are unreachable rather than leaving the model to
+# hunt for a tool that is not there: a paste that lets a truncated head read as the whole
+# sheet is a different, worse arm than the one the bar pre-registered.
+document_paste_preamble: "The following document content is attached to this task. Fields in a row are separated by tabs, rows are given in order, and row 0 of each part is its header."
+document_paste_part: "{document} ({kind}) part {index} \"{part}\": {rows} rows, numbered 0 to {last}; {shown} of them are shown below."
+document_paste_complete: "  rows 0 to {last_shown} are shown, which is every row of \"{part}\": this copy is COMPLETE."
+document_paste_truncated: "  rows 0 to {last_shown} are shown; rows {first_missing} to {last} of \"{part}\" are NOT shown and no tool is attached that can fetch them. This copy is PARTIAL."
+document_paste_none: "  no rows of \"{part}\" are shown and no tool is attached that can fetch them."
+# What the model is told when a tool CALL cannot be made or fails, rather than when a tool
+# answers with its own error (`document_unknown` and friends above are that). It lives here
+# for the reason the layer rule gives and for one measured reason: before 2026-08-20 the
+# dispatcher formatted this sentence itself and interpolated the raw exception, so a model
+# that sent one extra argument was handed
+# `_document_tools.<locals>.list_documents() got an unexpected keyword argument 'document'`
+# — a Python qualname, model-facing, owned by no asset and pinned by no golden. The
+# argument-shaped failures are intercepted before the handler is called now, so `{detail}`
+# carries a handler's OWN sentence and no longer a signature fragment.
+tool_failed: "error: {tool} failed: {detail}. fix the arguments and retry."
+tool_arguments: "error: {tool} does not take the arguments it was given. it takes: {accepts}. fix the arguments and retry."
+tool_arguments_none: "error: {tool} takes no arguments at all. call it with none and retry."
+# 2026-08-20, `RB-P86`. The sibling of the two above, one layer in. `select_declared_arguments`
+# drops keys the schema does not declare and type-checks nothing, so `llama3.2:3b` — which
+# emits a JSON-Schema FRAGMENT as the value of a declared parameter,
+# `{"document": {"description": "stock", "type": "string"}}` — got its dict straight through to
+# `docs.get(name)` and the model read `unhashable type: 'dict'`, thirteen times over 432 graded
+# runs. That is CPython's sentence about a hash table, not a tool's sentence about its own
+# arguments, and a 3b that receives it stops calling tools and answers that it cannot access
+# the workbook. What it is told now names the argument, the type the tool declares and the type
+# it was sent, so the next turn has something to correct. One frame for one or many, because
+# the count is not the thing the model has to act on.
+tool_argument_types: "error: {tool} was called with the wrong type of argument. {problems}. fix the arguments and retry."
+tool_argument_type: "{argument} must be type {expected}, not type {actual}"