nb-cli – CLI für KI-Agenten und Notebook-Automatisierung

• Ein experimentelles Open-Source-CLI-Tool, das so entwickelt wurde, dass KI-Coding-Agenten Jupyter-Notebooks als Artefakte behandeln können; implementiert in Rust, um schnelle und stabile Notebook-Manipulationen zu unterstützen
• Um das Problem zu lösen, dass die .ipynb-JSON-Struktur für Automatisierung und LLM-Verarbeitung ungeeignet ist, bietet es unter Einhaltung der nbformat-Spezifikation Lese-, Schreib-, Ausführungs- und Suchfunktionen über die Kommandozeile
• Funktioniert auch ohne Jupyter-Server; bei Verbindung mit einem Server wird kollaboratives Editieren in Echtzeit über dasselbe Y.js-CRDT-Protokoll unterstützt, das auch JupyterLab verwendet
• Für bessere LLM-Kontexteffizienz wurde ein neues sentinelbasiertes, KI-optimiertes Markdown-Format mit @@cell, @@output usw. entworfen
• Vereint auf Agenten-Workflows zugeschnittene Funktionen wie Unix-Komponierbarkeit, stabile Zellreferenzen, leistungsfähige Suche, Batch-Manipulation mehrerer Zellen und umgebungsbewusste Ausführung

---

Hintergrund: das „Blackbox“-Problem von Notebooks

• Mit dem Aufstieg von KI-Coding-Agenten verändert sich die Definition von Entwickler-Tools; LLMs wie Claude und GPT wurden anhand umfangreicher CLI-Anwendungsfälle aus Dokumentation, Stack Overflow und GitHub trainiert und sind daher sehr geübt im Umgang mit Kommandozeilen-Interfaces
• Bisherige Tools konzentrierten sich darauf, Agenten innerhalb von Notebooks auszuführen, doch es fehlten Werkzeuge für Agenten, die das Notebook selbst als Artefakt behandeln
• Die .ipynb-JSON-Struktur von Jupyter-Notebooks stellt in Shell-Skripten und LLMs einen Reibungspunkt für programmgesteuerte Verarbeitung dar
• In den folgenden Szenarien, die Automatisierung und KI-Analyse erfordern, reichen bestehende Interfaces nicht aus
  • Autonome Analyse: Ein KI-Agent, der Data-Science-Workflows auditiert, muss die Pipeline auf Zellebene verstehen
  • Automatisierte Verifikation: CI/CD-Systeme müssen Notebooks ausführen, Ausgaben prüfen und Fehler frühzeitig erkennen
  • Dokumentation im großen Maßstab: Notebook-Inhalte müssen automatisch in saubere Dokumentation umgewandelt werden
  • Debugging in Produktionsumgebungen: Ausführungsfehler von Notebooks in Headless-Umgebungen müssen ohne manuelle Eingriffe diagnostiziert werden
  • Notebooks als Daten: Notebooks werden wie strukturierte Datenbanken behandelt, um Berichte, Zusammenfassungen und Visualisierungen zu erzeugen
• Bisher war es üblich, die JupyterLab-UI manuell zu bedienen, fragile Python-Skripte zum Parsen komplexer JSON-Strukturen zu schreiben oder Ausführungstools ohne Echtzeit-Integration zu verwenden
• nb-cli nutzt ein CLI-first-Interface und Unix-Komponierbarkeit, damit Notebooks als erstklassiger Bestandteil des Software-Stacks behandelt werden können

Kernfunktionen

• Funktioniert mit oder ohne Jupyter-Server

  • Liest und schreibt standardmäßig direkt .ipynb-Dateien und führt sie aus, indem es über ZeroMQ direkt mit dem Kernel kommuniziert
  • Geeignet für Skripte und CI-Pipelines, bei denen kein laufender Server erforderlich ist
    • Mit nb create analysis.ipynb lässt sich ohne Server ein Notebook erstellen
    • Mit nb cell add, nb execute und nb read können Zellen hinzugefügt, ausgeführt und Ergebnisse abgerufen werden
  • Wenn mehrere Nutzer oder Agenten gleichzeitig dasselbe Notebook bearbeiten, ist eine Serververbindung nützlich; sie bietet konfliktfreie Synchronisierung in Echtzeit über dasselbe Y.js-CRDT-Protokoll, das JupyterLab intern verwendet
    • nb connect erkennt einen lokalen Server automatisch; mit der Option --server lassen sich bestimmter Server und Token angeben
    • Die Option --restart-kernel unterstützt Kernel-Neustarts zur Prüfung der Reproduzierbarkeit
  • Bei bestehender Serververbindung erkennt das Tool, ob das Notebook in JupyterLab geöffnet ist, und fällt andernfalls nahtlos auf dateibasiertes Arbeiten zurück

• KI-optimiertes Markdown-Format

  • Sprachmodelle parsen JSON nicht, sondern sagen Tokens voraus; deshalb ist tief verschachteltes Jupyter-JSON im Kontextfenster ineffizient
  • Im Standardformat von Jupyter bestehen Quellen aus String-Arrays, Ausgaben aus base64-Blobs und Metadaten aus mehreren Verschachtelungsebenen; aus Sicht eines LLM werden dadurch 30–40 % der Tokens bedeutungslos für Strukturzeichen wie geschweifte Klammern, eckige Klammern und Escapes verbraucht
  • Normales Markdown ist zwar tokeneffizient, aber mehrdeutig
    • Es ist nicht unterscheidbar, ob # eine Markdown-Überschrift oder ein Python-Kommentar ist
    • Es ist nicht unterscheidbar, ob ein Code-Fence eine Notebook-Zelle oder ein Beispiel im Dokument ist
    • Wenn man sagt „Behebe den Fehler in Zelle 7“, fehlen strukturelle Marker, um die Zellposition stabil zu identifizieren
  • Um das zu lösen, wurde ein zeilenbasiertes Sentinel-Format entworfen
    • Sentinels wie @@notebook, @@cell und @@output schaffen klare Strukturgrenzen
    • In den Sentinel-Zeilen werden Zelltyp, Index und Ausführungsanzahl als Inline-JSON-Metadaten angegeben, passend dazu, wie der Attention-Mechanismus Informationen findet
    • Code-Fences mit Sprachhinweisen aktivieren das Syntaxwissen des Modells
    • Jeder Zellblock ist in sich abgeschlossen und degradiert bei Abschneidung schrittweise, statt dass wie bei JSON bei einem einzelnen abgeschnittenen Teil die gesamte Struktur bricht

• Komponierbares Design

  • Folgt den Unix-Konventionen und bietet Plain-Text-Ausgabe, stdin-Unterstützung und vorhersehbare Exit-Codes
  • Aus Sicht eines Agenten kann ein einzelner Shell-Befehl mehrere Tool-Aufrufe und Zwischen-Parsing ersetzen
  • Aufgaben wie „Füge dem Notebook einen Zusammenfassungsabschnitt hinzu und führe es aus“ können durch einen einzigen Shell-Aufruf mit Zellen hinzufügen, ausführen und Ergebnis lesen erledigt werden
    • Verkettung in der Form nb cell add ... && nb execute ... && nb read ...
    • Der Agent erhält nur die benötigten Ausgaben, ohne das gesamte Notebook erneut lesen zu müssen
  • Dasselbe Prinzip gilt für das Debugging
    • nb search analysis.ipynb --with-errors gibt mit einem einzigen Aufruf nur fehlerhafte Zellen zurück, ohne Tokens für erfolgreiche Zellen zu verschwenden

• Stabile Zellreferenzen

  • Unterstützt zwei Arten der Zellreferenzierung
    • Indexbasiert --cell-index 0 (mit negativer Indizierung; -1 ist die letzte Zelle)
    • ID-basiert --cell f68t57 (bleibt auch dann unverändert, wenn die Zelle verschoben wird)
  • Referenzierung nach Position etwa mit nb cell update ... --cell-index 0 --source "x = 42" oder
  • per stabiler ID mit nb cell update ... --cell ce456 --source "print('Done')", sodass auch Zellumordnungen sicher sind

• Leistungsfähige Suche

  • Schnelles Auffinden nach Zellinhalt, Zelltyp und Ausführungsfehlern
  • Standardmäßig werden Zellquellen durchsucht; mit einem Scope-Filter lässt sich die Suche auf Ausgaben erweitern
    • nb search analysis.ipynb "import pandas" sucht nach dem Muster
    • nb search analysis.ipynb --with-errors extrahiert nur Fehlerzellen
    • nb search analysis.ipynb "KeyError" --scope output sucht in Ausgaben
    • nb search analysis.ipynb "TODO" --cell-type markdown filtert nach Zelltyp
  • Agenten können mit --with-errors nur fehlgeschlagene Zellen erhalten und in Kombination mit --scope output direkt nach Error-Tracebacks suchen
  • Auch Menschen können damit deprecated APIs auditieren, Funktionen in großen Notebooks auffinden oder Muster vor einem Refactoring extrahieren

• Batch-Manipulation mehrerer Zellen

  • Das Hinzufügen von Zellsequenzen wie Markdown-Header → Konfigurationscode → Analyse ist ein häufiges Muster; beim Hinzufügen einzelner Zellen steigen Roundtrips und Verwaltungsaufwand für Indizes
  • Unterstützt das Hinzufügen mehrerer Zellen in einem Aufruf über das Sentinel-Format
    • @@markdown- und @@code-Blöcke können per Heredoc gebündelt und auf einmal übergeben werden
    • Unterstützt auch das vollständige JSON-Format in der Form @@cell {"cell_type": "..."}
  • Kompatibel mit stdin und daher leicht in Skripten und Pipelines für den Zellenaufbau nutzbar
    • printf '@@markdown\n## Summary\n\n@@code\ndf.describe()\n' | nb cell add report.ipynb --source -
  • Dieselbe Batch-Philosophie gilt auch für Ausführung und Löschung
    • nb execute analysis.ipynb --start 2 --end 5 führt einen Bereich aus
    • nb cell delete analysis.ipynb -i 0 -i 2 löscht bestimmte Zellen
    • nb cell delete analysis.ipynb --range 0:3 löscht einen Bereich

• Umgebungsbewusste Ausführung

  • nb connect, nb execute und nb create unterstützen die Flags --uv, --pixi, um Jupyter-Server und Kernel über den jeweiligen Environment-Manager zu finden
  • nb status --python gibt das Befehlspräfix zurück, mit dem Python in derselben Umgebung wie der verbundene Kernel ausgeführt wird
    • Beispiel-Rückgabewerte: "uv run", "pixi run"; im Fall von System-Python ein leerer Wert
    • Nutzbar in Pipelines in der Form $(nb status --python) python -c "..."

Praktische Anwendungsfälle

• KI-Agenten-Workflows

  • Fehlgeschlagene Zellen finden → Code korrigieren → erneut ausführen lässt sich per Befehl verknüpfen, sodass Notebook-Manipulation Teil des Analyse-Workflows wird
    • nb search data_analysis.ipynb --with-errors
    • nb cell update data_analysis.ipynb --cell-index 3 --source "df = pd.read_csv('data.csv', encoding='utf-8')"
    • nb execute data_analysis.ipynb --cell-index 3

• CI/CD-Integration

  • Führt automatisierte Tests und Validierung von Notebooks in Continuous-Integration-Pipelines aus
    • Nach Ausführung mit nb execute pipeline.ipynb --allow-errors gibt nb search ... --with-errors bei gefundenen Fehlern Exit-Code 1 zurück
    • Vor dem Commit können mit nb output clear Ausgaben bereinigt werden

• Programmgesteuerte Notebook-Erzeugung

  • Automatische Erstellung von Dokumentation, Berichten und Analysen
    • Mit nb create report.ipynb wird ein Berichts-Notebook erzeugt
    • Mit einem Multi-Cell-Befehl lassen sich Titel, Einleitung und Analysecode auf einmal hinzufügen und anschließend mit nb execute mit Ausgaben füllen

• Debugging von Notebooks in Produktionsumgebungen

  • Probleme in ausgerollten Notebooks schnell diagnostizieren
    • nb search failing_notebook.ipynb --with-errors extrahiert Fehlerzellen
    • nb search analysis.ipynb "pandas.np" sucht nach Verwendung einer deprecated API
    • nb search notebook.ipynb "eval(" sucht nach sicherheitskritischen Mustern
    • nb read failing_notebook.ipynb --cell-index 5 zeigt die vollständige Ausgabe einer bestimmten Zelle
    • nb execute failing_notebook.ipynb --restart-kernel prüft saubere Reproduzierbarkeit

Beispiele aus der Praxis

• Beispiel 1: Mit Claude ein Trainings-Notebook für LLM-gestütztes Reinforcement Learning erstellen

  • Nutzer-Prompt: Erstelle ein Notebook, das zentrale Konzepte wie Policy-Modell, Reward-Modell, KL-divergence-Strafe, PPO und GRPO behandelt und in jeder Zelle die Funktionsweise erklärt
  • Verwendet ein kleines Toy-Modell mit kleinem Vokabular und GRU-Basis, damit alles ohne API-Key auf der CPU vollständig ausführbar ist

• Beispiel 2: Mit Codex mehrere Bugs in einem Notebook beheben

  • Nutzer-Prompt: Überarbeite churn_analysis.ipynb, das seit 2023 nicht mehr aktualisiert wurde, so dass es bis zum Ende sauber ausführbar ist; identifiziere, behebe und validiere jede fehlerhafte Zelle und füge oberhalb der geänderten Zellen eine Markdown-Notiz hinzu, was das Problem war und wie es behoben wurde
  • Vier von Codex behobene Bugs
    • hartkodierter Dateipfad
    • DataFrame.append(), entfernt in pandas 2.0
    • sklearn.cross_validation, entfernt in sklearn 0.20
    • plot_confusion_matrix, entfernt in sklearn 1.2
  • Nach den Korrekturen wurde verifiziert, dass das Notebook End-to-End korrekt läuft

Einstieg

• Drei Installationswege: Installationsskript, cargo install nb-cli und Build aus dem Quellcode (cargo build --release)
• Das Build erzeugt das Binärprogramm unter target/release/nb
• Damit KI-Agenten für alle Notebook-Aufgaben nb verwenden, wird der Skill-Installationsbefehl npx skills install jupyter-ai-contrib/nb-cli unterstützt

Entwickler und Mitwirkung

• Drei Mitwirkende am Jupyter-Projekt bei AWS sind an der Entwicklung beteiligt
  • Andrii Ieroshenko: AWS Software Development Engineer, langjähriger Mitwirkender an JupyterLab und Jupyter AI, Mitglied der Jupyter Media Strategy Working Group
  • Brian Granger: AWS Senior Principal Technologist, Mitgründer von Project Jupyter, Vorstandsmitglied bei Jupyter und der PyTorch Foundation
  • Piyush Jain: AWS Principal Engineer, zuständig für Jupyter und Agentic AI, Mitglied im Jupyter Server Council
• nb-cli befindet sich in einer frühen Phase; nach Installation und Nutzung werden Beiträge über GitHub-Issues, Diskussionen in jupyter-ai-contrib, Bug-Reports, Feature-Requests und PRs erbeten

[jessyt]

Danke, dass Sie den Beitrag anhand von Beispielen aufgebaut haben — da gibt es vieles, woran ich mich orientieren kann!