nb-cli - CLI untuk agen AI dan otomasi notebook

• Alat CLI open source eksperimental yang dirancang agar agen coding AI dapat memperlakukan Jupyter notebook sebagai artefak, diimplementasikan dengan Rust untuk mendukung manipulasi notebook yang cepat dan andal
• Untuk mengatasi masalah bahwa struktur JSON .ipynb tidak cocok untuk otomasi dan pemrosesan LLM, alat ini menyediakan fungsi baca, tulis, eksekusi, dan pencarian lewat command line sambil tetap mengikuti spesifikasi nbformat
• Berjalan tanpa server Jupyter, dan bila terhubung ke server mendukung pengeditan kolaboratif real-time dengan protokol Y.js CRDT yang sama seperti di JupyterLab
• Untuk efisiensi konteks LLM, dirancang format Markdown baru yang dioptimalkan untuk AI berbasis sentinel seperti @@cell dan @@output
• Menyediakan secara terpadu fitur yang disesuaikan untuk workflow agen seperti komposabilitas ala Unix, referensi sel yang stabil, pencarian yang kuat, manipulasi batch multi-sel, dan eksekusi yang sadar lingkungan

---

Latar belakang: masalah “kotak hitam” pada notebook

• Dengan naiknya agen coding AI, definisi alat developer berubah, dan LLM seperti Claude serta GPT dilatih dengan sangat banyak contoh penggunaan CLI dari dokumentasi, Stack Overflow, dan GitHub sehingga sangat mahir memanfaatkan command-line interface
• Alat-alat yang ada selama ini berfokus pada menjalankan agen di dalam notebook, tetapi masih ada kekosongan untuk alat bagi agen yang memperlakukan notebook itu sendiri sebagai artefak
• Struktur JSON .ipynb pada Jupyter notebook menjadi titik friksi untuk pemrosesan terprogram di shell script dan LLM
• Antarmuka yang ada kurang memadai untuk skenario berikut yang membutuhkan otomasi dan analisis AI
  • Analisis otonom: agen AI yang mengaudit workflow data science harus memahami pipeline per sel
  • Verifikasi otomatis: sistem CI/CD harus mengeksekusi notebook, memverifikasi output, dan menangkap error lebih awal
  • Dokumentasi skala besar: isi notebook harus bisa diubah otomatis menjadi dokumentasi yang rapi
  • Debugging di lingkungan operasional: kegagalan eksekusi notebook di lingkungan headless harus bisa didiagnosis tanpa intervensi manual
  • Notebook sebagai data: notebook diperlakukan seperti basis data terstruktur untuk menghasilkan laporan, ringkasan, dan visualisasi
• Selama ini, pendekatan umum adalah memanipulasi UI JupyterLab secara manual, menulis script Python rapuh yang mem-parsing JSON kompleks, atau memakai alat eksekusi tanpa integrasi real-time
• nb-cli memanfaatkan antarmuka yang mengutamakan CLI dan komposabilitas Unix agar notebook dapat diperlakukan sebagai warga kelas satu dalam software stack

Fitur utama

• Berjalan dengan atau tanpa server Jupyter

  • Secara default membaca dan menulis file .ipynb langsung, serta mengeksekusi dengan berkomunikasi langsung ke kernel melalui ZeroMQ
  • Cocok untuk script dan pipeline CI yang tidak membutuhkan server yang sedang berjalan
    • Membuat notebook tanpa server dengan nb create analysis.ipynb
    • Menambah sel, menjalankan, dan melihat hasil dengan perintah nb cell add, nb execute, dan nb read
  • Saat banyak pengguna atau agen mengedit notebook yang sama secara bersamaan, koneksi server berguna, dan menyediakan sinkronisasi real-time tanpa konflik dengan protokol Y.js CRDT yang juga dipakai internal oleh JupyterLab
    • nb connect dapat mendeteksi server lokal secara otomatis, dan opsi --server bisa dipakai untuk menentukan server atau token tertentu
    • Opsi --restart-kernel mendukung eksekusi dengan restart kernel untuk pemeriksaan reproduksibilitas
  • Saat terhubung ke server, alat ini mendeteksi apakah notebook sedang dibuka di JupyterLab; jika tidak, ia secara alami fallback ke mode berbasis file

• Format Markdown yang dioptimalkan untuk AI

  • Model bahasa tidak mem-parsing JSON melainkan memprediksi token, sehingga JSON Jupyter yang bersarang dalam sangat tidak efisien untuk context window
  • Format bawaan Jupyter menyimpan source sebagai array string, output sebagai blob base64, dan metadata sebagai struktur bertingkat, sehingga bagi LLM 30~40% token terbuang sia-sia untuk karakter struktural seperti kurung kurawal, kurung siku, dan escape
  • Markdown biasa lebih efisien secara token tetapi ambigu
    • Tidak bisa dibedakan apakah # adalah heading Markdown atau komentar Python
    • Tidak bisa dibedakan apakah code fence adalah sel notebook atau contoh di dalam dokumen
    • Saat diminta “perbaiki error di sel nomor 7”, tidak ada penanda struktural yang dapat mengidentifikasi posisi sel secara stabil
  • Untuk mengatasi ini, dirancang format sentinel berbasis baris
    • Sentinel seperti @@notebook, @@cell, dan @@output memberikan batas struktur yang jelas
    • Pada baris sentinel, tipe sel, indeks, dan jumlah eksekusi ditulis sebagai metadata JSON inline, selaras dengan cara mekanisme attention mencari informasi
    • Code fence dengan petunjuk bahasa mengaktifkan pembelajaran sintaks model
    • Setiap blok sel bersifat self-contained sehingga jika terpotong kerusakannya bertahap, tidak seperti JSON yang bisa rusak total saat satu bagian terpotong

• Desain yang dapat dikombinasikan

  • Mengikuti konvensi Unix dengan menyediakan output plain text, dukungan stdin, dan exit code yang dapat diprediksi
  • Dari sudut pandang agen, satu perintah shell dapat menggantikan beberapa pemanggilan alat dan parsing perantara
  • Tugas seperti “tambahkan bagian ringkasan ke notebook lalu jalankan” bisa diproses sebagai satu pemanggilan shell yang menambahkan sel, mengeksekusi, lalu membaca hasil
    • Dapat dirangkai dalam bentuk nb cell add ... && nb execute ... && nb read ...
    • Agen hanya menerima output yang dibutuhkan tanpa perlu membaca ulang seluruh notebook
  • Prinsip yang sama juga diterapkan pada debugging
    • Dengan satu nb search analysis.ipynb --with-errors, hanya sel yang error yang dikembalikan, tanpa membuang token pada sel yang sukses

• Referensi sel yang stabil

  • Mendukung dua cara referensi sel
    • Berbasis indeks --cell-index 0 (mendukung indeks negatif, -1 berarti sel terakhir)
    • Berbasis ID --cell f68t57 (tidak berubah meskipun sel dipindahkan)
  • Bisa mereferensikan berdasarkan posisi seperti nb cell update ... --cell-index 0 --source "x = 42"
  • Atau mereferensikan dengan ID stabil seperti nb cell update ... --cell ce456 --source "print('Done')" sehingga aman meski sel diurut ulang

• Fitur pencarian yang kuat

  • Dapat menelusuri lokasi dengan cepat berdasarkan isi sel, tipe sel, atau error eksekusi
  • Secara default mencocokkan source code sel, dan filter scope dapat diperluas ke output eksekusi
    • Pencarian pola dengan nb search analysis.ipynb "import pandas"
    • Mengekstrak hanya sel error dengan nb search analysis.ipynb --with-errors
    • Mencari di output dengan nb search analysis.ipynb "KeyError" --scope output
    • Memfilter berdasarkan tipe sel dengan nb search analysis.ipynb "TODO" --cell-type markdown
  • Agen bisa memakai --with-errors untuk memproses hanya sel yang gagal, lalu menggabungkannya dengan --scope output untuk langsung mencari traceback error
  • Manusia juga bisa memakainya untuk audit deprecated API, menemukan lokasi fungsi di notebook besar, atau mengekstrak pola sebelum refactor

• Manipulasi batch multi-sel

  • Menambahkan urutan sel seperti header Markdown → kode konfigurasi → analisis adalah pola umum, dan jika ditambahkan satu per satu akan meningkatkan jumlah round-trip serta beban pengelolaan indeks
  • Mendukung penambahan banyak sel dalam satu panggilan dengan format sentinel
    • Blok @@markdown dan @@code dapat dibungkus dalam heredoc dan dikirim sekaligus
    • Juga mendukung format JSON penuh berupa @@cell {"cell_type": "..."}
  • Kompatibel dengan stdin sehingga mudah menyusun sel dalam script dan pipeline
    • printf '@@markdown\n## Summary\n\n@@code\ndf.describe()\n' | nb cell add report.ipynb --source -
  • Filosofi batch yang sama juga berlaku untuk eksekusi dan penghapusan
    • Menjalankan rentang dengan nb execute analysis.ipynb --start 2 --end 5
    • Menghapus sel tertentu dengan nb cell delete analysis.ipynb -i 0 -i 2
    • Menghapus rentang dengan nb cell delete analysis.ipynb --range 0:3

• Eksekusi yang sadar lingkungan

  • nb connect, nb execute, dan nb create mendukung flag --uv dan --pixi untuk mencari server Jupyter dan kernel melalui environment manager terkait
  • nb status --python mengembalikan prefix perintah untuk menjalankan Python di lingkungan yang sama dengan kernel yang terhubung
    • Contoh nilai balik: "uv run", "pixi run", atau nilai kosong untuk Python sistem
    • Dapat dipakai dalam pipeline dalam bentuk $(nb status --python) python -c "..."

Contoh penggunaan nyata

• Workflow agen AI

  • Dapat memanipulasi notebook sebagai bagian dari workflow analisis dengan merangkai perintah pencarian sel gagal → perbaikan kode → eksekusi ulang
    • 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

• Integrasi CI/CD

  • Melakukan pengujian dan verifikasi otomatis notebook dalam pipeline continuous integration
    • Setelah menjalankan nb execute pipeline.ipynb --allow-errors, periksa error dengan nb search ... --with-errors dan kembalikan exit code 1 jika ada masalah
    • Membersihkan output sebelum commit dengan nb output clear

• Pembuatan notebook secara terprogram

  • Mengotomatiskan pembuatan dokumen, laporan, dan analisis
    • Membuat notebook laporan dengan nb create report.ipynb
    • Menambahkan judul, pengantar, dan kode analisis sekaligus lewat perintah multi-sel lalu mengisi output dengan nb execute

• Debugging notebook di lingkungan operasional

  • Mendiagnosis masalah pada notebook yang telah dideploy dengan cepat
    • Mengekstrak sel error dengan nb search failing_notebook.ipynb --with-errors
    • Menelusuri penggunaan deprecated API dengan nb search analysis.ipynb "pandas.np"
    • Menelusuri pola berisiko keamanan dengan nb search notebook.ipynb "eval("
    • Memeriksa seluruh output sel tertentu dengan nb read failing_notebook.ipynb --cell-index 5
    • Memeriksa reproduksibilitas bersih dengan nb execute failing_notebook.ipynb --restart-kernel

Contoh cara kerja nyata

• Example 1: Membuat notebook pelatihan reinforcement learning untuk LLM dengan Claude

  • Prompt pengguna: buat notebook yang membahas konsep inti seperti model kebijakan, model reward, penalti KL divergence, PPO, dan GRPO, serta jelaskan cara kerjanya di setiap sel
  • Disusun agar dapat dieksekusi penuh di CPU tanpa API key dengan memakai model toy kecil berbasis kosakata kecil dan GRU

• Example 2: Memperbaiki banyak bug notebook dengan Codex

  • Prompt pengguna: perbaiki churn_analysis.ipynb yang tidak diperbarui sejak 2023 agar dapat berjalan bersih sampai akhir, identifikasi, perbaiki, dan verifikasi setiap sel yang gagal, lalu tambahkan catatan Markdown di atas sel yang diubah tentang apa masalahnya dan bagaimana perbaikannya
  • Empat bug yang diperbaiki Codex
    • Path file yang di-hardcode
    • DataFrame.append() yang dihapus di pandas 2.0
    • sklearn.cross_validation yang dihapus di sklearn 0.20
    • plot_confusion_matrix yang dihapus di sklearn 1.2
  • Setelah diperbaiki, diverifikasi bahwa notebook berjalan normal end-to-end

Memulai

• Menyediakan tiga jalur instalasi: script instalasi, cargo install nb-cli, dan build dari source (cargo build --release)
• Saat build, binary dibuat di target/release/nb
• Jika ingin agen AI menggunakan nb untuk semua pekerjaan notebook, tersedia perintah instalasi skill npx skills install jupyter-ai-contrib/nb-cli

Developer dan kontribusi

• Tiga kontributor proyek Jupyter dari AWS terlibat dalam pengembangan
  • Andrii Ieroshenko: AWS Software Development Engineer, kontributor lama JupyterLab dan Jupyter AI, anggota Jupyter Media Strategy Working Group
  • Brian Granger: AWS Senior Principal Technologist, salah satu pendiri Project Jupyter, anggota board Jupyter dan PyTorch Foundation
  • Piyush Jain: AWS Principal Engineer, menangani Jupyter dan Agentic AI, anggota Jupyter Server Council
• nb-cli masih berada pada tahap awal, dan setelah instalasi serta penggunaan pengguna diminta mendaftarkan GitHub issue, ikut diskusi jupyter-ai-contrib, serta berkontribusi lewat bug report, feature request, dan PR

[jessyt]

Karena ditulis berfokus pada contoh kasus, ada banyak hal yang bisa dijadikan referensi!