▲

nb-cli - AI 에이전트와 노트북 자동화를 위한 CLI

 (blog.jupyter.org)
1P by GN⁺ | ★ favorite | 댓글 1개
  • AI 코딩 에이전트가 Jupyter 노트북을 아티팩트로 다룰 수 있도록 설계된 실험적 오픈소스 CLI 도구로, Rust 기반으로 구현되어 빠르고 안정적인 노트북 조작을 지원
  • .ipynb JSON 구조가 자동화·LLM 처리에 적합하지 않다는 문제를 해결하기 위해, nbformat 사양을 따르면서 읽기·쓰기·실행·검색 기능을 명령줄로 제공
  • Jupyter 서버 없이도 동작하며, 서버에 연결할 경우 JupyterLab과 동일한 Y.js CRDT 프로토콜로 실시간 협업 편집 지원
  • LLM 컨텍스트 효율을 위해 @@cell, @@output 같은 센티넬 기반 AI 최적화 마크다운 포맷을 새롭게 설계
  • 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 조합성을 활용해, 노트북을 소프트웨어 스택의 1급 시민으로 다룰 수 있게 함

핵심 기능

  • 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 최적화 마크다운 포맷

    • 언어 모델은 JSON을 파싱하지 않고 토큰을 예측하므로, 깊게 중첩된 Jupyter JSON은 컨텍스트 윈도우에서 비효율적
    • Jupyter 기본 포맷은 소스가 문자열 배열, 출력이 base64 블롭, 메타데이터가 다층 중첩으로 구성되어 있어, LLM 입장에서 토큰의 30~40%가 중괄호·대괄호·이스케이프 같은 구조 문자로 의미 없이 소모됨
    • 일반 Markdown은 토큰 효율은 좋지만 모호함이 큼
      • #이 마크다운 헤딩인지 Python 주석인지 구분 불가
      • 코드 펜스가 노트북 셀인지 문서 내 예시인지 구분 불가
      • "7번 셀의 오류를 고쳐줘"라고 했을 때 셀 위치를 안정적으로 식별할 구조적 마커 부재
    • 이를 해결하기 위해 라인 단위 센티넬 포맷을 설계
      • @@notebook, @@cell, @@output 같은 센티넬로 명확한 구조 경계 제공
      • 센티넬 라인에 셀 타입·인덱스·실행 횟수를 인라인 JSON 메타데이터로 표기해, 어텐션 메커니즘이 정보를 찾는 방식과 정렬
      • 언어 힌트가 붙은 코드 펜스로 모델의 구문 학습 활성화
      • 각 셀 블록이 자기완결적이라 잘려도 점진적으로 손상되며, JSON처럼 한 군데 잘리면 전체 구조가 깨지는 문제가 없음

  • 조합 가능한 설계

    • Unix 관례를 따라 plain text 출력, stdin 지원, 예측 가능한 종료 코드 제공
    • 에이전트 입장에서 단일 셸 명령이 여러 번의 도구 호출·중간 파싱을 대체 가능
    • "노트북에 요약 섹션을 추가하고 실행" 같은 작업을, 셀 추가·실행·결과 읽기를 하나의 셸 호출로 처리 가능
      • nb cell add ... && nb execute ... && nb read ... 형태로 체이닝
      • 에이전트는 노트북 전체를 다시 읽지 않고 필요한 출력만 받음
    • 디버깅에도 동일 원칙 적용
      • nb search analysis.ipynb --with-errors 한 번으로 오류가 난 셀만 반환, 성공한 셀에 토큰을 낭비하지 않음

  • 안정적 셀 참조

    • 두 가지 셀 참조 방식 지원
      • 인덱스 기반 --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, @@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를 끝까지 깔끔히 실행되도록 수정, 실패 셀 각각을 식별·수정·검증하고, 변경 셀 위에 무엇이 어떻게 문제였는지 마크다운 노트 추가
    • 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) 세 가지 설치 경로 제공
  • 빌드 시 바이너리는 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 이슈 등록, jupyter-ai-contrib 디스커션 참여, 버그 리포트·기능 요청·PR을 통한 기여를 요청

함께 보면 좋은 글 β

▲
jessyt   [-]

사례 위주로 작성해주셔서 참고할게 많네요!

답변달기