nblean 0.1.0__py3-none-any.whl

nblean/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: nblean
+description: Use whenever a task touches a Jupyter notebook (.ipynb), including reading, searching, editing, running cells, debugging tracebacks, and inspecting plots. Run the nblean CLI instead of reading the notebook, so only the cells you need enter context, with their outputs clipped.
+---
+
+# Working with notebooks via nblean
+
+Never `Read`, `cat`, `grep`, or `jq` an `.ipynb` file directly: it loads every output,
+every base64 image, and every progress-bar line. Use `nblean`; if it is not on PATH, run it as `uvx nblean`.
+
+## Navigate
+
+```bash
+nblean outline nb.ipynb             # always first: one line per cell, output summary
+nblean show nb.ipynb 12 15-18       # source + clipped outputs of those cells only
+nblean show nb.ipynb 12 --no-output # source only, when you are about to edit
+nblean grep nb.ipynb 'read_csv'     # index:line hits; -o searches outputs too
+nblean errors nb.ipynb              # failing cells only, with your frame and the exception
+```
+
+CELL is an index, a range (`3-7`, `5-`), `all`, or a cell id prefix.
+Outputs are clipped to 20 lines (`--lines N`, `--full` to disable). Ask for more
+only when the clipped part is what you need.
+
+## Edit
+
+```bash
+nblean set nb.ipynb 12 <<'PY'
+df = load(path)
+PY
+nblean add nb.ipynb --at 13 <<'PY'      # --md for markdown; omit --at to append
+df.describe()
+PY
+nblean rm nb.ipynb 14
+```
+
+Indices shift after `add`/`rm`; re-run `outline` or use ids before chaining edits.
+`set` clears the cell's stale outputs.
+
+## Execute
+
+```bash
+nblean run nb.ipynb 0-12        # persistent kernel, outputs saved into the notebook
+nblean run nb.ipynb 12          # re-run one edited cell; earlier state is kept
+nblean eval nb.ipynb 'df.dtypes' # scratch probe, not saved to the notebook
+nblean kernel nb.ipynb restart  # clean state; also status, stop
+```
+
+- The kernel uses the nearest `.venv/bin/python` (override `--python`) and the
+  notebook's directory as cwd. It needs `ipykernel` in that env.
+- A fresh kernel is empty: run the prerequisite cells before the one you changed.
+- Investigate with `eval` instead of inserting throwaway print cells.
+- Cells longer than a couple of minutes: run with Bash `run_in_background`.
+- `run` stops at the first error and exits 1.
+- Stop the kernel when the task is done.
+
+## Images
+
+Plots appear as `[image/png → /tmp/.../12_0.png]`. Do not open them by default.
+Prefer numbers: `nblean eval nb.ipynb 'series.describe()'`. Open an image with `Read`
+only when the judgement is visual, and downscale first since image tokens scale
+with pixel area: `sips -Z 768 in.png --out /tmp/small.png` (macOS).
+
+## Caveats
+
+If the user has the notebook open in Jupyter or VS Code, tell them to reload it after
+your writes and not to save over them from the editor.

nblean/__init__.py

@@ -0,0 +1,3 @@
+from nblean.cli import main
+
+__all__ = ["main"]

nblean/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from nblean.cli import main
+
+sys.exit(main())

nblean/cli.py

@@ -0,0 +1,289 @@
+import argparse
+import io
+import re
+import sys
+from collections import Counter
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import cast
+
+from nblean import kernel, skill
+from nblean.notebook import Cell, NbleanError, Notebook, joined, source_of
+from nblean.render import (
+    FULL,
+    Budget,
+    ImageSink,
+    Output,
+    cell_header,
+    clean,
+    image_suffix,
+    outline_row,
+    render_outputs,
+    shorten,
+)
+
+type Handler = Callable[[argparse.Namespace], int]
+
+GREP_WIDTH = 160
+
+
+def image_sink(notebook: Path, label: str) -> ImageSink:
+    def write(position: int, mime: str, payload: bytes) -> Path:
+        directory = kernel.state_dir(notebook) / "img"
+        directory.mkdir(parents=True, exist_ok=True)
+        target = directory / f"{label}_{position}{image_suffix(mime)}"
+        target.write_bytes(payload)
+        return target
+
+    return write
+
+
+def budget_of(args: argparse.Namespace) -> Budget:
+    return FULL if args.full else Budget(lines=args.lines)
+
+
+def read_stdin() -> str:
+    if sys.stdin.isatty():
+        msg = "expected cell source on stdin"
+        raise NbleanError(msg)
+    return sys.stdin.read()
+
+
+def outputs_of(cell: Cell) -> list[Output]:
+    return cast("list[Output]", cell.get("outputs", []))
+
+
+def cmd_outline(args: argparse.Namespace) -> int:
+    notebook = Notebook.load(args.notebook)
+    kinds = Counter(cell["cell_type"] for cell in notebook.cells)
+    summary = ", ".join(f"{count} {kind}" for kind, count in kinds.items())
+    status = "live" if kernel.running_pid(notebook.path) else "off"
+    print(f"{notebook.path.name}: {len(notebook.cells)} cells ({summary}), kernel {status}")
+    for index, cell in enumerate(notebook.cells):
+        print(outline_row(index, cell))
+    return 0
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    notebook = Notebook.load(args.notebook)
+    budget = budget_of(args)
+    for index in notebook.select(args.cells):
+        cell = notebook.cells[index]
+        print(cell_header(index, cell))
+        print(source_of(cell))
+        if cell["cell_type"] == "code" and not args.no_output:
+            print("── out ──")
+            print(render_outputs(outputs_of(cell), budget, image_sink(notebook.path, str(index))))
+    return 0
+
+
+def cmd_grep(args: argparse.Namespace) -> int:
+    notebook = Notebook.load(args.notebook)
+    pattern = re.compile(args.pattern)
+    found = False
+    for index, cell in enumerate(notebook.cells):
+        texts = [("", source_of(cell))]
+        if args.outputs:
+            texts += [("out ", text) for text in output_texts(outputs_of(cell))]
+        for label, text in texts:
+            for number, line in enumerate(clean(text).splitlines(), 1):
+                if pattern.search(line):
+                    found = True
+                    print(f"{index}:{label}{number}: {shorten(line.strip(), GREP_WIDTH)}")
+    return 0 if found else 1
+
+
+def output_texts(outputs: list[Output]) -> list[str]:
+    texts = []
+    for output in outputs:
+        match output:
+            case {"output_type": "stream", "text": text} | {"data": {"text/plain": text}}:
+                texts.append(joined(text))
+            case {"output_type": "error", "traceback": traceback}:
+                texts.append("\n".join(traceback))
+    return texts
+
+
+def cmd_errors(args: argparse.Namespace) -> int:
+    notebook = Notebook.load(args.notebook)
+    budget = budget_of(args)
+    failing = 0
+    for index, cell in enumerate(notebook.cells):
+        errors = [output for output in outputs_of(cell) if output["output_type"] == "error"]
+        if errors:
+            failing += 1
+            print(cell_header(index, cell))
+            print(render_outputs(errors, budget, image_sink(notebook.path, str(index))))
+    if not failing:
+        print("no errors")
+    return 0
+
+
+def cmd_set(args: argparse.Namespace) -> int:
+    notebook = Notebook.load(args.notebook)
+    match notebook.select([args.cell]):
+        case [index]:
+            notebook.replace_source(index, read_stdin())
+        case indices:
+            msg = f"set takes exactly one cell, {args.cell!r} selects {len(indices)}"
+            raise NbleanError(msg)
+    notebook.save()
+    print(f"set {index}")
+    return 0
+
+
+def cmd_add(args: argparse.Namespace) -> int:
+    notebook = Notebook.load(args.notebook)
+    index = notebook.insert(args.at, "markdown" if args.md else "code", read_stdin())
+    notebook.save()
+    print(f"added {index}")
+    return 0
+
+
+def cmd_rm(args: argparse.Namespace) -> int:
+    notebook = Notebook.load(args.notebook)
+    indices = notebook.select(args.cells)
+    notebook.remove(indices)
+    notebook.save()
+    print(f"removed {', '.join(map(str, indices))}")
+    return 0
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    notebook = Notebook.load(args.notebook)
+    budget = budget_of(args)
+    code_cells = [
+        i for i in notebook.select(args.cells) if notebook.cells[i]["cell_type"] == "code"
+    ]
+    client = kernel.connect(notebook.path, args.python)
+    try:
+        for index in code_cells:
+            cell = notebook.cells[index]
+            execution = kernel.execute(client, source_of(cell))
+            cell |= {"outputs": execution.outputs, "execution_count": execution.count}
+            notebook.save()
+            print(cell_header(index, cell))
+            print(render_outputs(execution.outputs, budget, image_sink(notebook.path, str(index))))
+            if execution.failed:
+                return 1
+    finally:
+        client.stop_channels()
+    return 0
+
+
+def cmd_eval(args: argparse.Namespace) -> int:
+    code = read_stdin() if args.code == "-" else args.code
+    client = kernel.connect(args.notebook, args.python)
+    try:
+        execution = kernel.execute(client, code, store_history=False)
+    finally:
+        client.stop_channels()
+    print(render_outputs(execution.outputs, budget_of(args), image_sink(args.notebook, "eval")))
+    return 1 if execution.failed else 0
+
+
+def cmd_kernel(args: argparse.Namespace) -> int:
+    match args.action:
+        case "status":
+            pid = kernel.running_pid(args.notebook)
+            print(f"live, pid {pid}" if pid else "off")
+        case "stop":
+            print("stopped" if kernel.stop(args.notebook) else "was not running")
+        case "restart":
+            kernel.stop(args.notebook)
+            kernel.start(args.notebook, args.python)
+            print("restarted, state is empty")
+    return 0
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    for path in skill.install(args.agent or ["claude"], project=args.project):
+        print(f"wrote {path}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nblean",
+        description="Token-lean Jupyter notebook access for coding agents.",
+        epilog="CELL is an index, a range like 3-7 or 5-, 'all', or a cell id prefix.",
+    )
+    commands = parser.add_subparsers(required=True, metavar="COMMAND")
+
+    def command(name: str, handler: Handler, summary: str) -> argparse.ArgumentParser:
+        sub = commands.add_parser(name, help=summary, description=summary)
+        sub.add_argument("notebook", type=Path)
+        sub.set_defaults(handler=handler)
+        return sub
+
+    def output_options(sub: argparse.ArgumentParser) -> None:
+        sub.add_argument("--full", action="store_true", help="disable output clipping")
+        sub.add_argument("--lines", type=int, default=20, help="max lines per output (default 20)")
+
+    def kernel_options(sub: argparse.ArgumentParser) -> None:
+        sub.add_argument("--python", type=Path, help="kernel interpreter (default: nearest .venv)")
+
+    init = commands.add_parser(
+        "init", help="install the agent skill", description="Install the nblean agent skill."
+    )
+    init.add_argument(
+        "--agent",
+        action="append",
+        choices=[*skill.SKILL_DIRS, "all"],
+        help="target agent, repeatable (default: claude)",
+    )
+    init.add_argument("--project", action="store_true", help="install into ./ instead of ~/")
+    init.set_defaults(handler=cmd_init)
+
+    command("outline", cmd_outline, "one line per cell with output summary")
+
+    show = command("show", cmd_show, "source and clipped outputs of selected cells")
+    show.add_argument("cells", nargs="+", metavar="CELL")
+    show.add_argument("--no-output", action="store_true", help="source only")
+    output_options(show)
+
+    grep = command("grep", cmd_grep, "regex search over cell sources")
+    grep.add_argument("pattern")
+    grep.add_argument("-o", "--outputs", action="store_true", help="search outputs too")
+
+    output_options(command("errors", cmd_errors, "tracebacks of failing cells"))
+
+    command("set", cmd_set, "replace a cell's source from stdin").add_argument(
+        "cell", metavar="CELL"
+    )
+
+    add = command("add", cmd_add, "insert a cell from stdin")
+    add.add_argument("--at", type=int, help="insert position (default: end)")
+    add.add_argument("--md", action="store_true", help="markdown cell")
+
+    command("rm", cmd_rm, "delete cells").add_argument("cells", nargs="+", metavar="CELL")
+
+    run = command("run", cmd_run, "execute cells in a persistent kernel and save outputs")
+    run.add_argument("cells", nargs="+", metavar="CELL")
+    output_options(run)
+    kernel_options(run)
+
+    evaluate = command("eval", cmd_eval, "run scratch code in the kernel without saving it")
+    evaluate.add_argument("code", help="code to run, or - for stdin")
+    output_options(evaluate)
+    kernel_options(evaluate)
+
+    manage = command("kernel", cmd_kernel, "inspect or control the notebook's kernel")
+    manage.add_argument("action", choices=["status", "stop", "restart"])
+    kernel_options(manage)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    if sys.platform == "win32":
+        for stream in (sys.stdout, sys.stderr):
+            if isinstance(stream, io.TextIOWrapper):
+                stream.reconfigure(encoding="utf-8", errors="replace")
+    args = build_parser().parse_args(argv)
+    try:
+        handler: Handler = args.handler
+        return handler(args)
+    except NbleanError as exc:
+        print(f"nblean: {exc}", file=sys.stderr)
+        return 2

nblean/kernel.py

@@ -0,0 +1,158 @@
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from contextlib import suppress
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from jupyter_client.blocking.client import BlockingKernelClient
+
+from nblean import process
+from nblean.notebook import NbleanError
+from nblean.render import Output
+
+STATE_ROOT = Path(tempfile.gettempdir()) / "nblean"
+STARTUP_TIMEOUT = 60.0
+POLL_INTERVAL = 0.1
+LOG_TAIL = 15
+RESULT_KEYS = ("data", "execution_count", "metadata")
+ERROR_KEYS = ("ename", "evalue", "traceback")
+
+
+@dataclass(slots=True)
+class Execution:
+    outputs: list[Output] = field(default_factory=list)
+    count: int | None = None
+
+    @property
+    def failed(self) -> bool:
+        return any(output["output_type"] == "error" for output in self.outputs)
+
+    def collect(self, message: dict[str, Any]) -> None:
+        content = message["content"]
+        match message["msg_type"]:
+            case "stream":
+                last = self.outputs[-1] if self.outputs else {}
+                if last.get("output_type") == "stream" and last["name"] == content["name"]:
+                    last["text"] += content["text"]
+                else:
+                    self.outputs.append(
+                        {
+                            "output_type": "stream",
+                            "name": content["name"],
+                            "text": content["text"],
+                        }
+                    )
+            case "display_data":
+                self.outputs.append(
+                    {
+                        "output_type": "display_data",
+                        "data": content["data"],
+                        "metadata": content["metadata"],
+                    }
+                )
+            case "execute_result":
+                self.outputs.append(
+                    {"output_type": "execute_result"} | {key: content[key] for key in RESULT_KEYS}
+                )
+            case "error":
+                self.outputs.append(
+                    {"output_type": "error"} | {key: content[key] for key in ERROR_KEYS}
+                )
+            case "clear_output":
+                self.outputs.clear()
+
+
+def state_dir(notebook: Path) -> Path:
+    digest = hashlib.sha256(str(notebook.resolve()).encode()).hexdigest()[:12]
+    return STATE_ROOT / f"{notebook.stem}-{digest}"
+
+
+def find_python(start: Path) -> Path:
+    for directory in (start.resolve(), *start.resolve().parents):
+        if (candidate := directory / ".venv" / process.VENV_PYTHON).exists():
+            return candidate
+    return Path(sys.executable)
+
+
+def running_pid(notebook: Path) -> int | None:
+    state = state_dir(notebook)
+    try:
+        pid = int((state / "kernel.pid").read_text())
+    except (OSError, ValueError):
+        return None
+    return pid if process.is_running(pid) and (state / "kernel.json").exists() else None
+
+
+def start(notebook: Path, python: Path | None) -> None:
+    state = state_dir(notebook)
+    state.mkdir(parents=True, exist_ok=True)
+    connection = state / "kernel.json"
+    connection.unlink(missing_ok=True)
+    interpreter = python or find_python(notebook.parent)
+    environment = {key: value for key, value in os.environ.items() if key != "JPY_PARENT_PID"}
+    log_path = state / "kernel.log"
+    with log_path.open("w") as log:
+        kernel = subprocess.Popen(
+            [str(interpreter), "-m", "ipykernel_launcher", "-f", str(connection)],
+            cwd=notebook.resolve().parent,
+            env=environment,
+            stdin=subprocess.DEVNULL,
+            stdout=log,
+            stderr=subprocess.STDOUT,
+            start_new_session=process.NEW_SESSION,
+            creationflags=process.CREATION_FLAGS,
+        )
+    (state / "kernel.pid").write_text(str(kernel.pid))
+    deadline = time.monotonic() + STARTUP_TIMEOUT
+    while time.monotonic() < deadline:
+        if kernel.poll() is not None:
+            tail = "\n".join(log_path.read_text().splitlines()[-LOG_TAIL:])
+            msg = (
+                f"kernel exited using {interpreter}:\n{tail}\n"
+                "is ipykernel installed there? `uv add --dev ipykernel`"
+            )
+            raise NbleanError(msg)
+        with suppress(OSError, ValueError):
+            json.loads(connection.read_text())
+            return
+        time.sleep(POLL_INTERVAL)
+    kernel.kill()
+    msg = f"kernel did not start within {STARTUP_TIMEOUT:.0f}s, see {log_path}"
+    raise NbleanError(msg)
+
+
+def stop(notebook: Path) -> bool:
+    pid = running_pid(notebook)
+    if pid is not None:
+        process.terminate_tree(pid)
+    for name in ("kernel.json", "kernel.pid"):
+        (state_dir(notebook) / name).unlink(missing_ok=True)
+    return pid is not None
+
+
+def connect(notebook: Path, python: Path | None) -> BlockingKernelClient:
+    if running_pid(notebook) is None:
+        start(notebook, python)
+    client = BlockingKernelClient()
+    client.load_connection_file(str(state_dir(notebook) / "kernel.json"))
+    client.start_channels()
+    client.wait_for_ready(timeout=STARTUP_TIMEOUT)
+    return client
+
+
+def execute(client: BlockingKernelClient, code: str, *, store_history: bool = True) -> Execution:
+    execution = Execution()
+    reply = client.execute_interactive(
+        code,
+        store_history=store_history,
+        allow_stdin=False,
+        output_hook=execution.collect,
+    )
+    execution.count = reply["content"].get("execution_count")
+    return execution

nblean/notebook.py

@@ -0,0 +1,101 @@
+import json
+import re
+import uuid
+from collections.abc import Iterable
+from dataclasses import dataclass
+from itertools import chain
+from pathlib import Path
+from typing import Any, Self, cast
+
+type Cell = dict[str, Any]
+
+CELL_RANGE = re.compile(r"(\d+)-(\d*)")
+
+
+class NbleanError(Exception):
+    pass
+
+
+def joined(value: str | list[str]) -> str:
+    return value if isinstance(value, str) else "".join(value)
+
+
+def source_of(cell: Cell) -> str:
+    return joined(cell["source"])
+
+
+def lines_of(text: str) -> list[str]:
+    return text.removesuffix("\n").splitlines(keepends=True)
+
+
+@dataclass(slots=True)
+class Notebook:
+    path: Path
+    data: dict[str, Any]
+
+    @classmethod
+    def load(cls, path: Path) -> Self:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            msg = f"{path}: {exc}"
+            raise NbleanError(msg) from exc
+        return cls(path, data)
+
+    @property
+    def cells(self) -> list[Cell]:
+        return cast("list[Cell]", self.data["cells"])
+
+    @property
+    def has_cell_ids(self) -> bool:
+        return (self.data.get("nbformat", 4), self.data.get("nbformat_minor", 0)) >= (
+            4,
+            5,
+        )
+
+    def save(self) -> None:
+        text = json.dumps(self.data, sort_keys=True, indent=1, ensure_ascii=False) + "\n"
+        staging = self.path.with_name(f".{self.path.name}.nblean")
+        staging.write_text(text, encoding="utf-8", newline="\n")
+        staging.replace(self.path)
+
+    def select(self, specs: Iterable[str]) -> list[int]:
+        return list(dict.fromkeys(chain.from_iterable(map(self._resolve, specs))))
+
+    def _resolve(self, spec: str) -> Iterable[int]:
+        count = len(self.cells)
+        if spec == "all":
+            return range(count)
+        if spec.isdigit():
+            if (index := int(spec)) >= count:
+                msg = f"cell {index} out of range, notebook has {count} cells"
+                raise NbleanError(msg)
+            return [index]
+        if match := CELL_RANGE.fullmatch(spec):
+            stop = int(match[2]) + 1 if match[2] else count
+            return range(int(match[1]), min(stop, count))
+        hits = [i for i, cell in enumerate(self.cells) if cell.get("id", "").startswith(spec)]
+        if len(hits) != 1:
+            msg = f"cell id {spec!r} matched {len(hits)} cells"
+            raise NbleanError(msg)
+        return hits
+
+    def replace_source(self, index: int, text: str) -> None:
+        cell = self.cells[index]
+        cell["source"] = lines_of(text)
+        if cell["cell_type"] == "code":
+            cell |= {"execution_count": None, "outputs": []}
+
+    def insert(self, index: int | None, kind: str, text: str) -> int:
+        cell: Cell = {"cell_type": kind, "metadata": {}, "source": lines_of(text)}
+        if self.has_cell_ids:
+            cell["id"] = uuid.uuid4().hex[:8]
+        if kind == "code":
+            cell |= {"execution_count": None, "outputs": []}
+        position = len(self.cells) if index is None else min(index, len(self.cells))
+        self.cells.insert(position, cell)
+        return position
+
+    def remove(self, indices: Iterable[int]) -> None:
+        for index in sorted(indices, reverse=True):
+            del self.cells[index]

nblean/process.py

@@ -0,0 +1,47 @@
+import os
+import subprocess
+import sys
+from contextlib import suppress
+from pathlib import Path
+
+if sys.platform == "win32":
+    import ctypes
+
+    PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+    STILL_ACTIVE = 259
+    VENV_PYTHON = Path("Scripts", "python.exe")
+    CREATION_FLAGS = subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.DETACHED_PROCESS
+    NEW_SESSION = False
+
+    def is_running(pid: int) -> bool:
+        kernel32 = ctypes.windll.kernel32
+        handle = kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
+        if not handle:
+            return False
+        try:
+            code = ctypes.c_ulong()
+            alive = kernel32.GetExitCodeProcess(handle, ctypes.byref(code))
+            return bool(alive) and code.value == STILL_ACTIVE
+        finally:
+            kernel32.CloseHandle(handle)
+
+    def terminate_tree(pid: int) -> None:
+        subprocess.run(["taskkill", "/F", "/T", "/PID", str(pid)], capture_output=True, check=False)
+
+else:
+    import signal
+
+    VENV_PYTHON = Path("bin", "python")
+    CREATION_FLAGS = 0
+    NEW_SESSION = True
+
+    def is_running(pid: int) -> bool:
+        try:
+            os.kill(pid, 0)
+        except OSError:
+            return False
+        return True
+
+    def terminate_tree(pid: int) -> None:
+        with suppress(ProcessLookupError):
+            os.killpg(pid, signal.SIGTERM)

nblean/render.py

@@ -0,0 +1,150 @@
+import base64
+import mimetypes
+import re
+from collections import Counter
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from nblean.notebook import Cell, joined, source_of
+
+type Output = dict[str, Any]
+type ImageSink = Callable[[int, str, bytes], Path]
+
+ANSI_ESCAPE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")
+HEAD_WIDTH = 72
+LIBRARY_FRAME = re.compile(r"site-packages|\.pyx\b|\.pxi\b|[\\/]lib[\\/]python\d|[\\/]Lib[\\/]")
+TRACEBACK_HEADER = "Traceback (most recent call last)"
+
+
+@dataclass(frozen=True, slots=True)
+class Budget:
+    lines: int | None = 20
+    width: int | None = 160
+
+
+FULL = Budget(lines=None, width=None)
+
+
+def shorten(line: str, width: int | None) -> str:
+    return line if width is None or len(line) <= width else f"{line[: width - 1]}…"
+
+
+def clean(text: str) -> str:
+    text = ANSI_ESCAPE.sub("", text)
+    return "\n".join(line.rstrip("\r").rsplit("\r", 1)[-1] for line in text.split("\n"))
+
+
+def clip(text: str, budget: Budget, *, tail_only: bool = False) -> str:
+    lines = [shorten(line, budget.width) for line in clean(text).rstrip("\n").split("\n")]
+    if budget.lines is None or len(lines) <= budget.lines:
+        return "\n".join(lines)
+    head = 0 if tail_only else budget.lines // 2
+    tail = budget.lines - head
+    marker = f"… {len(lines) - budget.lines} lines omitted …"
+    return "\n".join([*lines[:head], marker, *lines[-tail:]])
+
+
+def compact_traceback(traceback: list[str]) -> str:
+    entries = [clean(entry) for entry in traceback]
+    start = max((i for i, entry in enumerate(entries) if TRACEBACK_HEADER in entry), default=0)
+    *frames, exception = entries[start:]
+    kept = [frame for frame in frames if not LIBRARY_FRAME.search(frame.split("\n", 1)[0])]
+    hidden = len(entries) - 1 - len(kept)
+    marker = [f"… {hidden} library or chained frames omitted …"] if hidden else []
+    return "\n".join([*kept, *marker, exception])
+
+
+def render_error(output: Output, budget: Budget) -> str:
+    traceback: list[str] = output.get("traceback", [])
+    if not traceback:
+        return f"{output.get('ename')}: {output.get('evalue')}"
+    text = "\n".join(traceback) if budget.lines is None else compact_traceback(traceback)
+    return clip(text, budget, tail_only=True)
+
+
+def line_count(text: str) -> int:
+    return clean(text).rstrip("\n").count("\n") + 1
+
+
+def image_mime(data: dict[str, Any]) -> str | None:
+    return next((mime for mime in data if mime.startswith("image/")), None)
+
+
+def image_bytes(mime: str, payload: str | list[str]) -> bytes:
+    text = joined(payload)
+    return text.encode() if mime == "image/svg+xml" else base64.b64decode(text)
+
+
+def image_suffix(mime: str) -> str:
+    return mimetypes.guess_extension(mime) or ".bin"
+
+
+def render_output(position: int, output: Output, budget: Budget, sink: ImageSink) -> str:
+    match output:
+        case {"output_type": "stream", "text": text}:
+            return clip(joined(text), budget)
+        case {"output_type": "error"}:
+            return render_error(output, budget)
+        case {"data": data} if mime := image_mime(data):
+            return f"[{mime} → {sink(position, mime, image_bytes(mime, data[mime]))}]"
+        case {"data": {"text/plain": text}}:
+            return clip(joined(text), budget)
+        case {"data": data}:
+            return f"[{', '.join(data)}]"
+        case _:
+            return f"[{output.get('output_type', 'unknown output')}]"
+
+
+def render_outputs(outputs: list[Output], budget: Budget, sink: ImageSink) -> str:
+    rendered = (render_output(n, output, budget, sink) for n, output in enumerate(outputs))
+    return "\n".join(rendered) or "(no output)"
+
+
+def summarize(outputs: list[Output]) -> str:
+    text_lines = 0
+    marks: Counter[str] = Counter()
+    for output in outputs:
+        match output:
+            case {"output_type": "error", "ename": ename}:
+                marks[f"ERR {ename}"] += 1
+            case {"output_type": "stream", "text": text}:
+                text_lines += line_count(joined(text))
+            case {"data": data} if image_mime(data):
+                marks["img"] += 1
+            case {"data": {"text/plain": text}}:
+                text_lines += line_count(joined(text))
+            case _:
+                marks["other"] += 1
+    parts = [f"{text_lines}L"] if text_lines else []
+    parts += [mark if n == 1 else f"{mark}×{n}" for mark, n in marks.items()]
+    return " ".join(parts)
+
+
+def outline_row(index: int, cell: Cell) -> str:
+    lines = [line.strip() for line in source_of(cell).splitlines() if line.strip()]
+    head = shorten(lines[0], HEAD_WIDTH) if lines else ""
+    extra = f" +{len(lines) - 1}L" if len(lines) > 1 else ""
+    suffix = ""
+    match cell["cell_type"]:
+        case "code":
+            tag = "code"
+            if cell.get("execution_count") is None:
+                suffix = "  → not run"
+            elif summary := summarize(cell.get("outputs", [])):
+                suffix = f"  → {summary}"
+        case "markdown":
+            tag = "md"
+        case kind:
+            tag = kind
+    return f"{index:>3} {tag:<5} {head}{extra}{suffix}"
+
+
+def cell_header(index: int, cell: Cell) -> str:
+    fields = [str(index), cell["cell_type"]]
+    if cell_id := cell.get("id"):
+        fields.append(f"id={cell_id}")
+    if (count := cell.get("execution_count")) is not None:
+        fields.append(f"exec={count}")
+    return f"── {' '.join(fields)} ──"

nblean/skill.py

@@ -0,0 +1,21 @@
+from collections.abc import Iterable
+from importlib.resources import files
+from pathlib import Path
+
+SKILL_DIRS = {
+    "claude": Path(".claude", "skills"),
+    "codex": Path(".agents", "skills"),
+    "opencode": Path(".agents", "skills"),
+    "gemini": Path(".gemini", "skills"),
+}
+
+
+def install(agents: Iterable[str], *, project: bool) -> list[Path]:
+    names = SKILL_DIRS if "all" in agents else agents
+    base = Path.cwd() if project else Path.home()
+    targets = dict.fromkeys(base / SKILL_DIRS[name] / "nblean" / "SKILL.md" for name in names)
+    text = files("nblean").joinpath("SKILL.md").read_text(encoding="utf-8")
+    for target in targets:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text, encoding="utf-8", newline="\n")
+    return list(targets)

nblean-0.1.0.dist-info/METADATA

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: nblean
+Version: 0.1.0
+Summary: Token-lean Jupyter notebook access for coding agents: outlines, clipped outputs, lazy images, a persistent kernel.
+Keywords: jupyter,notebook,ipynb,llm,coding-agent,claude-code,tokens,cli
+Author: Recep Kaan Karaman
+Author-email: Recep Kaan Karaman <kaanrkaraman@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Dist: jupyter-client>=8.10.0
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/kaanrkaraman/nblean
+Project-URL: Repository, https://github.com/kaanrkaraman/nblean
+Project-URL: Issues, https://github.com/kaanrkaraman/nblean/issues
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <strong>nblean</strong><br>
+  <strong>Lets coding agents work with Jupyter notebooks without reading every output</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/kaanrkaraman/nblean/actions/workflows/ci.yml"><img src="https://github.com/kaanrkaraman/nblean/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/nblean/"><img src="https://img.shields.io/pypi/v/nblean" alt="PyPI"></a>
+  <a href="https://pypi.org/project/nblean/"><img src="https://img.shields.io/pypi/pyversions/nblean" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  <a href="#installation">Install</a> &bull;
+  <a href="#quick-start">Quick Start</a> &bull;
+  <a href="#commands">Commands</a> &bull;
+  <a href="#how-savings-work">Benchmarks</a> &bull;
+  <a href="#supported-agents">Agents</a>
+</p>
+
+---
+
+An `.ipynb` file holds code plus everything the code printed: DataFrame dumps,
+progress bars, tracebacks, and plots stored as base64 images. An agent that opens one
+reads all of it. To fix one cell, it then runs the whole notebook again and reads the
+result again.
+
+nblean is a small CLI and agent skill that lets the agent work one cell at a time. It
+lists the notebook as an outline, opens only the cells asked for, clips their outputs,
+and runs cells in a background kernel that stays alive between commands.
+
+## What nblean Does
+
+| Agent needs to | Without nblean | With nblean |
+|---|---|---|
+| See what a notebook contains | Reads the whole JSON, outputs included | `outline`: one line per cell, with an output summary like `→ 14L img ERR KeyError` |
+| Look at a few cells | Writes a one-off `json`/`jq` script | `show 12 15-18`: source, plus outputs clipped to the first and last lines |
+| Find code | Greps JSON-escaped strings | `grep`: matches by cell and line number |
+| Debug | Scrolls through ANSI-colored tracebacks full of library frames | `errors`: only the failing cells, showing your frame and the exception |
+| Edit a cell | Rewrites the JSON, or reads the notebook first | `set` / `add` / `rm`, with the new source passed on stdin |
+| Re-run after a fix | Runs the whole notebook again and reads all the output | `run 12`: runs that cell in a kernel that is still alive, prints only its output, and saves it into the notebook |
+| Check a value | Adds a throwaway `print` cell | `eval 'df.dtypes'`: runs the code in the kernel without changing the notebook |
+| Look at plots | Every plot costs image tokens | Plots are saved as files and only their paths are printed; the agent opens one when it needs to |
+
+## How Savings Work
+
+nblean cuts **notebook tokens**, which are only part of an agent's bill. Every session
+also pays for the system prompt, tool definitions, and conversation history. These
+fixed costs come to about 28k tokens per session on Claude Code. Savings grow with the
+size of the notebook and the volume of its outputs.
+
+### A/B test in Claude Code
+
+Claude Sonnet ran headless (`claude -p`), two times with the nblean skill and two
+times without it. Token counts
+come from the `usage` that Claude Code reports; costs are what the same usage would
+cost at API prices.
+
+| Task | Without nblean | With nblean | Change |
+|---|---:|---:|---:|
+| Answer two questions from the saved outputs of a 7 MB EDA notebook (97 cells, 31 plots) | 236k tokens · $0.207 | 172k tokens · $0.160 | **-27% tokens, -23% cost** |
+| Find and fix a bug in a 124 KB notebook, then re-run it until clean | 183k tokens · $0.153 | 183k tokens · $0.150 | no measurable change |
+
+The first version of nblean showed execution counts in the outline, and one run
+reported them as cell indices. The numbers above come from runs after that fix, and
+all of them answered correctly. Every fix run ended with a clean notebook. On the
+small notebook the baseline agent already worked efficiently: it ran `nbconvert` and
+grepped for errors, so nblean had little to remove.
+
+### First look
+
+This compares the `outline` output with reading the whole notebook,
+counting text as bytes/4 and images by pixel area. It is an upper bound on what the
+first step saves.
+
+| Notebook | Whole notebook | `nblean outline` |
+|---|---:|---:|
+| Flight-data EDA, 97 cells, 31 plots | ~81k | ~1.5k |
+| Data preprocessing | ~58k | ~260 |
+| Kaggle training run | ~29k | ~90 |
+
+## Installation
+
+```bash
+uv tool install nblean        # or: pipx install nblean
+nblean --help
+```
+
+You can also run it without installing: `uvx nblean outline nb.ipynb`.
+
+The kernel runs in the notebook's own environment, not in nblean's. nblean picks the
+nearest `.venv` above the notebook, which needs `ipykernel` installed
+(`uv add --dev ipykernel`). Use `--python PATH` to pick a different interpreter.
+
+## Quick Start
+
+```bash
+# 1. Install the skill for your agent
+nblean init                         # Claude Code (default)
+nblean init --agent codex           # Codex
+nblean init --agent opencode        # OpenCode
+nblean init --agent gemini          # Gemini CLI
+nblean init --agent all             # all of the above
+nblean init --project               # into ./ instead of ~/
+
+# 2. Ask your agent anything about a notebook
+```
+
+The skill tells the agent to start with `outline` and never to read the `.ipynb`
+directly.
+
+## How It Works
+
+```
+  Without nblean:                              With nblean:
+
+  agent --read--> nb.ipynb                     agent --outline/show--> nblean --> nb.ipynb
+    ^                 |                          ^                       |  clip, summarize,
+    |  every source,  |                          |  only requested       |  images to files
+    |  output, image  |                          |  cells, clipped       |
+    +-----------------+                          +-----------------------+
+                                                 agent --run 12--> nblean --> live kernel
+                                                                     |  only this cell's output,
+                                                                     |  saved back into nb.ipynb
+```
+
+The kernel is a detached `ipykernel` process. Each notebook gets its own kernel, and
+each nblean call connects to it, runs code, and disconnects. Variables stay in memory
+between calls until `kernel stop` or `kernel restart`.
+
+## Commands
+
+CELL is an index (`12`), a range (`3-7`, `5-`), `all`, or the start of a cell id.
+
+### Read
+
+```bash
+nblean outline nb.ipynb                       # one line per cell
+nblean show nb.ipynb 12 15-18                 # source + clipped outputs
+nblean show nb.ipynb 12 --no-output           # source only
+nblean show nb.ipynb 12 --lines 60            # bigger clip; --full disables it
+nblean grep nb.ipynb 'read_csv'               # search sources; -o includes outputs
+nblean errors nb.ipynb                        # failing cells only
+```
+
+### Edit
+
+```bash
+nblean set nb.ipynb 12 <<'PY'                 # replace source, clears stale outputs
+df = pd.read_parquet(path)
+PY
+nblean add nb.ipynb --at 13 <<'PY'            # insert; --md for markdown
+df.describe()
+PY
+nblean rm nb.ipynb 14 20-22
+```
+
+### Execute
+
+```bash
+nblean run nb.ipynb 0-12                      # run cells, save outputs, stop at first error
+nblean eval nb.ipynb 'df.shape'               # scratch code, nothing saved
+nblean kernel nb.ipynb status|stop|restart
+```
+
+## Examples
+
+```
+$ nblean outline eda.ipynb
+eda.ipynb: 97 cells (36 markdown, 61 code), kernel off
+  0 md    1. Files and Schema +14L
+  1 code  import itertools +27L
+  3 code  files = pl.DataFrame( +5L  → 13L
+ 13 code  p0 = pl.read_parquet(PARQ / "part.0.parquet") +7L  → 1L img
+ 15 code  fl_min = feat["flight_length"].to_numpy() / 60 +19L  → img
+```
+
+A 40-line pandas traceback, cut down to the line that failed:
+
+```
+$ nblean errors buggy.ipynb
+── 8 code id=cell08 exec=3 ──
+KeyError                                  Traceback (most recent call last)
+Cell In[3], line 1
+----> 1 df["pressure_kpa"] = df["presure"] * 6.89476
+      2 df.head()
+
+… 11 library or chained frames omitted …
+KeyError: 'presure'
+```
+
+A 300-line training log, with a plot that is saved to a file instead of loaded:
+
+```
+$ nblean run buggy.ipynb 3 4 --lines 6
+── 3 code id=cell03 exec=4 ──
+epoch 000 smoothing pass loss=1.000000 temp_mean=141.845
+epoch 001 smoothing pass loss=0.500000 temp_mean=141.724
+epoch 002 smoothing pass loss=0.333333 temp_mean=141.651
+… 294 lines omitted …
+epoch 297 smoothing pass loss=0.003356 temp_mean=139.027
+epoch 298 smoothing pass loss=0.003344 temp_mean=139.038
+epoch 299 smoothing pass loss=0.003333 temp_mean=139.048
+── 4 code id=cell04 exec=5 ──
+[image/png → /tmp/nblean/buggy-ec4a859a6390/img/4_0.png]
+```
+
+## Supported Agents
+
+The skill uses the [Agent Skills](https://agentskills.io) `SKILL.md` format, so the
+same file works in every agent below. The CLI works with any agent that can run shell
+commands.
+
+| Agent | `nblean init` | Skill location |
+|---|---|---|
+| Claude Code | `--agent claude`, or the plugin below | `~/.claude/skills/nblean` |
+| Codex | `--agent codex` | `~/.agents/skills/nblean` |
+| OpenCode | `--agent opencode` | `~/.agents/skills/nblean` |
+| Gemini CLI | `--agent gemini` | `~/.gemini/skills/nblean` |
+| Others | `npx skills add kaanrkaraman/nblean` | per agent |
+
+In Claude Code the skill is also available as a plugin:
+
+```
+/plugin marketplace add kaanrkaraman/nblean
+/plugin install nblean@nblean
+```
+
+nblean ships as a CLI and a skill instead of an MCP server. An MCP server's tool
+definitions are loaded into every session. A skill is loaded only when a notebook
+comes up.
+
+## Platform Support
+
+macOS, Linux, and Windows, on Python 3.13+. The kernel's Python can be any version
+that `ipykernel` supports.
+
+## Limitations
+
+- A cell's outputs are written when the cell finishes. If a long cell is killed, its output is lost.
+- Writes are atomic but not merged. If the notebook is open in Jupyter or VS Code, reload it there after nblean writes.
+- Widgets, `update_display_data`, and `input()` are not supported.
+
+## Contributing
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . && uv run mypy
+```
+
+## License
+
+[MIT](LICENSE)

nblean-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+nblean/SKILL.md,sha256=hfMltvod-KKHt5rsPBxlUYivo-IvpIdKsQ5xnHz5ibU,2772
+nblean/__init__.py,sha256=XIUjpD7vCIRfnx18NyLhlcsMeBK0tONgaWWugsAml1A,48
+nblean/__main__.py,sha256=fFi5nqpqk7_6wdAtSkmauDKeqHFBRov8ruLR-AfbszQ,58
+nblean/cli.py,sha256=FlmyEVhEYvS7WgF1eYKrYvF5W4cUgf6Wc0LNFdDa7ts,10230
+nblean/kernel.py,sha256=nd_9SWvYjDZT2gX7NzCKXmyMnOsJlNbmqL54_F003dM,5490
+nblean/notebook.py,sha256=QMEgR_EaMz_3QaRtzIx5ij4woyQq-WGqR4_elr6VgIk,3285
+nblean/process.py,sha256=0ZSxGr-GqhNNwMPruC7MNz76eEen-eH16PzFsJ9pL5A,1366
+nblean/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nblean/render.py,sha256=0xjXdnhwDuA2oIZKLMgAM783PN3GFlz-j0SJwaz2zjk,5477
+nblean/skill.py,sha256=tHa3CWGEAIz0wxjBXsAJPWEgntLotLAYNm6ca_-ctsc,801
+nblean-0.1.0.dist-info/licenses/LICENSE,sha256=hZ-d4XRb4sZgApI3eeJeMmaEpakU07fxMbQR8qf-1A8,1075
+nblean-0.1.0.dist-info/WHEEL,sha256=e4_1dyBeezi8ZjfxrZ3bnVOxFDa3ksqVqH0jTHkUZ3k,81
+nblean-0.1.0.dist-info/entry_points.txt,sha256=3no9FnFDoUuW3R4Of2rjsILULkMgV-Wn5W8wY8YXtV0,40
+nblean-0.1.0.dist-info/METADATA,sha256=JtPqh4-mPfDjCfxuSTb8OGcSDkAWpLJa5bvEV1tHAWY,11444
+nblean-0.1.0.dist-info/RECORD,,

nblean-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.19
+Root-Is-Purelib: true
+Tag: py3-none-any

nblean-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+nblean = nblean:main
+

nblean-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Recep Kaan Karaman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.