nb-cli - AIエージェントとノートブック自動化のためのCLI

• AIコーディングエージェントがJupyterノートブックを成果物として扱えるように設計された実験的なオープンソースCLIツールで、Rustベースで実装されており、高速かつ安定したノートブック操作をサポート
• .ipynb のJSON構造が自動化・LLM処理に適していないという問題を解決するため、nbformat仕様に従いながら読み取り・書き込み・実行・検索機能をコマンドラインで提供
• Jupyterサーバーなしでも動作し、サーバーに接続する場合はJupyterLabと同じ Y.js CRDTプロトコル でリアルタイム共同編集をサポート
• LLMコンテキスト効率のために @@cell, @@output のような センチネルベースのAI最適化Markdownフォーマット を新たに設計
• Unixの合成可能性、安定したセル参照、強力な検索、複数セルの一括操作、環境認識実行など、エージェントワークフローに合わせた機能を統合提供

---

背景: ノートブックが抱える「ブラックボックス」問題

• AIコーディングエージェントの台頭により開発者ツールの定義が変わりつつあり、Claude・GPTのようなLLMは文書・Stack Overflow・GitHubにある膨大なCLI利用事例で学習されているため、コマンドラインインターフェースの活用に非常に長けている
• 既存ツールはノートブック内でエージェントを実行することに焦点を当ててきたが、ノートブックそのものを成果物として扱うエージェント向けのツールは空白だった
• Jupyterノートブックの .ipynb JSON構造は、シェルスクリプトやLLMにとってプログラム的処理が難しい摩擦点として機能する
• 自動化・AI分析が必要な次のシナリオでは既存インターフェースでは不十分
  • 自律分析: データサイエンスのワークフローを監査するAIエージェントが、セル単位でパイプラインを把握する必要がある
  • 自動検証: CI/CDシステムがノートブックを実行し、出力を検証してエラーを事前に捉える必要がある
  • 大規模ドキュメント化: ノートブック内容を整ったドキュメントへ自動変換する必要がある
  • 運用環境のデバッグ: ヘッドレス環境でのノートブック実行失敗を手動介入なしに診断する必要がある
  • データとしてのノートブック: ノートブックを構造化データベースのように扱い、レポート・要約・可視化を生成
• 従来はJupyterLab UIを手作業で扱うか、複雑なJSONをパースする壊れやすいPythonスクリプトを書くか、リアルタイム統合のない実行ツールを使う方法が一般的だった
• nb-cliはCLIファーストのインターフェースとUnixの合成可能性を活用し、ノートブックをソフトウェアスタックの第一級市民として扱えるようにする

主な機能

• Jupyterサーバーの有無にかかわらず動作

  • デフォルトでは .ipynb ファイルを直接読み書きし、ZeroMQを通じてカーネルと直接通信して実行
  • サーバー起動が不要なスクリプト・CIパイプラインに適する
    • nb create analysis.ipynb でサーバーなしにノートブックを作成
    • nb cell add, nb execute, nb read コマンドでセル追加・実行・結果参照が可能
  • 複数のユーザーやエージェントが同時に同じノートブックを編集する場合はサーバー接続が有用で、JupyterLabが内部で使うものと同じ Y.js CRDTプロトコル により競合のないリアルタイム同期を提供
    • nb connect でローカルサーバーを自動検出し、--server オプションで特定のサーバー・トークンを指定可能
    • --restart-kernel オプションで再現性確認のためのカーネル再起動実行をサポート
  • サーバー接続時にはJupyterLabでノートブックが開かれているかを検知し、開かれていなければファイルベース動作へ自然にフォールバック

• AI最適化Markdownフォーマット

  • 言語モデルはJSONをパースするのではなくトークンを予測するため、深くネストしたJupyter JSONはコンテキストウィンドウ内で非効率
  • Jupyterの標準フォーマットはソースが文字列配列、出力がbase64 blob、メタデータが多層ネストで構成されており、LLMの観点ではトークンの30〜40%が波括弧・角括弧・エスケープのような構造文字に無意味に消費される
  • 一般的なMarkdownはトークン効率はよいが曖昧さが大きい
    • # がMarkdown見出しかPythonコメントか区別できない
    • コードフェンスがノートブックのセルなのか文書内の例なのか区別できない
    • 「7番目のセルのエラーを直して」と言われたとき、セル位置を安定的に識別する構造マーカーがない
  • これを解決するために行単位のセンチネルフォーマットを設計
    • @@notebook, @@cell, @@output のようなセンチネルで明確な構造境界を提供
    • センチネル行にセルタイプ・インデックス・実行回数をインラインJSONメタデータとして記載し、アテンションメカニズムが情報を探す方式と整合
    • 言語ヒント付きコードフェンスでモデルの構文学習を活性化
    • 各セルブロックが自己完結しているため、途中で切れても段階的に壊れるだけで、JSONのように一箇所切れると全体構造が崩れる問題がない

• 合成可能な設計

  • Unixの慣例に従い、プレーンテキスト出力、stdinサポート、予測可能な終了コードを提供
  • エージェントの観点では、単一のシェルコマンドで複数回のツール呼び出しや中間パースを置き換えられる
  • 「ノートブックに要約セクションを追加して実行」のような作業を、セル追加・実行・結果読み取りまで1回のシェル呼び出しで処理できる
    • nb cell add ... && nb execute ... && nb read ... のようにチェーン可能
    • エージェントはノートブック全体を再読込せず、必要な出力だけを受け取れる
  • デバッグにも同じ原則を適用
    • nb search analysis.ipynb --with-errors を1回実行するだけでエラーのあるセルだけを返し、成功したセルにトークンを浪費しない

• 安定したセル参照

  • 2種類のセル参照方式をサポート
    • インデックスベース --cell-index 0（負のインデックス対応、-1 は最後のセル）
    • IDベース --cell f68t57（セルが移動しても変わらない）
  • nb cell update ... --cell-index 0 --source "x = 42" のように位置で参照したり
  • nb cell update ... --cell ce456 --source "print('Done')" のように安定IDで参照してセルの並べ替えにも安全

• 強力な検索機能

  • セル内容・タイプ・実行エラーで素早く位置を特定できる
  • デフォルトではセルのソースコードを対象にし、scopeフィルターで実行出力まで拡張可能
    • nb search analysis.ipynb "import pandas" でパターン検索
    • nb search analysis.ipynb --with-errors でエラーセルのみ抽出
    • nb search analysis.ipynb "KeyError" --scope output で出力を検索
    • nb search analysis.ipynb "TODO" --cell-type markdown でセルタイプでフィルター
  • エージェントは --with-errors で失敗したセルだけを受け取り処理し、--scope output と組み合わせてエラートレースバックを直接検索できる
  • 人間にとっても、deprecated APIの監査、大規模ノートブックでの関数位置把握、リファクタ前のパターン抽出に活用できる

• 複数セルの一括操作

  • Markdownヘッダー → 設定コード → 分析のようなセルシーケンス追加は一般的なパターンであり、セルを1つずつ追加すると往復回数とインデックス管理の負担が増える
  • センチネルフォーマットにより1回の呼び出しで複数セルを追加可能
    • @@markdown, @@code ブロックをheredocでまとめて一度に渡せる
    • @@cell {"cell_type": "..."} 形式の完全なJSONフォーマットもサポート
  • stdinにも対応し、スクリプト・パイプラインでセル構成を容易にする
    • printf '@@markdown\n## Summary\n\n@@code\ndf.describe()\n' | nb cell add report.ipynb --source -
  • 同じ一括処理の思想は実行・削除にも適用
    • nb execute analysis.ipynb --start 2 --end 5 で範囲実行
    • nb cell delete analysis.ipynb -i 0 -i 2 で特定セル削除
    • nb cell delete analysis.ipynb --range 0:3 で範囲削除

• 環境認識実行

  • nb connect, nb execute, nb create で**--uv, --pixi フラグ**をサポートし、対応する環境マネージャーでJupyterサーバー・カーネルを探索
  • nb status --python は接続中のカーネルと同じ環境でPythonを実行するためのコマンドプレフィックスを返す
    • 返り値の例: "uv run", "pixi run"、システムPythonの場合は空文字列
    • $(nb status --python) python -c "..." の形でパイプラインに活用

実際の使用例

• AIエージェントワークフロー

  • 失敗セルの探索 → コード修正 → 再実行をコマンドでつなぎ、分析ワークフローの一部としてノートブックを操作できる
    • 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統合

  • 継続的インテグレーションパイプラインでノートブックの自動テストと検証を実施
    • nb execute pipeline.ipynb --allow-errors で実行後、nb search ... --with-errors でエラー確認時に終了コード1を返す
    • コミット前に nb output clear で出力を整理

• プログラムによるノートブック生成

  • ドキュメント・レポート・分析を自動生成
    • nb create report.ipynb でレポート用ノートブックを作成
    • マルチセルコマンドでタイトル・導入・分析コードを一度に追加し、nb execute で出力を埋める

• 運用環境でのノートブックデバッグ

  • デプロイ済みノートブックの問題を迅速に診断
    • nb search failing_notebook.ipynb --with-errors でエラーセルを抽出
    • nb search analysis.ipynb "pandas.np" でdeprecated API使用を探索
    • nb search notebook.ipynb "eval(" でセキュリティ懸念パターンを探索
    • nb read failing_notebook.ipynb --cell-index 5 で特定セルの完全な出力を確認
    • nb execute failing_notebook.ipynb --restart-kernel でクリーンな再現性確認

実際の動作例

• Example 1: ClaudeでLLM強化学習の学習ノートブックを作成

  • ユーザープロンプト: 方策モデル、報酬モデル、KL divergenceペナルティ、PPO、GRPOなどの主要概念を扱うノートブックを作り、各セルで動作原理を説明すること
  • 小さな語彙・GRUベースの小型トイモデルを用いて、APIキーなしでCPU上ですべて実行できるよう構成

• Example 2: Codexでノートブックの複数バグを修正

  • ユーザープロンプト: 2023年以降更新されていない churn_analysis.ipynb を最後まできれいに実行できるよう修正し、各失敗セルを特定・修正・検証したうえで、変更セルの上に何がどう問題だったかを説明するMarkdownノートを追加すること
  • Codexが修正した4つのバグ
    • ハードコードされたファイルパス
    • pandas 2.0で削除された DataFrame.append()
    • sklearn 0.20で削除された sklearn.cross_validation
    • sklearn 1.2で削除された plot_confusion_matrix
  • 修正後、ノートブックがエンドツーエンドで正常実行されることを検証

はじめに

• インストールスクリプト、cargo install nb-cli、ソースビルド（cargo build --release）の3つの導入方法を提供
• ビルド時のバイナリは target/release/nb に生成
• AIエージェントがすべてのノートブック作業でnbを使うようにするため、スキルインストールコマンド npx skills install jupyter-ai-contrib/nb-cli をサポート

開発者と参加方法

• AWS所属のJupyterプロジェクト貢献者3名が開発に参加
  • Andrii Ieroshenko: AWS Software Development Engineer、JupyterLab・Jupyter AIなどの長期貢献者、Jupyter Media Strategy Working Groupメンバー
  • Brian Granger: AWS Senior Principal Technologist、Project Jupyter共同創設者、Jupyter・PyTorch Foundationボードメンバー
  • Piyush Jain: AWS Principal Engineer、Jupyter・Agentic AI担当、Jupyter Server Councilメンバー
• nb-cliは初期段階にあり、インストール・利用後にGitHub Issue登録、jupyter-ai-contrib ディスカッション参加、バグレポート・機能要望・PRによる貢献を呼びかけている

[jessyt]

事例を中心に書いてくださっているので、参考になる点が多いですね！