nb-cli - CLI para automação de notebooks com agentes de IA

• Ferramenta experimental de código aberto em CLI, projetada para permitir que agentes de codificação com IA tratem notebooks como artefatos, implementada em Rust para oferecer manipulação de notebooks rápida e estável
• Para resolver o problema de que a estrutura JSON de .ipynb não é adequada para automação e processamento por LLMs, fornece leitura, escrita, execução e busca via linha de comando, seguindo a especificação nbformat
• Funciona sem servidor Jupyter e, quando conectada a um servidor, oferece edição colaborativa em tempo real com o mesmo protocolo Y.js CRDT usado pelo JupyterLab
• Para melhorar a eficiência de contexto de LLMs, foi criado um novo formato Markdown otimizado para IA com sentinelas como @@cell e @@output
• Reúne recursos voltados para fluxos de trabalho de agentes como composabilidade Unix, referência estável de células, busca avançada, manipulação em lote de múltiplas células e execução com reconhecimento de ambiente

---

Contexto: o problema da “caixa-preta” dos notebooks

• Com a ascensão dos agentes de codificação com IA, a definição de ferramentas de desenvolvimento está mudando, e LLMs como Claude e GPT foram treinados com vastos casos de uso de CLI em documentação, Stack Overflow e GitHub, sendo muito competentes no uso de interfaces de linha de comando
• As ferramentas existentes vinham focando em executar agentes dentro de notebooks, mas faltavam ferramentas para agentes que tratam o próprio notebook como artefato
• A estrutura JSON .ipynb dos notebooks Jupyter funciona como um ponto de atrito para processamento programático em scripts shell e LLMs
• As interfaces existentes são insuficientes para os cenários a seguir, que exigem automação e análise por IA
  • Análise autônoma: um agente de IA que audita workflows de ciência de dados precisa entender o pipeline no nível de célula
  • Validação automática: sistemas de CI/CD precisam executar notebooks, validar saídas e detectar erros antecipadamente
  • Documentação em escala: é necessário converter automaticamente o conteúdo de notebooks em documentação limpa
  • Depuração em ambiente operacional: falhas na execução de notebooks em ambientes headless precisam ser diagnosticadas sem intervenção manual
  • Notebook como dado: tratar notebooks como um banco de dados estruturado para gerar relatórios, resumos e visualizações
• Até agora, o comum era manipular manualmente a UI do JupyterLab, escrever scripts Python frágeis para fazer parsing de JSON complexo, ou usar ferramentas de execução sem integração em tempo real
• O nb-cli usa uma interface CLI em primeiro lugar e a composabilidade Unix para permitir que notebooks sejam tratados como cidadãos de primeira classe na stack de software

Principais recursos

• Funciona com ou sem servidor Jupyter

  • Por padrão, lê e grava arquivos .ipynb diretamente e executa comunicando-se diretamente com o kernel via ZeroMQ
  • Adequado para scripts e pipelines de CI que não exigem um servidor em execução
    • nb create analysis.ipynb cria um notebook sem servidor
    • Comandos nb cell add, nb execute e nb read permitem adicionar células, executar e consultar resultados
  • Quando vários usuários ou agentes editam simultaneamente o mesmo notebook, a conexão com servidor é útil, oferecendo sincronização em tempo real sem conflitos com o mesmo protocolo Y.js CRDT usado internamente pelo JupyterLab
    • nb connect detecta automaticamente um servidor local, e a opção --server permite especificar servidor e token
    • A opção --restart-kernel permite reiniciar o kernel na execução para verificar reprodutibilidade
  • Ao se conectar a um servidor, detecta se o notebook está aberto no JupyterLab e, se não estiver, faz fallback naturalmente para operação baseada em arquivo

• Formato Markdown otimizado para IA

  • Modelos de linguagem não fazem parsing de JSON; eles predizem tokens, então o JSON profundamente aninhado do Jupyter é ineficiente na janela de contexto
  • No formato padrão do Jupyter, o código-fonte é um array de strings, a saída é um blob em base64 e os metadados são aninhados em múltiplas camadas; do ponto de vista de um LLM, 30% a 40% dos tokens são desperdiçados em caracteres estruturais como chaves, colchetes e escapes
  • Markdown comum é eficiente em tokens, mas ambíguo
    • Não dá para distinguir se # é um cabeçalho Markdown ou um comentário Python
    • Não dá para distinguir se uma cerca de código é uma célula de notebook ou um exemplo dentro da documentação
    • Ao pedir "corrija o erro da célula 7", faltam marcadores estruturais para identificar de forma estável a posição da célula
  • Para resolver isso, foi criado um formato com sentinelas por linha
    • Sentinelas como @@notebook, @@cell e @@output fornecem limites estruturais claros
    • A linha de sentinela registra tipo de célula, índice e contagem de execução com metadados JSON inline, alinhando-se à forma como o mecanismo de atenção encontra informações
    • Cercas de código com dica de linguagem ativam o aprendizado sintático do modelo
    • Cada bloco de célula é autocontido, então se deteriora gradualmente quando cortado, ao contrário do JSON, em que um corte em um ponto pode quebrar toda a estrutura

• Design componível

  • Segue as convenções Unix com saída em texto puro, suporte a stdin e códigos de saída previsíveis
  • Do ponto de vista do agente, um único comando shell pode substituir várias chamadas de ferramenta e parsing intermediário
  • Tarefas como “adicionar uma seção de resumo ao notebook e executá-la” podem ser tratadas com uma única chamada shell para adicionar célula, executar e ler o resultado
    • Encadeamento no formato nb cell add ... && nb execute ... && nb read ...
    • O agente recebe apenas a saída necessária, sem reler o notebook inteiro
  • O mesmo princípio vale para depuração
    • nb search analysis.ipynb --with-errors retorna apenas as células com erro em uma chamada, sem desperdiçar tokens nas células bem-sucedidas

• Referência estável de células

  • Suporta duas formas de referenciar células
    • Baseada em índice --cell-index 0 (com suporte a índice negativo; -1 é a última célula)
    • Baseada em ID --cell f68t57 (não muda mesmo que a célula seja movida)
  • É possível referenciar por posição, como em nb cell update ... --cell-index 0 --source "x = 42"
  • Ou referenciar por ID estável, como em nb cell update ... --cell ce456 --source "print('Done')", mantendo segurança mesmo com reordenação de células

• Busca avançada

  • Permite localizar rapidamente por conteúdo da célula, tipo ou erro de execução
  • O padrão é casar com o código-fonte da célula, com possibilidade de expandir para saídas de execução usando filtro de escopo
    • nb search analysis.ipynb "import pandas" busca um padrão
    • nb search analysis.ipynb --with-errors extrai apenas células com erro
    • nb search analysis.ipynb "KeyError" --scope output busca nas saídas
    • nb search analysis.ipynb "TODO" --cell-type markdown filtra por tipo de célula
  • Agentes podem usar --with-errors para processar apenas células com falha e combiná-lo com --scope output para buscar traceback de erro diretamente
  • Também é útil para pessoas auditarem APIs deprecated, localizar funções em notebooks grandes e extrair padrões antes de refatoração

• Manipulação em lote de múltiplas células

  • Adicionar sequências como cabeçalho Markdown → código de configuração → análise é um padrão comum, e adicionar célula por célula aumenta o número de idas e voltas e a carga de gerenciar índices
  • Suporta adição de múltiplas células em uma única chamada com formato de sentinelas
    • Blocos @@markdown e @@code podem ser agrupados em heredoc e enviados de uma vez
    • Também suporta formato JSON completo como @@cell {"cell_type": "..."}
  • Compatível com stdin, facilitando a composição de células em scripts e pipelines
    • printf '@@markdown\n## Summary\n\n@@code\ndf.describe()\n' | nb cell add report.ipynb --source -
  • A mesma filosofia de processamento em lote também se aplica a execução e exclusão
    • nb execute analysis.ipynb --start 2 --end 5 executa um intervalo
    • nb cell delete analysis.ipynb -i 0 -i 2 remove células específicas
    • nb cell delete analysis.ipynb --range 0:3 remove um intervalo

• Execução com reconhecimento de ambiente

  • nb connect, nb execute e nb create suportam as flags --uv e --pixi, usando esses gerenciadores de ambiente para localizar servidor Jupyter e kernel
  • nb status --python retorna o prefixo de comando para executar Python no mesmo ambiente do kernel conectado
    • Exemplos de retorno: "uv run", "pixi run"; no caso do Python do sistema, retorna valor vazio
    • Pode ser usado em pipelines no formato $(nb status --python) python -c "..."

Casos de uso reais

• Workflow de agentes de IA

  • É possível manipular notebooks como parte do workflow de análise encadeando comandos de busca de células com falha → correção de código → reexecução
    • 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

• Integração com CI/CD

  • Realiza testes e validação automáticos de notebooks em pipelines de integração contínua
    • Após executar com nb execute pipeline.ipynb --allow-errors, verificar erros com nb search ... --with-errors faz o comando retornar código de saída 1
    • Limpeza de saídas antes do commit com nb output clear

• Geração programática de notebooks

  • Automatiza a criação de documentos, relatórios e análises
    • Cria um notebook de relatório com nb create report.ipynb
    • Adiciona título, introdução e código de análise de uma vez com um comando multicélula, e preenche as saídas com nb execute

• Depuração de notebooks em ambiente operacional

  • Permite diagnosticar rapidamente problemas em notebooks implantados
    • nb search failing_notebook.ipynb --with-errors extrai as células com erro
    • nb search analysis.ipynb "pandas.np" procura uso de API deprecated
    • nb search notebook.ipynb "eval(" procura padrões com potencial risco de segurança
    • nb read failing_notebook.ipynb --cell-index 5 mostra a saída completa de uma célula específica
    • nb execute failing_notebook.ipynb --restart-kernel verifica reprodutibilidade em um estado limpo

Exemplos de funcionamento real

• Example 1: criação de notebook de treinamento em reinforcement learning com LLM usando Claude

  • Prompt do usuário: criar um notebook cobrindo conceitos centrais como modelo de política, modelo de recompensa, penalidade de KL divergence, PPO e GRPO, explicando como cada célula funciona
  • Usa um pequeno modelo de brinquedo com vocabulário reduzido e baseado em GRU, permitindo execução completa em CPU sem chave de API

• Example 2: correção de múltiplos bugs em notebook com Codex

  • Prompt do usuário: corrigir churn_analysis.ipynb, não atualizado desde 2023, para que execute do início ao fim de forma limpa; identificar, corrigir e validar cada célula com falha, e adicionar acima de cada célula alterada uma nota em Markdown explicando o que estava errado e como foi corrigido
  • Os 4 bugs corrigidos pelo Codex
    • Caminho de arquivo hardcoded
    • DataFrame.append(), removido no pandas 2.0
    • sklearn.cross_validation, removido no sklearn 0.20
    • plot_confusion_matrix, removido no sklearn 1.2
  • Após as correções, foi validado que o notebook executa normalmente de ponta a ponta

Primeiros passos

• Oferece três caminhos de instalação: script de instalação, cargo install nb-cli e build a partir do código-fonte (cargo build --release)
• Na build, o binário é gerado em target/release/nb
• Para fazer com que agentes de IA usem nb em todas as tarefas de notebook, há suporte ao comando de instalação de skill npx skills install jupyter-ai-contrib/nb-cli

Desenvolvedores e participação

• Três contribuidores do projeto Jupyter ligados à AWS participaram do desenvolvimento
  • Andrii Ieroshenko: AWS Software Development Engineer, contribuidor de longa data em JupyterLab e Jupyter AI, membro do Jupyter Media Strategy Working Group
  • Brian Granger: AWS Senior Principal Technologist, cofundador do Project Jupyter, membro do conselho da Jupyter Foundation e da PyTorch Foundation
  • Piyush Jain: AWS Principal Engineer, responsável por Jupyter e Agentic AI, membro do Jupyter Server Council
• O nb-cli ainda está em estágio inicial, e o projeto pede instalação e uso prático, abertura de issues no GitHub, participação nas discussões do jupyter-ai-contrib e contribuições via relatórios de bugs, pedidos de recursos e PRs

[jessyt]

Como foi escrito com foco em casos práticos, tem bastante coisa para eu usar como referência!