From ce162e7a58406f191dc878b2148623f691d25907 Mon Sep 17 00:00:00 2001 From: Steve Brown Date: Fri, 13 Nov 2026 14:06:49 -0500 Subject: [PATCH 1/2] docs: embed native semantic search and context demo --- README.md | 8 + docs/demos/terminal.md | 32 ++++ docs/demos/terminal/demo.cast | 3 + docs/demos/terminal/demo.svg | 34 +++++ docs/demos/terminal/demo.tape.json | 46 ++++++ docs/demos/terminal/fixture/totals.py | 3 + docs/demos/terminal/manifest.json | 57 ++++++++ docs/demos/terminal/prepare.py | 43 ++++++ docs/demos/terminal/render.py | 201 ++++++++++++++++++++++++++ docs/demos/terminal/transcript.txt | 18 +++ 10 files changed, 445 insertions(+) create mode 100644 docs/demos/terminal.md create mode 100644 docs/demos/terminal/demo.cast create mode 100644 docs/demos/terminal/demo.svg create mode 100644 docs/demos/terminal/demo.tape.json create mode 100644 docs/demos/terminal/fixture/totals.py create mode 100644 docs/demos/terminal/manifest.json create mode 100644 docs/demos/terminal/prepare.py create mode 100644 docs/demos/terminal/render.py create mode 100644 docs/demos/terminal/transcript.txt diff --git a/README.md b/README.md index 561c9b6..b4e3223 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,14 @@ greeting:1-2 Bobbin found a parsed function, with its source range, in the index you just built. See the [quick start](https://scbrown.github.io/bobbin/getting-started/quick-start.html) for semantic search. +![Animated terminal: Bobbin finds a function by meaning and assembles its source context](docs/demos/terminal/demo.svg) + +This 20-second recording uses a small local Python fixture. Semantic search +finds the invoice-total function; context returns its source. The optional +graph store is unavailable, and the recording retains that warning. +[Read the transcript](docs/demos/terminal/transcript.txt) or +[reproduce the recording](docs/demos/terminal.md). + ## On your own code Run `bobbin init` and `bobbin index` from your repository first. diff --git a/docs/demos/terminal.md b/docs/demos/terminal.md new file mode 100644 index 0000000..1686268 --- /dev/null +++ b/docs/demos/terminal.md @@ -0,0 +1,32 @@ +# Find code by meaning, then read its context + +This recording runs native Bobbin 0.36.1 at commit +`667a680d393c0d9e5347af7fc9d71472c00a494e` against a local public Python fixture. +The manifest pins the executable and every input. Semantic search returns +`calculate_total`; context displays its three source lines. The optional Quipu +store is unavailable, so its single warning remains visible. This does not +claim graph ranking occurred. + +The two reading holds total 20 seconds. Actual command execution durations +are recorded separately. The static transcript is an accessible fallback; +the last SVG frame remains visible when animation is disabled. + +The vendored renderer is byte-identical to Tambo's shared recorder at +`b0765b5d8f16a6a26acb3595552f17826d965b44`, +SHA-256 `bebbe000565314f18a58731f2a1a4690577db127b3673fa10a45ce74eef0f23c`. +It refuses possible private paths and credentials rather than filtering output. + +## Reproduce + +Use Python 3, the recorded Bobbin version and a compatible ONNX runtime. +Prepare a new, absent workspace with the helper. It creates an isolated HOME +and index, and indexing may download the embedding model. It does not install +hooks or connect to a graph. + +```sh +python3 docs/demos/terminal/prepare.py /tmp/bobbin-terminal-demo --tool "$(command -v bobbin)" +python3 docs/demos/terminal/render.py docs/demos/terminal/demo.tape.json --workspace /tmp/bobbin-terminal-demo --tool bobbin="$(command -v bobbin)" --output /tmp/bobbin-terminal-render +``` + +The fixture and model cache stay inside that disposable workspace. No existing +index or user configuration is read. Use a fresh directory for each capture. diff --git a/docs/demos/terminal/demo.cast b/docs/demos/terminal/demo.cast new file mode 100644 index 0000000..bda02fd --- /dev/null +++ b/docs/demos/terminal/demo.cast @@ -0,0 +1,3 @@ +{"version": 2, "width": 65, "height": 14, "title": "Bobbin | find code and assemble context", "env": {"TERM": "dumb"}} +[0.0, "o", "\u001b[2J\u001b[H$ bobbin search 'calculate invoice total' --mode semantic --limit\r\n 2\r\n\u2713 Found 1 results for: calculate invoice total (semantic)\r\n\r\n1. totals.py:1 (calculate_total)\r\n [totals-example] function python \u00b7 lines 1-3 \u00b7 score 0.6736\r\n"] +[10.0, "o", "\u001b[2J\u001b[H$ bobbin context 'calculate invoice total' --budget 40\r\n\u2713 Context for: calculate invoice total\r\n 1 files, 1 chunks (3/40 lines)\r\n\r\n--- totals.py [direct, score: 1.0000] ---\r\n calculate_total (function), lines 1-3\r\n def calculate_total(amounts):\r\n \"\"\"Calculate the total amount for an invoice.\"\"\"\r\n return sum(amounts)\r\n\r\n ! PPR enabled but Quipu store unavailable; continuing without \r\ngraph ranking. Use --verbose for details.\r\n"] diff --git a/docs/demos/terminal/demo.svg b/docs/demos/terminal/demo.svg new file mode 100644 index 0000000..c0dd030 --- /dev/null +++ b/docs/demos/terminal/demo.svg @@ -0,0 +1,34 @@ + +Bobbin | find code and assemble context +Native semantic retrieval and context from a small local Python fixture; optional graph ranking is unavailable. The animation repeats. The adjacent transcript provides a static alternative. + + + + + +Bobbin | find code and assemble context + + +$ bobbin search 'calculate invoice total' --mode semantic --limit + 2 +✓ Found 1 results for: calculate invoice total (semantic) + +1. totals.py:1 (calculate_total) + [totals-example] function python · lines 1-3 · score 0.6736 + + + +$ bobbin context 'calculate invoice total' --budget 40 +✓ Context for: calculate invoice total + 1 files, 1 chunks (3/40 lines) + +--- totals.py [direct, score: 1.0000] --- + calculate_total (function), lines 1-3 + def calculate_total(amounts): + """Calculate the total amount for an invoice.""" + return sum(amounts) + + ! PPR enabled but Quipu store unavailable; continuing without +graph ranking. Use --verbose for details. + + diff --git a/docs/demos/terminal/demo.tape.json b/docs/demos/terminal/demo.tape.json new file mode 100644 index 0000000..e2e0934 --- /dev/null +++ b/docs/demos/terminal/demo.tape.json @@ -0,0 +1,46 @@ +{ + "title": "Bobbin | find code and assemble context", + "description": "Native semantic retrieval and context from a small local Python fixture; optional graph ranking is unavailable.", + "width": 1100, + "height": 700, + "font_size": 24, + "line_height": 32, + "inputs": [ + "totals.py" + ], + "steps": [ + { + "tool": "bobbin", + "args": [ + "search", + "calculate invoice total", + "--mode", + "semantic", + "--limit", + "2" + ], + "requires": [ + "calculate_total", + "semantic" + ], + "hold": 10, + "timeout": 120 + }, + { + "tool": "bobbin", + "args": [ + "context", + "calculate invoice total", + "--budget", + "40" + ], + "requires": [ + "calculate_total", + "graph ranking" + ], + "allow_stderr": true, + "hold": 10, + "timeout": 120 + } + ] +} diff --git a/docs/demos/terminal/fixture/totals.py b/docs/demos/terminal/fixture/totals.py new file mode 100644 index 0000000..0da14c6 --- /dev/null +++ b/docs/demos/terminal/fixture/totals.py @@ -0,0 +1,3 @@ +def calculate_total(amounts): + """Calculate the total amount for an invoice.""" + return sum(amounts) diff --git a/docs/demos/terminal/manifest.json b/docs/demos/terminal/manifest.json new file mode 100644 index 0000000..effda28 --- /dev/null +++ b/docs/demos/terminal/manifest.json @@ -0,0 +1,57 @@ +{ + "theme": "stack-terminal-24", + "versions": { + "bobbin": "bobbin 0.36.1 (667a680d393c0d9e5347af7fc9d71472c00a494e)" + }, + "binary_sha256": { + "bobbin": "d56bd5e01a82b64269c106f0b68692dc6c225bc12ad9bafb24dce1c61be57937" + }, + "version_args": { + "bobbin": [ + "--version" + ] + }, + "inputs_sha256": { + "render.py": "bebbe000565314f18a58731f2a1a4690577db127b3673fa10a45ce74eef0f23c", + "tape": "e97f346a9ebb25a1ae7f8896e6c51b7e34400558acffce1c23f2e332e62cd3f2", + "totals.py": "8b22236231ed7b92250a818a749d26334e3201f87d28a9e6bcdb38ebdec7ea19" + }, + "duration_seconds": 20.0, + "timeline": "deliberate reading holds; execution times recorded separately", + "frames_checked": 2, + "commands": [ + { + "tool": "bobbin", + "args": [ + "search", + "calculate invoice total", + "--mode", + "semantic", + "--limit", + "2" + ], + "exit": 0, + "seconds": 0.261712, + "stdout": "\u2713 Found 1 results for: calculate invoice total (semantic)\n\n1. totals.py:1 (calculate_total)\n [totals-example] function python \u00b7 lines 1-3 \u00b7 score 0.6736\n\n", + "stderr": "" + }, + { + "tool": "bobbin", + "args": [ + "context", + "calculate invoice total", + "--budget", + "40" + ], + "exit": 0, + "seconds": 0.214701, + "stdout": "\u2713 Context for: calculate invoice total\n 1 files, 1 chunks (3/40 lines)\n\n--- totals.py [direct, score: 1.0000] ---\n calculate_total (function), lines 1-3\n def calculate_total(amounts):\n \"\"\"Calculate the total amount for an invoice.\"\"\"\n return sum(amounts)\n\n", + "stderr": " ! PPR enabled but Quipu store unavailable; continuing without graph ranking. Use --verbose for details.\n" + } + ], + "sha256": { + "demo.svg": "39c22eb226479048e1bc5bc88c1f6e586907fe8ec8f4e3f6c78e5b76cb5152bf", + "transcript.txt": "f7fe87d60b1901e95f97761bc49d15b4c1a62d167c112e743e607b7b289955bc", + "demo.cast": "d955fc73c73534f684e19471b0995807d6f95f04446cceac9014685d165219fb" + } +} diff --git a/docs/demos/terminal/prepare.py b/docs/demos/terminal/prepare.py new file mode 100644 index 0000000..ae2bafe --- /dev/null +++ b/docs/demos/terminal/prepare.py @@ -0,0 +1,43 @@ +#!/usr/bin/env python3 +"""Prepare a disposable index and model cache for the terminal recorder.""" +import argparse +import os +from pathlib import Path +import shutil +import subprocess + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("workspace", type=Path) + parser.add_argument("--tool", type=Path, required=True) + args = parser.parse_args() + tool = args.tool.resolve(strict=True) + root = args.workspace.resolve() + root.mkdir() # Refuse an existing workspace rather than reuse its state. + home = root / ".demo-home" + home.mkdir() + shutil.copyfile(Path(__file__).parent / "fixture/totals.py", root / "totals.py") + (root / ".terminal-demo-sandbox").write_text("disposable terminal fixture\n") + env = { + "PATH": str(tool.parent) + os.pathsep + os.defpath, + "HOME": str(home), + "XDG_CONFIG_HOME": str(home / ".config"), + "XDG_CACHE_HOME": str(home / ".cache"), + "XDG_STATE_HOME": str(home / ".state"), + "TMPDIR": str(root), + "LANG": "C.UTF-8", + "TERM": "dumb", + "NO_COLOR": "1", + "RUST_LOG": "off", + "BOBBIN_GPU": "0", + } + for command in [ + ["init", ".", "--quiet"], + ["index", ".", "--repo", "totals-example", "--no-quipu-publish", "--skip-calibrate", "--quiet"], + ]: + subprocess.run([str(tool), *command], cwd=root, env=env, check=True) + + +if __name__ == "__main__": + main() diff --git a/docs/demos/terminal/render.py b/docs/demos/terminal/render.py new file mode 100644 index 0000000..9afe7fa --- /dev/null +++ b/docs/demos/terminal/render.py @@ -0,0 +1,201 @@ +#!/usr/bin/env python3 +"""Record real local CLI output and render a self-contained animated SVG.""" +from __future__ import annotations + +import argparse +import hashlib +import html +import json +import os +from pathlib import Path +import re +import subprocess +import time +import shlex +import textwrap +import xml.etree.ElementTree as ET + +HERE = Path(__file__).resolve().parent +FORBIDDEN = [ + r"/(?:home|Users|root|srv|run)/", + r"\b[\w.-]+\.(?:lan|svc|internal|local)\b", + r"\b(?:\d{1,3}\.){3}\d{1,3}\b", + r"\b(?:[0-9a-fA-F]{1,4}:){2,}[0-9a-fA-F:]+\b", + r"(?i)\bbearer\s+\S+", + r"-----BEGIN [A-Z ]*PRIVATE KEY-----", + r"(?i)(?:token|password|secret)\s*[=:]\s*\S+", +] + + +def check_text(text: str, *, identifiers: bool = True) -> None: + """Refuse, never redact a recording into a claimed successful command.""" + if any(re.search(pattern, text) for pattern in FORBIDDEN): + raise ValueError("recording refused: possible private data") + if any(ord(char) < 32 and char not in "\n\r\t" for char in text): + raise ValueError("recording refused: unsupported terminal control") + # Reject crew work-item prefixes while allowing public CLI flag names. + if identifiers and re.search(r"\b(?:aegis|na)-[a-z0-9]+(?:\.\d+)*\b", text): + raise ValueError("recording refused: possible work item identifier") + + + +def render_svg(tape: dict, frames: list[dict], duration: float) -> str: + width, height = tape["width"], tape["height"] + title = html.escape(tape["title"]) + pieces = [ + f'', + f'{title}', + f'{html.escape(tape["description"])} The animation repeats. ' + 'The adjacent transcript provides a static alternative.', + '', + f'', + '', + '', + '', + '' + f'{title}', + ] + # Last frame is the static fallback when SVG animation is disabled. + for index, frame in enumerate(frames): + check_text("\n".join(frame["lines"])) + last = index == len(frames) - 1 + start = frame["at"] / duration + end = (frames[index + 1]["at"] / duration) if not last else 1 + values, keys = ["hidden"], [0.0] + if start == 0: + values[0] = "visible" + else: + values.append("visible") + keys.append(start) + if not last: + values.append("hidden") + keys.append(end) + values.append(values[-1]) + keys.append(1.0) + pieces.append(f'') + pieces.append(f'') + for row, line in enumerate(frame["lines"]): + color = "#6ee7b7" if line.startswith("$ ") else "#f1f5f9" + pieces.append(f'{html.escape(line)}') + pieces.append('') + pieces.append('') + return "\n".join(pieces) + "\n" + + +def digest(path: Path) -> str: + return hashlib.sha256(path.read_bytes()).hexdigest() + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("tape", type=Path) + parser.add_argument("--workspace", type=Path, required=True, + help="prepared PRIVATE sandbox; commands may write here") + parser.add_argument("--tool", action="append", default=[], metavar="NAME=PATH") + parser.add_argument("--output", type=Path, required=True) + args = parser.parse_args() + tape = json.loads(args.tape.read_text()) + if tape["font_size"] != 24 or not 1 <= len(tape["steps"]) <= 12: + raise ValueError("use the shared 24px theme and at most twelve steps") + tools = dict(value.split("=", 1) for value in args.tool) + binaries = {name: Path(path).resolve(strict=True) for name, path in tools.items()} + root = args.workspace.resolve(strict=True) + if not (root / ".terminal-demo-sandbox").is_file(): + raise ValueError("workspace needs an explicit .terminal-demo-sandbox marker") + home = root / ".demo-home" + home.mkdir(exist_ok=True) + # Never inherit endpoints, tokens, user configuration or tool search paths. + env = {"PATH": os.pathsep.join(dict.fromkeys( + [str(p.parent) for p in binaries.values()] + [os.defpath])), + "HOME": str(home), "XDG_CONFIG_HOME": str(home / ".config"), + "XDG_CACHE_HOME": str(home / ".cache"), + "XDG_STATE_HOME": str(home / ".state"), "TMPDIR": str(root), + "LANG": "C.UTF-8", "TERM": "dumb", "NO_COLOR": "1", "RUST_LOG": "off", + "BOBBIN_GPU": "0"} + binary_hashes = {name: digest(path) for name, path in binaries.items()} + version_args = {name: tape.get("version_args", {}).get(name, ["--version"]) + for name in binaries} + versions = {name: subprocess.check_output([str(path), *version_args[name]], env=env, + text=True, timeout=10).strip() for name, path in binaries.items()} + frames, events, runs, transcript = [], [], [], [] + elapsed = 0.0 + for step in tape["steps"]: + name = step["tool"] + command = "$ " + shlex.join([name, *step["args"]]) + stdin = None + if "stdin" in step: + input_path = (root / step["stdin"]).resolve(strict=True) + input_path.relative_to(root) + stdin = input_path.read_text() + command += " < " + shlex.quote(step["stdin"]) + check_text(command) + start = time.monotonic() + result = subprocess.run([str(binaries[name]), *step["args"]], cwd=root, + env=env, input=stdin, capture_output=True, + text=True, timeout=step.get("timeout", 30)) + seconds = time.monotonic() - start + check_text(result.stdout + result.stderr) + if result.returncode != step.get("exit", 0): + raise RuntimeError("unexpected command exit; no render published") + if result.stderr and not step.get("allow_stderr", False): + raise RuntimeError("unexpected stderr; no render published") + body = result.stdout + result.stderr + for required in step.get("requires", []): + if required not in body: + raise RuntimeError("required output absent; no render published") + transcript.extend([command, body.rstrip(), f"[exit {result.returncode}]"]) + # Page complete output, never ellipsize or silently discard a line. + lines = [] + for line in (command + "\n" + body.rstrip()).splitlines(): + lines.extend(textwrap.wrap(line, width=65, replace_whitespace=False, + drop_whitespace=False) or [""]) + pages = [lines[i:i + 14] for i in range(0, len(lines), 14)] + for page in pages: + check_text("\n".join(page)) + frames.append({"at": elapsed, "lines": page}) + events.append([elapsed, "o", "\x1b[2J\x1b[H" + "\r\n".join(page) + "\r\n"]) + elapsed += step.get("hold", 5) / len(pages) + runs.append({"tool": name, "args": step["args"], "exit": result.returncode, + "seconds": round(seconds, 6), "stdout": result.stdout, + "stderr": result.stderr}) + if not 10 <= elapsed <= 30: + raise ValueError("reading timeline must be 10 to 30 seconds") + svg = render_svg(tape, frames, elapsed) + ET.fromstring(svg) + check_text(svg, identifiers=False) + cast = {"version": 2, "width": 65, "height": 14, "title": tape["title"], + "env": {"TERM": "dumb"}} + artifacts = {"demo.svg": svg, "transcript.txt": "\n".join(transcript) + "\n", + "demo.cast": json.dumps(cast) + "\n" + "\n".join( + json.dumps(event) for event in events) + "\n"} + for name, body in artifacts.items(): + check_text(body, identifiers=name != "demo.svg") + inputs = {"render.py": digest(Path(__file__)), "tape": digest(args.tape)} + for name in tape.get("inputs", []): + path = (root / name).resolve(strict=True) + path.relative_to(root) + inputs[name] = digest(path) + if binary_hashes != {name: digest(path) for name, path in binaries.items()}: + raise RuntimeError("tool bytes changed during capture; no render published") + manifest = {"theme": "stack-terminal-24", "versions": versions, + "binary_sha256": binary_hashes, "version_args": version_args, + "inputs_sha256": inputs, "duration_seconds": elapsed, + "timeline": "deliberate reading holds; execution times recorded separately", + "frames_checked": len(frames), "commands": runs, + "sha256": {n: hashlib.sha256(b.encode()).hexdigest() + for n, b in artifacts.items()}} + args.output.mkdir(parents=True, exist_ok=True) + for name, body in artifacts.items(): + (args.output / name).write_text(body) + (args.output / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n") + print(json.dumps({"frames_checked": len(frames), "duration": elapsed, + "svg_sha256": manifest["sha256"]["demo.svg"]})) + + +if __name__ == "__main__": + main() diff --git a/docs/demos/terminal/transcript.txt b/docs/demos/terminal/transcript.txt new file mode 100644 index 0000000..76849e0 --- /dev/null +++ b/docs/demos/terminal/transcript.txt @@ -0,0 +1,18 @@ +$ bobbin search 'calculate invoice total' --mode semantic --limit 2 +✓ Found 1 results for: calculate invoice total (semantic) + +1. totals.py:1 (calculate_total) + [totals-example] function python · lines 1-3 · score 0.6736 +[exit 0] +$ bobbin context 'calculate invoice total' --budget 40 +✓ Context for: calculate invoice total + 1 files, 1 chunks (3/40 lines) + +--- totals.py [direct, score: 1.0000] --- + calculate_total (function), lines 1-3 + def calculate_total(amounts): + """Calculate the total amount for an invoice.""" + return sum(amounts) + + ! PPR enabled but Quipu store unavailable; continuing without graph ranking. Use --verbose for details. +[exit 0] From 6c9031e0c540dfc35a4cd2d84ab56761051f5bdd Mon Sep 17 00:00:00 2001 From: Steve Brown Date: Fri, 13 Nov 2026 16:30:41 -0500 Subject: [PATCH 2/2] docs: refresh README source witness for terminal demo --- docs/knowledge/repository-knowledge.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/knowledge/repository-knowledge.json b/docs/knowledge/repository-knowledge.json index 6447afd..6c02953 100644 --- a/docs/knowledge/repository-knowledge.json +++ b/docs/knowledge/repository-knowledge.json @@ -109,7 +109,7 @@ "source": "README.md", "subject": "http://aegis.gastown.local/ontology/doc/bobbin/README.md", "summary": "Start with installation and the first successful search, then read architecture and contributor guidance.", - "source_sha256": "53ac24ef95c0f5aa4cfcda826df06732e3f722f912eb5914d3837048dd6659cb", + "source_sha256": "883e46dc9528c956edee68abbfd55cb28c6813e5a545ea15e8a29e887814e7ca", "properties": { "startHereOrder": "1" }