bantamkit 0.27.0__py3-none-any.whl

bantamkit/statusline.py

@@ -0,0 +1,313 @@
+"""One line for a host's status bar, rendered from what a finished session left on disk.
+
+WHAT THIS IS AND WHY IT IS NOT A SIXTH HOST. `bantamkit_status` and its prompt
+(`docs/status.md`) are surfaces a host renders ON DEMAND: the model calls a tool, or a
+person invokes a slash command. This one is rendered WITHOUT ANYONE ASKING, on the
+host's own redraw path. That is the whole point of it, and it exists in **Claude Code
+only** -- `statusLine` is a key in `~/.claude/settings.json` and has no analogue in
+Claude Desktop, in Copilot CLI, or in either VS Code extension. It does not generalise
+and nothing here should be written as though it will.
+
+THREE PROPERTIES, EACH THE OPPOSITE OF A DEFECT ALREADY MEASURED IN THIS PRODUCT.
+
+* **It never starts a server.** Nothing in this module opens a transport, builds a
+  `Memory`, or imports `mcpserver`. It reads at most one file. A status bar that spawned
+  an MCP server per redraw would cost more than everything it reports on.
+* **It never fails loudly.** No traceback, no stderr, no empty line. `status_line` is
+  total: every path returns a string, and the outermost `except Exception` turns a
+  surprise into the UNKNOWN state. Job39 measured the alternative twice -- the packaged
+  `bin` dies with a raw Node stack trace, and the default memory store resolves against
+  `cwd` so a GUI host launched at `/` kills the server -- and both of those are what a
+  redraw path must not reproduce. **Unknown is a state to render, not an error to raise.**
+* **It reads what is already true.** No clock, no probe, no heartbeat, no timer.
+
+WHY THE EVENT LOG AND NOT `--mcp-report`. Two sources were defensible and a third would
+have been an invention. `--mcp-report` (`docs/mcpreport.md`) reads the event log too,
+but it reaches it through the HOST's log first. Measured on this machine 2026-08-24, 25
+runs each: bare `node -e 0` p50 **18.1 ms**, `--statusline` p50 **69.4 ms**,
+`--mcp-report` p50 **88.6 ms** over 22 slug directories, 112 files and 1674 records.
+
+The 19 ms is the smaller half of the reason. The larger half is that **source A is
+unbounded and bantamkit does not own it**: the host writes it, never rotates it, and it
+was 1533 records when `docs/eventlog.md` was written and 1674 five days later. A redraw
+path may not have its cost set by a file another program grows. Source B is bounded by
+its own rotation rule at 1 MiB, and this reader bounds it again at `TAIL_BYTES`.
+
+The third reason is shape. `--mcp-report` prints forty lines; a status bar takes one, so
+an adapter over it would have to PARSE the report -- a third representation of a state
+that already has two. `bantamkit-mcp --statusline` renders the one line directly.
+
+WHAT THE LINE CAN AND CANNOT SAY. The four conditions in `docs/status.md` are computed
+by a RUNNING server, and one of them (`event-log-unwritable`) is process state that no
+outside reader can see at all. This module does not recompute them and does not pretend
+to. What it has is the event log's own closed `outcome` vocabulary, and three of those
+values name a failure of the server's own state rather than a property of the caller's
+input -- see `ADVERSE`. A window that contains one of them is DEGRADED.
+
+METADATA ONLY, THE SAME RULE THE LOG ITSELF IS UNDER, AND HERE IT IS STRUCTURAL. The
+parser below keeps exactly two strings per record: a `tool` that matched
+`^[a-z0-9_]{1,64}$` and an `outcome` that is a member of `OUTCOMES`. `detail` is never
+read, `ts` is never read, `v` is never read. There is no field on the parsed record that
+could hold borrowed text, so no code path can print one -- the same guard
+`mcpreport.py` uses against the host's log, applied here to bantamkit's own, because the
+log is a file on disk that anything can append to.
+
+THE CROSS-RUNTIME CONTRACT IS `docs/statusline.md`. `runtime-ts/src/statusline.ts`
+emits the same bytes and `tools/conformance/suites/statusline.mjs` compares the two as
+processes. Change the rendering there and in both runtimes, or not at all.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from bantamkit.mcpreport import resolve_event_log_path
+
+#: How many of the log's most recent records the line describes.
+#:
+#: The bar answers "what is happening now", not "what has ever happened" -- that second
+#: question is `--mcp-report`'s and it reads both generations to answer it. A fixed
+#: window also makes the two counts on the line bounded, so the rendered string cannot
+#: grow with the size of somebody's log.
+WINDOW = 50
+
+#: The most bytes read off the end of the log, ever.
+#:
+#: The log rotates itself at 1 MiB (`eventlog.CAP_BYTES`), so under bantamkit's own
+#: default this branch never fires. It fires when `BANTAMKIT_EVENT_LOG` names a LITERAL
+#: path -- an operator can point that at anything, and a redraw path may not be at the
+#: mercy of how big that anything is. A partial first line is discarded, so the tail is
+#: parsed identically whether or not it was truncated.
+#:
+#: The rotated generation `<path>.1` is NOT read at all. It is history, and history is
+#: the analyst's job; a bar that reached back into it would report a fault the current
+#: session has already replaced.
+TAIL_BYTES = 262144
+
+#: Every `outcome` `docs/eventlog.md` defines, and nothing else is renderable.
+#:
+#: A closed set, not a shape check: this is the guard that keeps an appended line from
+#: putting text of its own choosing on the operator's status bar.
+OUTCOMES = frozenset(
+    {
+        # memory_save
+        "saved",
+        "duplicate",
+        "refused-validation",
+        "refused-budget",
+        # memory_recall
+        "answered",
+        "empty-no-match",
+        "empty-unreadable-layer",
+        "empty-nothing-saved",
+        # validate_json
+        "valid",
+        "invalid",
+        # shiftwork_clock_in
+        "brief",
+        "escalate",
+        "success",
+        "error",
+        # shiftwork_clock_out / shiftwork_status
+        "ok",
+        "status",
+        # build_identity
+        "complete",
+        "partial",
+        # any handler that fell over
+        "raised",
+    }
+)
+
+#: The three outcomes that mean BANTAMKIT is in trouble, rather than the caller's input.
+#:
+#: * `raised` -- a handler fell over. There is no reading of that which is fine.
+#: * `refused-budget` -- the store's index budget stopped a save. This is the same
+#:   pressure `docs/status.md`'s `index-budget-low` warns about one step earlier; by the
+#:   time it is in the log the refusal has already happened.
+#: * `empty-unreadable-layer` -- a bound memory layer could not be listed. That is
+#:   `docs/status.md`'s `memory-layer-unreadable`, observed from the outside.
+#:
+#: Deliberately NOT here: `refused-validation` (the caller handed over a bad memory),
+#: `error` and `escalate` (the shiftwork register composing a refusal about a checkpoint,
+#: which is the tool working), `invalid` (a schema said no, which is the answer), and
+#: every `empty-*` that is simply nothing to recall. A bar that turned orange because a
+#: user typo'd a fact name is a bar the user learns to ignore.
+ADVERSE = ("raised", "refused-budget", "empty-unreadable-layer")
+
+#: The host's log validates tool names with exactly this and so does `mcpreport.py`.
+_TOOL = re.compile(r"^[a-z0-9_]{1,64}$")
+
+#: U+1F7E2 / U+1F7E0 are the same two `docs/status.md` pins; U+26AA is this file's.
+ACTIVE = "bantamkit Active 🟢"
+DEGRADED = "bantamkit Degraded 🟠"
+UNKNOWN = "bantamkit Unknown ⚪"
+
+#: The separator. One space, U+00B7, one space.
+SEP = " · "
+
+#: Every reason the UNKNOWN state can carry. A closed set, like `OUTCOMES`.
+OFF = "event log off"
+ABSENT = "no event log yet"
+UNREADABLE = "event log unreadable"
+EMPTY = "event log empty"
+SURPRISE = "state unavailable"
+
+
+@dataclass(frozen=True)
+class Reading:
+    """What one look at the log found. Integers and closed-vocabulary tokens only."""
+
+    state: str
+    """`active`, `degraded` or `unknown`."""
+
+    events: int = 0
+    """Records in the window. `0` in every unknown state."""
+
+    problems: int = 0
+    """Records in the window whose outcome is in `ADVERSE`."""
+
+    tool: str = ""
+    """The tool of the record the line names, validated against `_TOOL`."""
+
+    outcome: str = ""
+    """That record's outcome, a member of `OUTCOMES`."""
+
+    reason: str = ""
+    """Why the state is unknown. Empty otherwise."""
+
+
+def _unknown(reason: str) -> Reading:
+    return Reading(state="unknown", reason=reason)
+
+
+def read_tail(path: Path) -> bytes:
+    """The last `TAIL_BYTES` of `path`, with a partial leading line discarded.
+
+    Opened in BINARY mode and never decoded as a whole: the log is UTF-8 by contract but
+    a truncated tail can start mid-codepoint, and a `UnicodeDecodeError` on the whole
+    buffer would throw away every intact record behind it. Each line is decoded on its
+    own inside `parse`, so one bad line costs one record.
+
+    Raises `OSError` -- the caller turns that into a rendered state.
+    """
+    with open(path, "rb") as handle:
+        handle.seek(0, 2)
+        size = handle.tell()
+        start = size - TAIL_BYTES if size > TAIL_BYTES else 0
+        handle.seek(start)
+        data = handle.read()
+    if start:
+        cut = data.find(b"\n")
+        data = b"" if cut < 0 else data[cut + 1 :]
+    return data
+
+
+def parse(data: bytes) -> list[tuple[str, str]]:
+    """`(tool, outcome)` for every line that is a record this module is willing to render.
+
+    THIS IS THE LEAK GUARD AND IT IS STRUCTURAL, NOT A FILTER. What comes back is a list
+    of pairs of validated tokens; there is no field here that can hold a path, a memory
+    body, a query, or a `detail` value, so no later code CAN print one. A record with an
+    unknown outcome, a tool that is not `^[a-z0-9_]{1,64}$`, a non-object body, or
+    unparseable JSON is dropped whole -- it is not rendered under some fallback spelling,
+    because a fallback spelling is a way for the file's own bytes to reach the bar.
+    """
+    pairs: list[tuple[str, str]] = []
+    for raw in data.split(b"\n"):
+        if not raw:
+            continue
+        try:
+            record = json.loads(raw.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            continue
+        if not isinstance(record, dict):
+            continue
+        tool = record.get("tool")
+        outcome = record.get("outcome")
+        if not isinstance(tool, str) or not isinstance(outcome, str):
+            continue
+        if _TOOL.match(tool) is None or outcome not in OUTCOMES:
+            continue
+        pairs.append((tool, outcome))
+    return pairs
+
+
+def summarise(pairs: list[tuple[str, str]]) -> Reading:
+    """The window's state: degraded if it holds an `ADVERSE` outcome, else active.
+
+    The record the line NAMES is the most recent adverse one when degraded, and simply
+    the most recent one when active. Naming the last record while degraded would hide the
+    fault behind whatever happened to run after it.
+    """
+    window = pairs[-WINDOW:]
+    if not window:
+        return _unknown(EMPTY)
+    problems = [pair for pair in window if pair[1] in ADVERSE]
+    tool, outcome = problems[-1] if problems else window[-1]
+    return Reading(
+        state="degraded" if problems else "active",
+        events=len(window),
+        problems=len(problems),
+        tool=tool,
+        outcome=outcome,
+    )
+
+
+def probe(
+    env: dict[str, str], store: str | None = None, start: str | None = None
+) -> Reading:
+    """Resolve the log the same way the server would, read it, and summarise it.
+
+    `resolve_event_log_path` is reused rather than reimplemented so there is ONE
+    vocabulary for `BANTAMKIT_EVENT_LOG` in this runtime and not a second copy that can
+    drift. It DESIGNATES a store path without creating one, so drawing a status bar never
+    brings a memory store into existence.
+    """
+    try:
+        path = resolve_event_log_path(env, store=store, start=start)
+    except Exception:  # noqa: BLE001 - a redraw path renders, it does not raise
+        return _unknown(UNREADABLE)
+    if path is None:
+        return _unknown(OFF)
+    try:
+        data = read_tail(path)
+    except FileNotFoundError:
+        return _unknown(ABSENT)
+    except OSError:
+        return _unknown(UNREADABLE)
+    return summarise(parse(data))
+
+
+def render(reading: Reading) -> str:
+    """The one line, without its newline. Never empty, never multi-line.
+
+    An empty line would make the host's bar flicker between one row and none, which is
+    worse than any wording; that is why the unknown state has a rendering at all.
+    """
+    if reading.state == "unknown":
+        return f"{UNKNOWN}{SEP}{reading.reason}"
+    events = f"{reading.events} event" + ("" if reading.events == 1 else "s")
+    named = f"{reading.tool} {reading.outcome}"
+    if reading.state == "degraded":
+        problems = f"{reading.problems} problem" + ("" if reading.problems == 1 else "s")
+        return f"{DEGRADED}{SEP}{events}{SEP}{problems}{SEP}{named}"
+    return f"{ACTIVE}{SEP}{events}{SEP}{named}"
+
+
+def status_line(
+    env: dict[str, str], store: str | None = None, start: str | None = None
+) -> str:
+    """The total entry point: a string for every input, including inputs that are wrong.
+
+    The `except Exception` is not laziness, it is the contract. This runs on somebody's
+    redraw path with no operator watching; the failure this must not have is a traceback
+    where a status bar should be.
+    """
+    try:
+        return render(probe(env, store=store, start=start))
+    except Exception:  # noqa: BLE001 - see the docstring
+        return f"{UNKNOWN}{SEP}{SURPRISE}"

bantamkit/structured.py

@@ -0,0 +1,125 @@
+"""JSON-Schema-enforced output: validate, retry with a pointed error, bounded budget."""
+
+from __future__ import annotations
+
+import jsonschema
+
+from bantamkit.agent import Agent, _supports_response_format, response_format_for
+from bantamkit.client import BantamError, Message, ModelClient
+from bantamkit.contract import (
+    extract_json,
+    json_answer_retry,
+    parse_error_message,
+    schema_instruction,
+    schema_retry_feedback,
+    validation_error_message,
+)
+from bantamkit.profile import default as profile_default
+
+__all__ = ["JsonAnswerGate", "StructuredOutputError", "extract_json", "structured"]
+
+
+class StructuredOutputError(BantamError):
+    """No schema-valid output within the retry budget.
+
+    Carries the transcript up to the raise, same payload and same reason as
+    `MaxTurnsExceeded`: when a schema gate gives up it raises from inside the
+    agent's post-hook chain, and without a slot for the transcript every
+    `schema-exhausted` run wrote `{"output": null, "messages": []}` — the runs
+    most worth diagnosing recording nothing. The agent fills the slot in
+    (`Agent.run`); a raiser that already has the transcript may pass it here.
+    """
+
+    def __init__(self, message: str, messages: list[Message] | None = None):
+        super().__init__(message)
+        self.messages: list[Message] = list(messages or [])
+
+
+def structured(
+    client: ModelClient, prompt: str, schema: dict, *, max_retries: int | None = None
+) -> dict:
+    """Tier 1 constrains the decode, tiers 2-3 (instruction + validate/retry) still gate.
+
+    A constrained server makes the retries rare; a server that ignores or rejects
+    `response_format` changes nothing, because enforcement is only ever as good as
+    the server and validation is what actually decides.
+    """
+    if max_retries is None:
+        max_retries = profile_default("structured", "max_retries")
+    response_format = response_format_for(schema)
+    messages = [
+        Message(role="system", content=schema_instruction(schema)),
+        Message(role="user", content=prompt),
+    ]
+    error = "no attempts made"
+    for _ in range(max_retries):
+        # Re-checked per attempt: a 400 on attempt 1 silently drops the tier from here on.
+        if _supports_response_format(client):
+            resp = client.chat(messages, response_format=response_format)
+        else:
+            resp = client.chat(messages)
+        content = resp.message.content or ""
+        try:
+            data = extract_json(content)
+            jsonschema.validate(data, schema)
+            return data
+        except ValueError as e:
+            error = parse_error_message(e)
+        except jsonschema.ValidationError as e:
+            where = "/".join(str(p) for p in e.absolute_path) or "root"
+            error = validation_error_message(where, e.message)
+        messages.append(resp.message)
+        messages.append(Message(role="user", content=schema_retry_feedback(error)))
+    raise StructuredOutputError(
+        f"no valid output after {max_retries} attempts; last error: {error}"
+    )
+
+
+class JsonAnswerGate:
+    """Rescue the failure the 7b transcripts actually showed: right content, no JSON.
+
+    Fires only when the final answer has no extractable JSON at all. A parseable
+    answer that violates a schema is `SchemaGate`'s business; a parseable answer
+    that is simply wrong is the scorer's. This gate exists for the measured
+    mechanism — the model detours, answers in fluent prose, and the "ONLY this
+    JSON" instruction is a turn too far away — and it asks for exactly one
+    restatement.
+
+    Fail-open by construction: once the budget is spent the answer passes through
+    untouched. A gate that raised here would convert a scorable wrong answer into
+    an exception, and scoring must stay the judge.
+
+    `max_attempts` counts retries the gate may spend (default 1 = one restatement),
+    unlike `SchemaGate`, whose budget counts answers including the last rejected one.
+    """
+
+    def __init__(self, max_attempts: int | None = None):
+        self.max_attempts = (
+            max_attempts
+            if max_attempts is not None
+            else profile_default("json_answer", "max_attempts")
+        )
+        self.retries_used = 0
+        self._attempts = 0
+
+    def setup(self, agent: Agent) -> None:
+        self.retries_used = 0
+        self._attempts = 0
+        agent.add_post_hook(self)
+
+    def __call__(self, task: str, output: str) -> str | None:
+        # The budget is latched for the whole run (reset only in setup): when a
+        # later hook (e.g. a critique gate) keeps the run alive past this gate's
+        # fail-open, the budget must not re-arm and interleave retries with the
+        # critic's feedback.
+        try:
+            extract_json(output)
+        except ValueError:
+            pass
+        else:
+            return None
+        self._attempts += 1
+        if self._attempts > self.max_attempts:
+            return None
+        self.retries_used += 1
+        return json_answer_retry()

bantamkit/textutil.py

@@ -0,0 +1,30 @@
+"""Byte-budget truncation shared by the core loop and contract rendering."""
+
+from __future__ import annotations
+
+
+def truncate_counted(text: str, budget: int) -> tuple[str, int]:
+    """`truncate`, plus the number of bytes it dropped. Zero when nothing was cut.
+
+    C-6, 2026-08-19. The cut was already announced, but IN BAND — inside the string
+    handed to the model, as `[truncated N bytes]`. The number was known here and thrown
+    away, so nothing outside the model's own context could tell a run whose observations
+    were cut from one whose were not. RB-P51's shape: a run that silently proceeded is
+    not the same run as one that reported what it dropped.
+
+    The second return value is what makes it a column. It is deliberately NOT parsed back
+    out of the marker by a caller: that would be a second transcription of one rule and a
+    check over the two would be a tautology (RB-P47).
+    """
+    raw = text.encode()
+    if len(raw) <= budget:
+        return text, 0
+    dropped = len(raw) - budget
+    kept = raw[:budget].decode(errors="ignore")
+    return f"{kept}\n[truncated {dropped} bytes]", dropped
+
+
+def truncate(text: str, budget: int) -> str:
+    """Byte-identical to what it always returned. Callers that want the count call
+    `truncate_counted`; `contract.py` and `filegraph.py` do not and are unchanged."""
+    return truncate_counted(text, budget)[0]

bantamkit-0.27.0.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.5
+Name: bantamkit
+Version: 0.27.0
+Summary: bantamweight tooling — harness primitives that lift small-model agents
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: hatchling>=1.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# bantamkit
+
+Harness primitives that lift small-model agents: a per-person memory store, JSON
+validation, shift-work accounting, a document reader, and a skill-catalogue
+auditor — served to any MCP host over stdio.
+
+This is the **Python** distribution. There is a second, independent
+implementation of the same surface on npm as
+[`bantamkit-mcp`](https://www.npmjs.com/package/bantamkit-mcp), written in pure
+Node. The two share a memory store on disk and are held to the same answers by a
+conformance suite, so you can install whichever one your host makes easy. What
+the two do *not* agree on is written down in
+[`docs/porting.md`](https://github.com/Ink01101011/bantamkit/blob/main/docs/porting.md)
+and summarised at the bottom of this page.
+
+## Install and run
+
+```bash
+pipx run --spec "bantamkit[mcp]" bantamkit-mcp --assets-root
+```
+
+or into an environment you keep:
+
+```bash
+pip install "bantamkit[mcp]"
+bantamkit-mcp --help
+```
+
+The `[mcp]` extra pulls the MCP SDK. Without it you still get the library and the
+operator CLI, but not the server.
+
+The uv equivalent is `uvx --from "bantamkit[mcp]" bantamkit-mcp`. uv is not
+installed on the machine this README was measured on, so unlike every other
+command here that one is the documented form rather than a measured one.
+
+### Connect it to a host
+
+Every host below runs the same command; only the file and the key around it change. If
+you installed with `pip` into an environment you keep, replace the `command`/`args` pair
+with the absolute path to the `bantamkit-mcp` console script in that environment.
+
+**Claude Code** — one command, no file to edit. `-s user` makes it available in every
+project; drop it for this project only.
+
+```bash
+claude mcp add bantamkit -s user -- pipx run --spec "bantamkit[mcp]" bantamkit-mcp
+```
+
+**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`
+on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Top-level key
+`mcpServers`; each entry takes `command`, `args` and an optional `env`.
+
+```json
+{"mcpServers": {"bantamkit": {"command": "pipx", "args": ["run", "--spec", "bantamkit[mcp]", "bantamkit-mcp"]}}}
+```
+
+**GitHub Copilot in VS Code** — `.vscode/mcp.json` for one workspace, or the user
+profile via the **MCP: Open User Configuration** command. Note the top-level key is
+`servers`, not `mcpServers`.
+
+```json
+{"servers": {"bantamkit": {"type": "stdio", "command": "pipx", "args": ["run", "--spec", "bantamkit[mcp]", "bantamkit-mcp"]}}}
+```
+
+**Cursor** — `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` globally. Back
+to `mcpServers`.
+
+```json
+{"mcpServers": {"bantamkit": {"command": "pipx", "args": ["run", "--spec", "bantamkit[mcp]", "bantamkit-mcp"]}}}
+```
+
+**Anything else that speaks MCP over stdio** runs the console script and talks JSON-RPC
+on its stdin and stdout. Nothing about this package is host-specific.
+
+The Claude Code and Claude Desktop forms were taken from this machine — `claude mcp add
+--help` and an existing config file. The VS Code and Cursor forms are from those
+projects' own documentation, not from a host installed here.
+
+Point `--start` at a directory to choose where project-store discovery begins, or
+`--store` at a single path to disable layering entirely. Do not reach for
+`--store` by reflex: the default is layered, and the layering is most of the
+value.
+
+## What it serves
+
+Eleven tools, measured off a wheel installed into an empty virtualenv:
+
+| tool | what it does |
+|---|---|
+| `memory_save` | store one durable fact, deduped and budgeted |
+| `memory_recall` | retrieve facts matching a query |
+| `memory_compact` | archive the stalest facts to fit the index budget |
+| `validate_json` | validate a document against a JSON Schema |
+| `bantamkit_read` | read a document — text, office formats, pdf |
+| `skill_audit` | audit a skill catalogue for findings |
+| `shiftwork_clock_in` | open a unit of work and get its brief |
+| `shiftwork_clock_out` | close a unit with status and accounting |
+| `shiftwork_status` | report the open cursor |
+| `bantamkit_status` | report store health against its budget |
+| `build_identity` | report the fingerprint of the source on disk |
+
+`build_identity` describes the tree on disk, not the code currently executing —
+useful precisely when a machine carries two installs under one name.
+
+## Requirements
+
+Python 3.11 or newer. Three runtime dependencies — `httpx`, `jsonschema`,
+`pyyaml` — plus `mcp` under the `[mcp]` extra.
+
+## The asset pack
+
+Contracts, schemas, eval tasks, rubrics and tool manifests ship inside the
+package and are located at import time:
+
+```bash
+bantamkit-mcp --assets-root
+```
+
+It prints the resolved directory and its file count. A build that cannot find the
+pack fails rather than producing an artifact without it — that refusal is
+deliberate, because the silent version of it shipped once.
+
+`BANTAMKIT_ASSETS` overrides the location.
+
+## The operator CLI
+
+Memory-store maintenance is a separate surface from the agent-facing tools, and
+it is not served over MCP:
+
+```bash
+python -m bantamkit.memory status     # index size, budget, headroom, archives
+python -m bantamkit.memory lint       # exit 1 if malformed or over budget
+python -m bantamkit.memory compact    # archive the stalest facts
+python -m bantamkit.memory archive <name>
+python -m bantamkit.memory restore <name>
+```
+
+`archive` moves a fact out of the store without deleting it; `restore` brings it
+back by name.
+
+## Sharing a store with the Node server
+
+Both distributions read and write the same on-disk format, so one store can be
+served by either. That is also why a surface present in one and absent from the
+other is not merely a coverage gap — it is a way for two servers to disagree
+about one person's data. Every feature lands in both implementations in the same
+change, and a conformance case compares the two answers before it counts as
+ported.
+
+## Where the two implementations differ, on purpose
+
+- **This side reads pdf, `.doc` and `.rtf`; the Node side refuses them by name.**
+  PDF is read by a stdlib reader written for this project; real OLE2 `.doc` and
+  `.rtf` go through `/usr/bin/textutil`, a macOS built-in that is probed at every
+  call and refused by name where it is absent.
+- **The operator CLI is spelled differently**, and it shows in help text and
+  error messages: `python -m bantamkit.memory` here against `bantamkit-memory`
+  there. There is no third spelling — a pure-npm install has no Python in it, and
+  CPython does not install that console script.
+- **`build_id` hashes the executing tree**, and the two runtimes are two trees, so
+  it differs by construction. `assets_digest` is identical, and that is the one
+  that carries meaning.
+
+Each of these is recorded in the divergence table with a conformance case pinning
+the wording, so the difference cannot drift unnoticed.
+
+## Development
+
+```bash
+git clone https://github.com/Ink01101011/bantamkit
+cd bantamkit
+python -m venv .venv && .venv/bin/pip install -e "runtime-py[dev,mcp]"
+.venv/bin/python -m pytest runtime-py/tests -q
+.venv/bin/ruff check runtime-py
+```
+
+The cross-runtime gate needs Node:
+
+```bash
+node tools/conformance/run.mjs --all
+```
+
+## Links
+
+- Source: https://github.com/Ink01101011/bantamkit
+- The Node distribution: https://www.npmjs.com/package/bantamkit-mcp
+- Install notes: [`docs/install.md`](https://github.com/Ink01101011/bantamkit/blob/main/docs/install.md)
+- What the two runtimes disagree about: [`docs/porting.md`](https://github.com/Ink01101011/bantamkit/blob/main/docs/porting.md)
+
+MIT.