bantamkit 0.29.1__tar.gz → 0.30.0__tar.gz

{bantamkit-0.29.1 → bantamkit-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bantamkit
-Version: 0.29.1
+Version: 0.30.0
 Summary: bantamweight tooling — harness primitives that lift small-model agents
 License-Expression: MIT
 Requires-Python: >=3.11

bantamkit-0.30.0/_assets/tools/memory_dream.json

@@ -0,0 +1,20 @@
+{
+  "name": "memory_dream",
+  "description": "Consolidate the memories the project layer and the machine-wide profile layer hold under the SAME NAME, and say exactly what changed. Byte-identical copies collapse to one; a pair that has diverged is UNIONED — every claim from both copies survives, never a winner-takes-all — and a relative date in a body is annotated with the day it resolves to against that fact's own mtime, never against today. The survivor stays in the writable project layer and the profile copy MOVES to that store's archive/: nothing is deleted and any consumed memory can be restored by name. This is a correctness pass, not a token saving: the profile index is derived at read time and is not loaded from a prompt, so consolidating it frees approximately no bytes — what it buys is one copy of a ruling instead of two that can disagree. It defaults to a DRY RUN because the profile store is machine-wide: a memory archived out of it stops answering for every other project on this machine that has no store of its own. Read the plan first, then call it again with dry_run false to apply it.",
+  "surfaces": ["mcp"],
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "dry_run": {
+        "type": "boolean",
+        "description": "Preview only. True (the default) performs every read, merge and projection and writes nothing. Pass false to apply the plan."
+      }
+    }
+  },
+  "output_schema": {
+    "properties": { "result": { "title": "Result", "type": "string" } },
+    "required": ["result"],
+    "type": "object",
+    "title": "memory_dreamOutput"
+  }
+}

bantamkit-0.30.0/_assets/tools/repo_map.json

@@ -0,0 +1,44 @@
+{
+  "name": "repo_map",
+  "description": "A ranked map of a source tree: every file's definitions, ordered by how central that file is to the files you name in `focus`, truncated to a byte budget. Call it when you are about to work on a file and want to know which OTHER files matter to it — the ports, the callers, the module it reaches through a private helper — rather than reading a directory listing and guessing. `focus` is the file or files you are editing, relative to `root` and POSIX-separated; they are excluded from the listing because you already have them open, and an empty focus gives plain centrality over the whole tree. This is a PRECISION pass and it is not a token saving: the gate this feature was supposed to clear was refuted by measurement — discovery is 0.114% of real prompt tokens, because 97.8% of the bill is cache_read — so a map does not make a session cheaper. What it buys is the right file found sooner. Nothing the scanner cannot read is dropped silently: every unread file resolves into a named omission (unknown-language, unreadable-bytes, size-cap, no-definitions, unreachable, per-file-cap, budget) counted in a footer that is NOT charged to the budget. The budget is UTF-8 BYTES of the listing, not tokens; there is no model tokenizer in either runtime and this tool will not pretend to one.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "type": "object",
+    "required": [
+      "root"
+    ],
+    "properties": {
+      "root": {
+        "type": "string",
+        "description": "Directory to map, absolute or relative to the server's working directory"
+      },
+      "focus": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "The files you are working on, relative to `root` and POSIX-separated. They are excluded from the listing. A name that is not a scanned source is ignored rather than refused."
+      },
+      "budget": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "UTF-8 bytes of listing to render; default 4000. The omission footer is not charged against it."
+      }
+    }
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "repo_mapOutput"
+  }
+}

{bantamkit-0.29.1 → bantamkit-0.30.0}/src/bantamkit/__init__.py

@@ -29,4 +29,4 @@ from bantamkit.structured import StructuredOutputError, extract_json, structured
 # 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.29.1"
+__version__ = "0.30.0"

bantamkit-0.30.0/src/bantamkit/docmanifest.py

@@ -0,0 +1,99 @@
+"""One rendering of a `docread.Document` as a manifest — for every caller that has one.
+
+Register entries (b) and (h), `docs/roadmap-toolbox.md` row 8. The entry dict
+`{document, kind, index, part, row_count, rows, omissions}` that `contract.document_manifest`
+takes was built by hand in `evalrun._document_tools` and again in `mcpserver.bantamkit_read`,
+with no shared helper and no test that the two produced the same bytes for the same file. They
+did not: the eval harness answered a zero-row part with `document_offset_past_end`, whose
+sentence reads `numbered 0 to -1`, while the MCP server answered `"<part>" in <path> has no
+rows`. One runtime disagreeing with itself about a file is not a two-runtime divergence and
+costs no `docs/porting.md` row — it just had to stop.
+
+**Why this is its own module and not a function on either caller.** `evalrun` is the
+measurement harness and `mcpserver` is Layer 5; making either import the other to reach a
+shared renderer would put the eval harness behind the MCP SDK's import, or the server behind
+`yaml` and the whole eval config surface. `docread` itself is the other candidate and is the
+better one on paper — but the entry dict is the *contract layer's* input shape, not the
+reader's, and `docread` is deliberately ignorant of who renders it. So the adapter between the
+two sits here: it imports `docread` for nothing at all (it reads attributes off whatever it is
+handed) and `contract` for the sentences, which is the direction the layer rule allows.
+
+The sentences are `contract`'s, with ONE exception this module inherited rather than chose:
+`document_no_rows` builds its text here, exactly as `mcpserver` built it inline before. It is
+not in `assets/contracts/default.yaml` beside every other model-facing sentence in this
+repository, and the port spells it a third time in `runtime-ts/src/mcp/server.ts`. Moving it
+into the contract asset is a two-runtime contract change and is registered, not done here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from bantamkit.contract import document_error, document_manifest
+
+__all__ = [
+    "document_no_rows",
+    "manifest_entries",
+    "package_entries",
+    "render_manifest",
+]
+
+
+def manifest_entries(document: str, doc: Any) -> list[dict]:
+    """The PART-grain entries for one document, keyed by the label the caller uses.
+
+    `document` is the caller's name for the file — a path on the MCP surface, a fixture name
+    in the eval harness — and it is the only thing about this rendering that legitimately
+    differs between the two. Everything else is a fact about the bytes.
+    """
+    return [
+        {
+            "document": document,
+            "kind": doc.kind,
+            "index": part.index,
+            "part": part.name,
+            "row_count": part.row_count,
+            "rows": part.rows,
+            "omissions": [o.as_dict() for o in part.omissions],
+        }
+        for part in doc.parts
+    ]
+
+
+def package_entries(document: str, doc: Any) -> list[dict]:
+    """The DOCUMENT-grain entries: what the container holds that belongs to no part.
+
+    Empty when the document has no such omissions, because `contract.document_manifest`
+    renders an entry without them byte-for-byte as it did before the disclosure existed —
+    which is what keeps the committed `document-read` rows where they are.
+    """
+    if not doc.omissions:
+        return []
+    return [{"document": document, "omissions": [o.as_dict() for o in doc.omissions]}]
+
+
+def render_manifest(documents: Iterable[tuple[str, Any]]) -> str:
+    """The manifest for one or many (label, `Document`) pairs, as one observation."""
+    parts: list[dict] = []
+    package: list[dict] = []
+    for document, doc in documents:
+        parts.extend(manifest_entries(document, doc))
+        package.extend(package_entries(document, doc))
+    return document_manifest(parts, package)
+
+
+def document_no_rows(part: str, document: str) -> str:
+    """The refusal for a part that has no rows at all — NOT an offset past the end.
+
+    `document_offset_past_end` over a zero-row part prints `numbered 0 to -1`, a range with
+    no members, and it says "offset N is past the end" about an offset of 0, which is not
+    past anything. No offset can be in range here, so the reply states that fact instead.
+
+    This exact string is pinned ON THE WIRE for both runtimes by
+    `tools/conformance/suites/wire.mjs` (`read: id 12`), which asserts it as a literal on each
+    side precisely so that both sides drifting back together would still fail. Changing it is
+    a two-runtime change plus that case; it is why this is the sentence that survived (b)/(h)
+    rather than the eval harness's.
+    """
+    return document_error(f'"{part}" in {document} has no rows')