nb-cli - AI एजेंट और notebook automation के लिए CLI

• यह एक experimental open source CLI टूल है, जिसे इस तरह डिज़ाइन किया गया है कि AI coding agents Jupyter notebooks को artifacts की तरह हैंडल कर सकें; यह Rust आधारित है और तेज़ व भरोसेमंद notebook manipulation को सपोर्ट करता है
• .ipynb JSON structure automation और LLM processing के लिए उपयुक्त नहीं है—इस समस्या को हल करने के लिए यह nbformat specification का पालन करते हुए read, write, execute और search features को command line पर उपलब्ध कराता है
• Jupyter server के बिना भी काम करता है, और server से connect करने पर JupyterLab के समान Y.js CRDT protocol के साथ real-time collaborative editing को सपोर्ट करता है
• LLM context efficiency के लिए @@cell, @@output जैसे sentinel-based AI-optimized Markdown format को नए सिरे से डिज़ाइन किया गया है
• Unix composability, stable cell references, powerful search, multi-cell batch operations, environment-aware execution जैसे agent workflows के अनुरूप features एकीकृत रूप से प्रदान करता है

---

पृष्ठभूमि: notebooks की “black box” समस्या

• AI coding agents के उभरने के साथ developer tools की परिभाषा बदल रही है, और Claude, GPT जैसे LLMs documents, Stack Overflow और GitHub पर मौजूद विशाल CLI use cases से प्रशिक्षित होने के कारण command-line interfaces का उपयोग करने में बेहद सक्षम हैं
• मौजूदा tools अब तक notebooks के अंदर agents चलाने पर केंद्रित रहे हैं, लेकिन notebook को स्वयं artifact की तरह ट्रीट करने वाले agents के लिए tools का अभाव था
• Jupyter notebook का .ipynb JSON structure shell scripts और LLMs के लिए programmatic processing में friction point बनता है
• automation और AI analysis की ज़रूरत वाले नीचे दिए गए scenarios में मौजूदा interfaces पर्याप्त नहीं हैं
  • autonomous analysis: data science workflow को audit करने वाले AI agent को cell स्तर पर pipeline समझनी होती है
  • automated validation: CI/CD system को notebook execute करके outputs verify करने और errors पहले से पकड़ने चाहिए
  • large-scale documentation: notebook contents को अपने-आप साफ़-सुथरे documents में बदलना चाहिए
  • production environment debugging: headless environments में notebook execution failures का manual intervention के बिना diagnosis होना चाहिए
  • notebooks as data: notebooks को structured database की तरह ट्रीट करके reports, summaries और visualizations बनाना
• अब तक आम तौर पर JupyterLab UI को manually चलाना, जटिल JSON को parse करने वाले fragile Python scripts लिखना, या real-time integration के बिना execution tools इस्तेमाल करना पड़ता था
• nb-cli CLI-first interface और Unix composability का उपयोग करके notebooks को software stack का first-class citizen बनाता है

मुख्य features

• Jupyter server हो या न हो, काम करता है

  • डिफ़ॉल्ट रूप से यह सीधे .ipynb files को पढ़ता और लिखता है, और ZeroMQ के ज़रिए kernel से सीधे communicate करके execution करता है
  • यह उन scripts और CI pipelines के लिए उपयुक्त है जहाँ server चलाने की ज़रूरत नहीं होती
    • nb create analysis.ipynb से server के बिना notebook बनाएं
    • nb cell add, nb execute, nb read commands से cells जोड़ना, execute करना और results देखना संभव है
  • जब कई users या agents एक ही notebook को एक साथ edit कर रहे हों, तब server connection उपयोगी होता है; यह JupyterLab द्वारा अंदरूनी रूप से इस्तेमाल किए जाने वाले Y.js CRDT protocol के साथ conflict-free real-time sync प्रदान करता है
    • nb connect से local server auto-detect होता है, और --server option से किसी specific server या token को specify किया जा सकता है
    • --restart-kernel option reproducibility check के लिए kernel restart execution को सपोर्ट करता है
  • server connection होने पर यह detect करता है कि notebook JupyterLab में खुली है या नहीं; अगर नहीं, तो स्वाभाविक रूप से file-based mode पर fallback हो जाता है

• AI-optimized Markdown format

  • language models JSON parse नहीं करते, बल्कि tokens predict करते हैं; इसलिए deeply nested Jupyter JSON context window में inefficient होता है
  • Jupyter का default format source को string arrays, outputs को base64 blobs, और metadata को multi-layer nesting के रूप में रखता है, इसलिए LLM के नज़रिए से 30~40% tokens braces, brackets, escapes जैसे structural characters पर बेकार खर्च हो जाते हैं
  • सामान्य Markdown token efficiency में अच्छा है, लेकिन उसमें ambiguity अधिक होती है
    • # Markdown heading है या Python comment, यह स्पष्ट नहीं होता
    • code fence notebook cell है या document के भीतर example, यह स्पष्ट नहीं होता
    • "cell 7 की error ठीक करो" कहने पर cell position को स्थिर रूप से पहचानने के लिए structural markers नहीं होते
  • इसे हल करने के लिए line-based sentinel format डिज़ाइन किया गया
    • @@notebook, @@cell, @@output जैसे sentinels स्पष्ट structural boundaries देते हैं
    • sentinel lines में cell type, index, execution count को inline JSON metadata के रूप में दिखाया जाता है, जो attention mechanism द्वारा जानकारी खोजने के तरीके के अनुरूप है
    • language hints वाले code fences model के syntax learning को सक्रिय करते हैं
    • हर cell block self-contained होता है, इसलिए कटने पर क्रमिक रूप से क्षतिग्रस्त होता है; JSON की तरह एक जगह कटते ही पूरा structure नहीं टूटता

• composable design

  • Unix conventions का पालन करते हुए plain text output, stdin support और predictable exit codes देता है
  • agent के नज़रिए से एक single shell command कई tool calls और intermediate parsing की ज़रूरत को बदल सकती है
  • "notebook में summary section जोड़ो और execute करो" जैसे tasks को cell add, execute और result read के रूप में एक ही shell call में हैंडल किया जा सकता है
    • nb cell add ... && nb execute ... && nb read ... जैसी chaining
    • agent को पूरी notebook दोबारा पढ़ने के बजाय सिर्फ़ ज़रूरी output मिलता है
  • debugging में भी वही सिद्धांत लागू होता है
    • nb search analysis.ipynb --with-errors एक बार चलाने पर सिर्फ़ error वाले cells लौटते हैं, सफल cells पर tokens बर्बाद नहीं होते

• stable cell references

  • cell reference के दो तरीक़े सपोर्ट होते हैं
    • index-based --cell-index 0 (negative indexing समर्थित है, -1 अंतिम cell है)
    • ID-based --cell f68t57 (cell move होने पर भी नहीं बदलता)
  • nb cell update ... --cell-index 0 --source "x = 42" की तरह position से reference किया जा सकता है
  • या nb cell update ... --cell ce456 --source "print('Done')" की तरह stable ID से reference करके cell reordering के बाद भी सुरक्षित रहा जा सकता है

• powerful search features

  • cell content, type और execution errors के आधार पर तेज़ी से लोकेशन खोजी जा सकती है
  • डिफ़ॉल्ट रूप से cell source code match होता है, और scope filter के साथ execution output तक विस्तार किया जा सकता है
    • nb search analysis.ipynb "import pandas" pattern search
    • nb search analysis.ipynb --with-errors सिर्फ़ error cells निकालता है
    • nb search analysis.ipynb "KeyError" --scope output output में search
    • nb search analysis.ipynb "TODO" --cell-type markdown cell type से filter
  • agent --with-errors के साथ सिर्फ़ failed cells लेकर process कर सकता है, और --scope output के साथ error traceback सीधे खोज सकता है
  • इंसान भी deprecated API audit, बड़े notebooks में function location ढूँढने, और refactor से पहले patterns निकालने में इसका उपयोग कर सकते हैं

• multi-cell batch operations

  • Markdown header → setup code → analysis जैसे cell sequences जोड़ना एक आम pattern है; cells को एक-एक करके जोड़ने पर round trips और index management का बोझ बढ़ता है
  • sentinel format के साथ एक ही call में कई cells जोड़ने का support है
    • @@markdown, @@code blocks को heredoc में बाँधकर एक बार में भेजा जा सकता है
    • @@cell {"cell_type": "..."} जैसे full JSON format का भी support है
  • stdin compatible होने के कारण scripts और pipelines में cell composition आसान हो जाती है
    • printf '@@markdown\n## Summary\n\n@@code\ndf.describe()\n' | nb cell add report.ipynb --source -
  • यही batch-processing philosophy execution और deletion पर भी लागू होती है
    • nb execute analysis.ipynb --start 2 --end 5 range execution
    • nb cell delete analysis.ipynb -i 0 -i 2 specific cells delete
    • nb cell delete analysis.ipynb --range 0:3 range delete

• environment-aware execution

  • nb connect, nb execute, nb create में --uv, --pixi flags समर्थित हैं, जो संबंधित environment manager के माध्यम से Jupyter server और kernel खोजते हैं
  • nb status --python connected kernel के समान environment में Python चलाने के लिए command prefix लौटाता है
    • return values के उदाहरण: "uv run", "pixi run", और system Python के मामले में empty value
    • $(nb status --python) python -c "..." के रूप में pipeline में इस्तेमाल किया जा सकता है

वास्तविक उपयोग के मामले

• AI agent workflows

  • failed cell को ढूँढना → code ठीक करना → दोबारा execute करना जैसी commands जोड़कर analysis workflow के हिस्से के रूप में notebook manipulation किया जा सकता है
    • 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

  • continuous integration pipeline में notebooks की automated testing और validation की जा सकती है
    • nb execute pipeline.ipynb --allow-errors से execute करने के बाद, nb search ... --with-errors से errors मिलने पर exit code 1 लौटाया जाता है
    • commit से पहले nb output clear से outputs साफ़ किए जा सकते हैं

• programmatic notebook generation

  • documents, reports और analysis को अपने-आप generate किया जा सकता है
    • nb create report.ipynb से report notebook बनाएं
    • multi-cell command से title, introduction और analysis code एक साथ जोड़ें और nb execute से outputs भरें

• production environment notebook debugging

  • deployed notebook की समस्याओं का तेज़ diagnosis
    • nb search failing_notebook.ipynb --with-errors से error cells निकालें
    • nb search analysis.ipynb "pandas.np" से deprecated API usage खोजें
    • nb search notebook.ipynb "eval(" से security concern patterns खोजें
    • nb read failing_notebook.ipynb --cell-index 5 से किसी specific cell का पूरा output देखें
    • nb execute failing_notebook.ipynb --restart-kernel से clean reproducibility check करें

वास्तविक काम करने के उदाहरण

• Example 1: Claude से LLM reinforcement learning training notebook बनाना

  • user prompt: एक ऐसा notebook बनाओ जो policy model, reward model, KL divergence penalty, PPO, GRPO जैसे core concepts को cover करे, और हर cell में उसके working principles समझाए
  • इसे छोटे vocabulary और GRU आधारित small toy model के साथ इस तरह बनाया गया कि API key के बिना CPU पर end-to-end execute किया जा सके

• Example 2: Codex से notebook के multiple bugs ठीक करना

  • user prompt: 2023 के बाद update न हुए churn_analysis.ipynb को अंत तक साफ़-सुथरे तरीके से execute होने लायक ठीक करो; हर failed cell की पहचान करो, उसे fix करो, verify करो, और बदले गए cell के ऊपर Markdown note जोड़ो कि समस्या क्या थी और कैसे ठीक की गई
  • Codex द्वारा ठीक किए गए 4 bugs
    • hardcoded file paths
    • pandas 2.0 में हटाया गया DataFrame.append()
    • sklearn 0.20 में हटाया गया sklearn.cross_validation
    • sklearn 1.2 में हटाया गया plot_confusion_matrix
  • fix के बाद notebook के end-to-end सही चलने की पुष्टि की गई

शुरुआत करना

• installation script, cargo install nb-cli, और source build (cargo build --release)—ये तीन installation paths उपलब्ध हैं
• build होने पर binary target/release/nb में बनती है
• अगर आप चाहते हैं कि AI agent notebook के सभी tasks में nb का उपयोग करे, तो skill installation command npx skills install jupyter-ai-contrib/nb-cli समर्थित है

डेवलपर्स और भागीदारी

• AWS से जुड़े Jupyter project के 3 contributors इसके development में शामिल हैं
  • Andrii Ieroshenko: AWS Software Development Engineer, JupyterLab और Jupyter AI के long-term contributor, Jupyter Media Strategy Working Group member
  • Brian Granger: AWS Senior Principal Technologist, Project Jupyter के सह-संस्थापक, Jupyter और PyTorch Foundation board member
  • Piyush Jain: AWS Principal Engineer, Jupyter और Agentic AI से जुड़े, Jupyter Server Council member
• nb-cli अभी शुरुआती चरण में है; installation और usage के बाद GitHub issues दर्ज करने, jupyter-ai-contrib discussions में भाग लेने, और bug reports, feature requests, PRs के माध्यम से योगदान देने का अनुरोध किया गया है

[jessyt]

आपने इसे उदाहरणों के आधार पर लिखा है, इसलिए रेफ़रेंस के लिए काफी कुछ मिल गया!