nb-cli - CLI para agentes de IA y automatización de notebooks

• Herramienta CLI experimental de código abierto diseñada para que los agentes de codificación con IA puedan tratar los notebooks como artefactos, implementada en Rust para permitir una manipulación rápida y estable de notebooks
• Para resolver el problema de que la estructura JSON de .ipynb no es adecuada para la automatización ni para el procesamiento con LLM, ofrece desde la línea de comandos funciones de lectura, escritura, ejecución y búsqueda cumpliendo con la especificación nbformat
• Funciona incluso sin un servidor Jupyter y, cuando se conecta a uno, admite edición colaborativa en tiempo real con el mismo protocolo CRDT de Y.js que usa JupyterLab
• Para mejorar la eficiencia del contexto en LLM, diseña un nuevo formato Markdown optimizado para IA basado en sentinelas como @@cell y @@output
• Integra funciones orientadas a flujos de trabajo de agentes como componibilidad tipo Unix, referencias estables de celdas, búsqueda potente, manipulación masiva de múltiples celdas y ejecución consciente del entorno

---

Contexto: el problema de “caja negra” de los notebooks

• Con el auge de los agentes de codificación con IA, está cambiando la definición de las herramientas para desarrolladores, y los LLM como Claude y GPT han sido entrenados con enormes cantidades de casos de uso de CLI en documentación, Stack Overflow y GitHub, por lo que son muy hábiles usando interfaces de línea de comandos
• Las herramientas existentes se han enfocado en ejecutar agentes dentro del notebook, pero faltaban herramientas para agentes que traten al notebook mismo como artefacto
• La estructura JSON de .ipynb en los notebooks de Jupyter genera fricción para su procesamiento programático en scripts de shell y LLM
• La interfaz tradicional se queda corta en los siguientes escenarios que requieren automatización y análisis con IA
  • Análisis autónomo: un agente de IA que audita flujos de trabajo de ciencia de datos necesita entender el pipeline a nivel de celdas
  • Validación automática: un sistema CI/CD debe ejecutar notebooks, validar salidas y detectar errores con anticipación
  • Documentación a gran escala: se necesita convertir automáticamente el contenido del notebook en documentación ordenada
  • Depuración en entornos operativos: se necesita diagnosticar fallos en la ejecución de notebooks en entornos sin interfaz gráfica y sin intervención manual
  • Notebooks como datos: tratar notebooks como si fueran una base de datos estructurada para generar reportes, resúmenes y visualizaciones
• Hasta ahora, lo común era manipular manualmente la UI de JupyterLab, escribir scripts frágiles en Python que parseaban JSON complejo o usar herramientas de ejecución sin integración en tiempo real
• nb-cli aprovecha una interfaz orientada primero a CLI y la componibilidad de Unix para tratar a los notebooks como ciudadanos de primera clase dentro del stack de software

Funciones principales

• Funciona con o sin servidor Jupyter

  • Por defecto lee y escribe directamente archivos .ipynb, y ejecuta comunicándose directamente con el kernel mediante ZeroMQ
  • Es ideal para scripts y pipelines de CI donde no hace falta levantar un servidor
    • nb create analysis.ipynb crea un notebook sin servidor
    • Con nb cell add, nb execute y nb read se pueden agregar celdas, ejecutarlas y consultar resultados
  • Cuando varios usuarios o agentes editan simultáneamente el mismo notebook, conectarse al servidor resulta útil, y ofrece sincronización en tiempo real sin conflictos con el mismo protocolo CRDT de Y.js que usa internamente JupyterLab
    • nb connect detecta automáticamente un servidor local, y la opción --server permite indicar un servidor o token específicos
    • La opción --restart-kernel permite ejecutar reiniciando el kernel para verificar la reproducibilidad
  • Al conectarse al servidor, detecta si el notebook está abierto en JupyterLab y, si no lo está, hace fallback de forma natural al modo basado en archivos

• Formato Markdown optimizado para IA

  • Los modelos de lenguaje no parsean JSON; predicen tokens, por lo que el JSON profundamente anidado de Jupyter es ineficiente dentro de la ventana de contexto
  • En el formato predeterminado de Jupyter, el código fuente está en arreglos de cadenas, la salida en blobs base64 y los metadatos en múltiples niveles de anidación, así que para un LLM entre el 30% y el 40% de los tokens se desperdician en caracteres estructurales como llaves, corchetes y escapes
  • El Markdown común es eficiente en tokens, pero muy ambiguo
    • No se puede distinguir si # es un encabezado Markdown o un comentario de Python
    • No se puede distinguir si un bloque de código es una celda de notebook o un ejemplo dentro del documento
    • Si se pide “corrige el error de la celda 7”, faltan marcadores estructurales para identificar de forma estable la posición de la celda
  • Para resolver esto se diseñó un formato basado en sentinelas por línea
    • Sentinelas como @@notebook, @@cell y @@output ofrecen límites estructurales claros
    • En la línea sentinela se indican con metadatos JSON inline el tipo de celda, índice y número de ejecución, alineándose con la forma en que el mecanismo de atención encuentra información
    • Los bloques de código con pistas de lenguaje activan el aprendizaje sintáctico del modelo
    • Cada bloque de celda es autocontenido, así que si se recorta, el daño es gradual, a diferencia del JSON donde un solo corte puede romper toda la estructura

• Diseño componible

  • Siguiendo las convenciones de Unix, ofrece salida en texto plano, soporte para stdin y códigos de salida predecibles
  • Desde la perspectiva de un agente, un solo comando de shell puede reemplazar múltiples llamadas a herramientas y parseo intermedio
  • Tareas como “agrega una sección de resumen al notebook y ejecútalo” pueden resolverse con una sola invocación de shell que agregue celdas, ejecute y lea resultados
    • Encadenando comandos como nb cell add ... && nb execute ... && nb read ...
    • El agente recibe solo la salida necesaria sin releer todo el notebook
  • El mismo principio aplica a la depuración
    • nb search analysis.ipynb --with-errors devuelve en una sola vez solo las celdas con error, sin desperdiciar tokens en las celdas exitosas

• Referencias estables de celdas

  • Soporta dos formas de referenciar celdas
    • Basada en índice --cell-index 0 (con soporte para índices negativos; -1 es la última celda)
    • Basada en ID --cell f68t57 (no cambia aunque la celda se mueva)
  • Se puede referenciar por posición, como en nb cell update ... --cell-index 0 --source "x = 42"
  • O referenciar por ID estable, como en nb cell update ... --cell ce456 --source "print('Done')", de forma segura incluso si las celdas se reordenan

• Búsqueda potente

  • Permite ubicar rápidamente por contenido de celda, tipo o errores de ejecución
  • Por defecto busca coincidencias en el código fuente de las celdas, y con filtros de alcance puede ampliarse hasta la salida de ejecución
    • nb search analysis.ipynb "import pandas" busca un patrón
    • nb search analysis.ipynb --with-errors extrae solo las celdas con error
    • nb search analysis.ipynb "KeyError" --scope output busca dentro de la salida
    • nb search analysis.ipynb "TODO" --cell-type markdown filtra por tipo de celda
  • Un agente puede usar --with-errors para recibir y procesar solo las celdas fallidas, y combinarlo con --scope output para buscar directamente trazas de error
  • También sirve para auditorías de APIs obsoletas, ubicar funciones en notebooks grandes y extraer patrones antes de refactorizar

• Manipulación masiva de múltiples celdas

  • Agregar secuencias de celdas como encabezado Markdown → código de configuración → análisis es un patrón común, y añadirlas una por una aumenta la cantidad de idas y vueltas y la carga de manejar índices
  • Soporta agregar varias celdas en una sola llamada con formato sentinela
    • Se pueden agrupar bloques @@markdown y @@code en un heredoc para enviarlos de una vez
    • También admite el formato JSON completo como @@cell {"cell_type": "..."}
  • También es compatible con stdin, lo que facilita construir celdas desde scripts y pipelines
    • printf '@@markdown\n## Summary\n\n@@code\ndf.describe()\n' | nb cell add report.ipynb --source -
  • La misma filosofía de procesamiento por lotes se aplica a la ejecución y el borrado
    • nb execute analysis.ipynb --start 2 --end 5 ejecuta un rango
    • nb cell delete analysis.ipynb -i 0 -i 2 elimina celdas específicas
    • nb cell delete analysis.ipynb --range 0:3 elimina un rango

• Ejecución consciente del entorno

  • nb connect, nb execute y nb create admiten las banderas --uv y --pixi, y buscan servidores Jupyter y kernels con ese gestor de entorno
  • nb status --python devuelve el prefijo de comando para ejecutar Python en el mismo entorno que el kernel conectado
    • Ejemplos de valores devueltos: "uv run", "pixi run"; en el caso de Python del sistema, devuelve un valor vacío
    • Se puede usar en pipelines con una forma como $(nb status --python) python -c "..."

Casos de uso reales

• Flujos de trabajo con agentes de IA

  • Es posible manipular notebooks como parte de un flujo de análisis encadenando comandos para localizar celdas fallidas, corregir código y volver a ejecutar
    • 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

• Integración con CI/CD

  • Permite hacer pruebas y validación automáticas de notebooks en pipelines de integración continua
    • Tras ejecutar con nb execute pipeline.ipynb --allow-errors, si nb search ... --with-errors detecta errores, devuelve código de salida 1
    • Antes del commit se puede limpiar la salida con nb output clear

• Generación programática de notebooks

  • Permite generar automáticamente documentación, reportes y análisis
    • nb create report.ipynb crea un notebook de reporte
    • Con un comando multicelda se agregan de una vez título, introducción y código de análisis, y luego nb execute llena las salidas

• Depuración de notebooks en entornos operativos

  • Permite diagnosticar rápidamente problemas en notebooks desplegados
    • nb search failing_notebook.ipynb --with-errors extrae las celdas con error
    • nb search analysis.ipynb "pandas.np" busca uso de APIs obsoletas
    • nb search notebook.ipynb "eval(" busca patrones con implicaciones de seguridad
    • nb read failing_notebook.ipynb --cell-index 5 revisa la salida completa de una celda específica
    • nb execute failing_notebook.ipynb --restart-kernel verifica reproducibilidad limpia

Ejemplos reales de funcionamiento

• Example 1: crear con Claude un notebook para aprender RL con LLM

  • Prompt del usuario: crear un notebook que cubra conceptos clave como modelo de política, modelo de recompensa, penalización por KL divergence, PPO y GRPO, explicando cómo funciona cada uno en cada celda
  • Se usa un modelo toy pequeño basado en vocabulario reducido y GRU para que toda la ejecución sea posible en CPU y sin API key

• Example 2: corregir múltiples bugs de un notebook con Codex

  • Prompt del usuario: corregir churn_analysis.ipynb, que no se actualiza desde 2023, para que se ejecute limpiamente de principio a fin; identificar, corregir y validar cada celda fallida, y agregar encima de cada celda modificada una nota en Markdown explicando qué problema había y cómo se resolvió
  • Los 4 bugs corregidos por Codex
    • Ruta de archivo hardcodeada
    • DataFrame.append() eliminado en pandas 2.0
    • sklearn.cross_validation, eliminado en sklearn 0.20
    • plot_confusion_matrix, eliminado en sklearn 1.2
  • Después de las correcciones se verificó que el notebook se ejecuta correctamente de extremo a extremo

Cómo empezar

• Ofrece tres rutas de instalación: script de instalación, cargo install nb-cli y compilación desde el código fuente (cargo build --release)
• Al compilar, el binario se genera en target/release/nb
• Para que un agente de IA use nb en todas las tareas relacionadas con notebooks, admite el comando de instalación de skills npx skills install jupyter-ai-contrib/nb-cli

Desarrolladores y participación

• Participan en el desarrollo tres contribuyentes del proyecto Jupyter que trabajan en AWS
  • Andrii Ieroshenko: AWS Software Development Engineer, colaborador de larga trayectoria en JupyterLab y Jupyter AI, miembro del Jupyter Media Strategy Working Group
  • Brian Granger: AWS Senior Principal Technologist, cofundador de Project Jupyter, miembro de las juntas de Jupyter y PyTorch Foundation
  • Piyush Jain: AWS Principal Engineer, responsable de Jupyter y Agentic AI, miembro del Jupyter Server Council
• nb-cli está en una etapa temprana, y se invita a instalarlo y usarlo, registrar issues en GitHub, participar en las discusiones de jupyter-ai-contrib y contribuir mediante reportes de bugs, solicitudes de funciones y PR

[jessyt]

Como está escrito con base en casos reales, hay mucho que tomar como referencia.