nb-cli - CLI cho tác tử AI và tự động hóa notebook

• Một công cụ CLI mã nguồn mở mang tính thử nghiệm, được thiết kế để giúp các tác tử lập trình AI xử lý notebook như một artifact, được xây dựng bằng Rust để hỗ trợ thao tác notebook nhanh và ổn định
• Nhằm giải quyết vấn đề cấu trúc JSON .ipynb không phù hợp cho tự động hóa và xử lý bởi LLM, công cụ này cung cấp các chức năng đọc, ghi, chạy và tìm kiếm qua dòng lệnh trong khi vẫn tuân theo đặc tả nbformat
• Hoạt động ngay cả khi không có máy chủ Jupyter; khi kết nối máy chủ, công cụ hỗ trợ chỉnh sửa cộng tác thời gian thực bằng chính giao thức Y.js CRDT như JupyterLab
• Thiết kế mới một định dạng Markdown tối ưu cho AI dựa trên sentinel như @@cell, @@output để tăng hiệu quả ngữ cảnh cho LLM
• Tích hợp các tính năng phù hợp với workflow của tác tử như khả năng kết hợp kiểu Unix, tham chiếu ô ổn định, tìm kiếm mạnh, thao tác hàng loạt trên nhiều ô và thực thi nhận biết môi trường

---

Bối cảnh: vấn đề “hộp đen” của notebook

• Khi các tác tử lập trình AI nổi lên, định nghĩa về công cụ dành cho nhà phát triển cũng đang thay đổi; các LLM như Claude hay GPT được huấn luyện từ khối lượng lớn ví dụ sử dụng CLI trong tài liệu, Stack Overflow và GitHub nên rất thành thạo trong việc dùng giao diện dòng lệnh
• Các công cụ hiện có chủ yếu tập trung vào việc chạy tác tử bên trong notebook, nhưng vẫn còn thiếu công cụ cho các tác tử xử lý chính notebook như một artifact
• Cấu trúc JSON .ipynb của Jupyter notebook tạo ra ma sát khiến việc xử lý theo lập trình trở nên khó khăn trong shell script và với LLM
• Giao diện hiện có chưa đủ tốt cho các kịch bản sau, nơi tự động hóa và phân tích bằng AI là cần thiết
  • Phân tích tự chủ: tác tử AI kiểm tra một workflow khoa học dữ liệu cần hiểu pipeline ở cấp độ từng ô
  • Xác minh tự động: hệ thống CI/CD phải chạy notebook, xác thực đầu ra và bắt lỗi trước
  • Tài liệu hóa quy mô lớn: nội dung notebook cần được tự động chuyển thành tài liệu gọn gàng
  • Gỡ lỗi trong môi trường vận hành: cần chẩn đoán lỗi chạy notebook trong môi trường headless mà không phải can thiệp thủ công
  • Notebook như dữ liệu: xử lý notebook như một cơ sở dữ liệu có cấu trúc để tạo báo cáo, tóm tắt và trực quan hóa
• Trước đây, cách làm phổ biến là thao tác thủ công qua giao diện JupyterLab, viết script Python mong manh để parse JSON phức tạp, hoặc dùng công cụ thực thi không có tích hợp thời gian thực
• nb-cli sử dụng giao diện ưu tiên CLI và khả năng kết hợp kiểu Unix để biến notebook thành công dân hạng nhất trong software stack

Tính năng cốt lõi

• Hoạt động bất kể có hay không có máy chủ Jupyter

  • Mặc định đọc và ghi trực tiếp tệp .ipynb, đồng thời giao tiếp trực tiếp với kernel qua ZeroMQ để thực thi
  • Phù hợp với script và pipeline CI không cần chạy máy chủ
    • Tạo notebook không cần máy chủ bằng nb create analysis.ipynb
    • Có thể thêm ô, chạy và xem kết quả bằng các lệnh nb cell add, nb execute, nb read
  • Khi nhiều người dùng hoặc tác tử cùng chỉnh sửa một notebook đồng thời, kết nối máy chủ sẽ hữu ích; công cụ cung cấp đồng bộ thời gian thực không xung đột bằng chính giao thức Y.js CRDT mà JupyterLab dùng nội bộ
    • Dùng nb connect để tự động phát hiện máy chủ cục bộ, hoặc chỉ định máy chủ/token cụ thể bằng tùy chọn --server
    • Hỗ trợ chạy lại với khởi động lại kernel qua tùy chọn --restart-kernel để kiểm tra tính tái lập
  • Khi có kết nối máy chủ, công cụ phát hiện notebook có đang mở trong JupyterLab hay không; nếu chưa mở, nó sẽ tự nhiên fallback về chế độ dựa trên tệp

• Định dạng Markdown tối ưu cho AI

  • Mô hình ngôn ngữ không parse JSON mà dự đoán token, nên JSON Jupyter lồng sâu rất kém hiệu quả trong cửa sổ ngữ cảnh
  • Định dạng mặc định của Jupyter có source là mảng chuỗi, output là blob base64 và metadata lồng nhiều lớp, nên với LLM, 30~40% token bị tiêu tốn vô nghĩa vào các ký tự cấu trúc như ngoặc nhọn, ngoặc vuông và escape
  • Markdown thông thường hiệu quả về token nhưng lại rất mơ hồ
    • Không thể phân biệt # là heading Markdown hay comment Python
    • Không thể phân biệt code fence là ô notebook hay ví dụ trong tài liệu
    • Khi nói “hãy sửa lỗi ở ô số 7”, không có marker cấu trúc để nhận diện vị trí ô một cách ổn định
  • Để giải quyết điều này, dự án đã thiết kế định dạng sentinel theo từng dòng
    • Cung cấp ranh giới cấu trúc rõ ràng bằng các sentinel như @@notebook, @@cell, @@output
    • Trên dòng sentinel, ghi metadata JSON inline như loại ô, chỉ số và số lần thực thi, phù hợp với cách cơ chế attention tìm thông tin
    • Kích hoạt việc học cú pháp của mô hình bằng code fence có gợi ý ngôn ngữ
    • Mỗi khối ô là một đơn vị tự hoàn chỉnh nên nếu bị cắt thì chỉ hỏng dần dần, thay vì làm vỡ toàn bộ cấu trúc như JSON khi bị cắt ở một điểm

• Thiết kế có thể kết hợp

  • Theo quy ước Unix, công cụ cung cấp đầu ra plain text, hỗ trợ stdin và mã thoát có thể dự đoán được
  • Với tác tử, một lệnh shell duy nhất có thể thay thế nhiều lần gọi công cụ và bước parse trung gian
  • Những tác vụ như “thêm phần tóm tắt vào notebook rồi chạy” có thể được xử lý bằng một lần gọi shell duy nhất cho việc thêm ô, chạy và đọc kết quả
    • Chain theo kiểu nb cell add ... && nb execute ... && nb read ...
    • Tác tử chỉ nhận đúng phần output cần thiết mà không phải đọc lại toàn bộ notebook
  • Nguyên tắc tương tự cũng áp dụng cho gỡ lỗi
    • Chỉ với nb search analysis.ipynb --with-errors, công cụ trả về đúng các ô bị lỗi, không lãng phí token vào các ô chạy thành công

• Tham chiếu ô ổn định

  • Hỗ trợ hai cách tham chiếu ô
    • Dựa trên chỉ số --cell-index 0 (hỗ trợ chỉ số âm, -1 là ô cuối)
    • Dựa trên ID --cell f68t57 (không đổi ngay cả khi ô bị di chuyển)
  • Có thể tham chiếu theo vị trí như nb cell update ... --cell-index 0 --source "x = 42"
  • Hoặc tham chiếu bằng ID ổn định như nb cell update ... --cell ce456 --source "print('Done')", an toàn cả khi các ô bị sắp xếp lại

• Khả năng tìm kiếm mạnh mẽ

  • Có thể nhanh chóng tìm vị trí theo nội dung ô, loại ô và lỗi thực thi
  • Mặc định là khớp với source code của ô, và có thể mở rộng sang output thực thi bằng bộ lọc scope
    • Tìm mẫu bằng nb search analysis.ipynb "import pandas"
    • Chỉ trích xuất các ô lỗi bằng nb search analysis.ipynb --with-errors
    • Tìm trong output bằng nb search analysis.ipynb "KeyError" --scope output
    • Lọc theo loại ô bằng nb search analysis.ipynb "TODO" --cell-type markdown
  • Tác tử có thể dùng --with-errors để chỉ nhận các ô thất bại, và kết hợp với --scope output để tìm trực tiếp traceback lỗi
  • Con người cũng có thể dùng để audit deprecated API, xác định vị trí hàm trong notebook lớn, hoặc trích xuất pattern trước khi refactor

• Thao tác hàng loạt trên nhiều ô

  • Việc thêm chuỗi ô như heading Markdown → mã cấu hình → phân tích là mẫu phổ biến; nếu thêm từng ô một sẽ tăng số lần round-trip và gánh nặng quản lý chỉ số
  • Hỗ trợ thêm nhiều ô trong một lần gọi bằng định dạng sentinel
    • Có thể gói các khối @@markdown, @@code trong heredoc để gửi một lần
    • Cũng hỗ trợ định dạng JSON đầy đủ như @@cell {"cell_type": "..."}
  • Tương thích với stdin nên dễ dựng ô trong script và pipeline
    • printf '@@markdown\n## Summary\n\n@@code\ndf.describe()\n' | nb cell add report.ipynb --source -
  • Triết lý xử lý hàng loạt tương tự cũng áp dụng cho thực thi và xóa
    • Chạy theo phạm vi bằng nb execute analysis.ipynb --start 2 --end 5
    • Xóa ô cụ thể bằng nb cell delete analysis.ipynb -i 0 -i 2
    • Xóa theo phạm vi bằng nb cell delete analysis.ipynb --range 0:3

• Thực thi nhận biết môi trường

  • nb connect, nb execute, nb create hỗ trợ các cờ --uv, --pixi để tìm máy chủ Jupyter và kernel qua đúng trình quản lý môi trường tương ứng
  • nb status --python trả về tiền tố lệnh để chạy Python trong cùng môi trường với kernel đã kết nối
    • Ví dụ giá trị trả về: "uv run", "pixi run", hoặc chuỗi rỗng nếu là Python hệ thống
    • Có thể dùng trong pipeline theo dạng $(nb status --python) python -c "..."

Các trường hợp sử dụng thực tế

• Workflow của tác tử AI

  • Có thể thao tác notebook như một phần của workflow phân tích bằng cách nối các lệnh tìm ô lỗi → sửa mã → chạy lại
    • 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

• Tích hợp CI/CD

  • Thực hiện kiểm thử và xác minh tự động cho notebook trong pipeline tích hợp liên tục
    • Chạy bằng nb execute pipeline.ipynb --allow-errors, sau đó nếu nb search ... --with-errors phát hiện lỗi thì trả về mã thoát 1
    • Dọn output trước khi commit bằng nb output clear

• Tạo notebook theo cách lập trình

  • Tự động tạo tài liệu, báo cáo và phân tích
    • Tạo notebook báo cáo bằng nb create report.ipynb
    • Dùng lệnh multicell để thêm tiêu đề, giới thiệu và mã phân tích một lần, rồi điền output bằng nb execute

• Gỡ lỗi notebook trong môi trường vận hành

  • Chẩn đoán nhanh sự cố của notebook đã triển khai
    • Trích xuất ô lỗi bằng nb search failing_notebook.ipynb --with-errors
    • Tìm việc dùng deprecated API bằng nb search analysis.ipynb "pandas.np"
    • Tìm pattern có rủi ro bảo mật bằng nb search notebook.ipynb "eval("
    • Xem toàn bộ output của ô cụ thể bằng nb read failing_notebook.ipynb --cell-index 5
    • Kiểm tra khả năng tái lập sạch bằng nb execute failing_notebook.ipynb --restart-kernel

Ví dụ hoạt động thực tế

• Example 1: Tạo notebook huấn luyện RL cho LLM bằng Claude

  • Prompt của người dùng: tạo một notebook bao quát các khái niệm cốt lõi như policy model, reward model, KL divergence penalty, PPO, GRPO, và giải thích cơ chế hoạt động ở từng ô
  • Sử dụng mô hình đồ chơi cỡ nhỏ dựa trên từ vựng nhỏ và GRU để có thể chạy toàn bộ trên CPU mà không cần API key

• Example 2: Sửa nhiều lỗi trong notebook bằng Codex

  • Prompt của người dùng: sửa churn_analysis.ipynb chưa được cập nhật từ sau năm 2023 để có thể chạy sạch từ đầu đến cuối, xác định–sửa–xác minh từng ô lỗi, và thêm ghi chú Markdown phía trên các ô đã sửa để giải thích vấn đề là gì và đã sửa như thế nào
  • 4 lỗi mà Codex đã sửa
    • Đường dẫn tệp được hard-code
    • DataFrame.append() đã bị loại bỏ trong pandas 2.0
    • sklearn.cross_validation đã bị loại bỏ trong sklearn 0.20
    • plot_confusion_matrix đã bị loại bỏ trong sklearn 1.2
  • Xác minh rằng sau khi sửa, notebook chạy end-to-end bình thường

Bắt đầu sử dụng

• Cung cấp ba cách cài đặt: script cài đặt, cargo install nb-cli, và build từ source bằng cargo build --release
• Khi build, binary được tạo tại target/release/nb
• Nếu muốn tác tử AI dùng nb cho mọi tác vụ notebook, công cụ hỗ trợ lệnh cài skill npx skills install jupyter-ai-contrib/nb-cli

Nhà phát triển và tham gia đóng góp

• Có 3 người đóng góp cho dự án Jupyter thuộc AWS tham gia phát triển
  • Andrii Ieroshenko: AWS Software Development Engineer, cộng tác viên lâu năm của JupyterLab và Jupyter AI, thành viên Jupyter Media Strategy Working Group
  • Brian Granger: AWS Senior Principal Technologist, đồng sáng lập Project Jupyter, thành viên hội đồng của Jupyter và PyTorch Foundation
  • Piyush Jain: AWS Principal Engineer, phụ trách Jupyter và Agentic AI, thành viên Jupyter Server Council
• nb-cli hiện còn ở giai đoạn đầu; sau khi cài đặt và sử dụng, dự án mong người dùng gửi issue trên GitHub, tham gia thảo luận trong jupyter-ai-contrib, và đóng góp qua báo cáo lỗi, yêu cầu tính năng hoặc PR

[jessyt]

Bạn viết theo hướng nhiều ví dụ thực tế nên có rất nhiều điểm để mình tham khảo!