nb-cli - une CLI pour les agents IA et l’automatisation des notebooks

• Outil CLI open source expérimental conçu pour permettre aux agents de codage IA de traiter les notebooks comme des artefacts, implémenté en Rust pour offrir une manipulation rapide et fiable des notebooks
• Afin de résoudre le problème selon lequel la structure JSON des .ipynb n’est pas adaptée à l’automatisation ni au traitement par les LLM, il fournit en ligne de commande des fonctions de lecture, écriture, exécution et recherche tout en respectant la spécification nbformat
• Fonctionne sans serveur Jupyter et, lorsqu’il est connecté à un serveur, prend en charge l’édition collaborative en temps réel via le même protocole Y.js CRDT que JupyterLab
• Conçoit un nouveau format Markdown optimisé pour l’IA à base de sentinelles comme @@cell et @@output afin d’améliorer l’efficacité du contexte pour les LLM
• Intègre des fonctionnalités adaptées aux workflows d’agents telles que la composabilité Unix, des références de cellules stables, une recherche puissante, des manipulations par lots multi-cellules et une exécution sensible à l’environnement

---

Contexte : le problème de la « boîte noire » des notebooks

• Avec la montée en puissance des agents de codage IA, la définition même des outils pour développeurs évolue, et les LLM comme Claude ou GPT ont été entraînés sur d’immenses corpus d’usages de CLI issus de la documentation, de Stack Overflow et de GitHub, ce qui les rend très compétents dans l’usage des interfaces en ligne de commande
• Les outils existants se sont surtout concentrés sur l’exécution d’agents à l’intérieur des notebooks, mais il manquait des outils pour des agents capables de traiter le notebook lui-même comme un artefact
• La structure JSON .ipynb des notebooks Jupyter constitue un point de friction pour le traitement programmatique dans les scripts shell et les LLM
• Les interfaces existantes sont insuffisantes pour les scénarios suivants, où l’automatisation et l’analyse par IA sont nécessaires
  • Analyse autonome : un agent IA chargé d’auditer un workflow de data science doit comprendre le pipeline cellule par cellule
  • Validation automatisée : un système CI/CD doit exécuter un notebook, vérifier ses sorties et détecter les erreurs en amont
  • Documentation à grande échelle : le contenu des notebooks doit être automatiquement converti en documentation propre
  • Débogage en environnement de production : il faut diagnostiquer les échecs d’exécution de notebooks en environnement headless sans intervention manuelle
  • Le notebook comme donnée : traiter les notebooks comme une base de données structurée pour générer rapports, résumés et visualisations
• Jusqu’ici, la pratique courante consistait à manipuler manuellement l’interface JupyterLab, à écrire des scripts Python fragiles qui parsèrent un JSON complexe, ou à utiliser des outils d’exécution sans intégration temps réel
• nb-cli s’appuie sur une interface pensée d’abord pour la CLI et sur la composabilité Unix afin de faire du notebook un citoyen de première classe dans la pile logicielle

Fonctionnalités clés

• Fonctionne avec ou sans serveur Jupyter

  • Par défaut, lit et écrit directement les fichiers .ipynb, et exécute les notebooks en communiquant directement avec le kernel via ZeroMQ
  • Convient bien aux scripts et pipelines CI qui n’ont pas besoin d’un serveur en cours d’exécution
    • Création d’un notebook sans serveur avec nb create analysis.ipynb
    • Ajout de cellules, exécution et consultation des résultats avec nb cell add, nb execute et nb read
  • Lorsqu’un même notebook est édité simultanément par plusieurs utilisateurs ou agents, la connexion au serveur devient utile, avec une synchronisation temps réel sans conflit via le même protocole Y.js CRDT que celui utilisé en interne par JupyterLab
    • nb connect détecte automatiquement un serveur local, et l’option --server permet de spécifier un serveur ou un token précis
    • L’option --restart-kernel permet de redémarrer le kernel pour vérifier la reproductibilité
  • En mode connecté, il détecte si le notebook est ouvert dans JupyterLab, et sinon repasse naturellement en fonctionnement basé sur fichier

• Format Markdown optimisé pour l’IA

  • Les modèles de langage ne parsèrent pas le JSON : ils prédisent des tokens. Le JSON Jupyter profondément imbriqué est donc inefficace dans une fenêtre de contexte
  • Dans le format natif de Jupyter, les sources sont des tableaux de chaînes, les sorties des blobs base64 et les métadonnées sont imbriquées sur plusieurs niveaux ; du point de vue d’un LLM, 30 à 40 % des tokens sont gaspillés en caractères structurels comme accolades, crochets ou séquences d’échappement
  • Le Markdown classique est plus efficace en tokens, mais il reste ambigu
    • Impossible de distinguer si # est un titre Markdown ou un commentaire Python
    • Impossible de savoir si un bloc de code est une cellule de notebook ou un exemple dans la documentation
    • Quand on demande « corrige l’erreur dans la cellule 7 », il n’existe pas de marqueur structurel stable pour identifier la position de la cellule
  • Pour résoudre cela, un format à sentinelles ligne par ligne a été conçu
    • Des sentinelles comme @@notebook, @@cell et @@output fournissent des frontières structurelles claires
    • Les lignes sentinelles indiquent le type de cellule, l’index et le compteur d’exécution via des métadonnées JSON inline, ce qui correspond à la manière dont le mécanisme d’attention retrouve l’information
    • Des fences de code accompagnées d’indices de langage activent l’apprentissage syntaxique du modèle
    • Chaque bloc de cellule est autonome, donc en cas de troncature la dégradation est progressive, au lieu de casser toute la structure comme avec du JSON

• Une conception composable

  • Suit les conventions Unix avec sorties en texte brut, prise en charge de stdin et codes de sortie prévisibles
  • Du point de vue d’un agent, une seule commande shell peut remplacer plusieurs appels d’outils et étapes de parsing intermédiaires
  • Une tâche comme « ajouter une section de résumé au notebook puis l’exécuter » peut être gérée en un seul enchaînement shell couvrant ajout de cellule, exécution et lecture du résultat
    • Chaînage du type nb cell add ... && nb execute ... && nb read ...
    • L’agent n’a pas besoin de relire tout le notebook et ne récupère que la sortie nécessaire
  • Le même principe s’applique au débogage
    • nb search analysis.ipynb --with-errors renvoie en une seule fois uniquement les cellules en erreur, sans gaspiller de tokens sur les cellules réussies

• Références de cellules stables

  • Prend en charge deux modes de référence de cellule
    • Basé sur l’index avec --cell-index 0 (indexation négative prise en charge, -1 désigne la dernière cellule)
    • Basé sur l’ID avec --cell f68t57 (ne change pas même si la cellule est déplacée)
  • Référence par position avec nb cell update ... --cell-index 0 --source "x = 42"
  • Ou référence par ID stable avec nb cell update ... --cell ce456 --source "print('Done')", sûre même si les cellules sont réordonnées

• Recherche puissante

  • Permet de localiser rapidement par contenu de cellule, type de cellule ou erreur d’exécution
  • Par défaut, la recherche porte sur le code source des cellules, avec possibilité d’étendre aux sorties d’exécution via un filtre de scope
    • Recherche de motif avec nb search analysis.ipynb "import pandas"
    • Extraction des seules cellules en erreur avec nb search analysis.ipynb --with-errors
    • Recherche dans les sorties avec nb search analysis.ipynb "KeyError" --scope output
    • Filtrage par type de cellule avec nb search analysis.ipynb "TODO" --cell-type markdown
  • Un agent peut utiliser --with-errors pour ne récupérer que les cellules en échec, et le combiner avec --scope output pour rechercher directement dans les traceback d’erreur
  • C’est aussi utile pour les humains : audit d’API dépréciées, localisation de fonctions dans de gros notebooks, extraction de motifs avant refactorisation

• Manipulation par lots de plusieurs cellules

  • Ajouter une séquence de cellules du type en-tête Markdown → code de configuration → analyse est un schéma fréquent, et l’ajout cellule par cellule augmente les allers-retours et la charge de gestion des index
  • Le format à sentinelles permet d’ajouter plusieurs cellules en un seul appel
    • Des blocs @@markdown et @@code peuvent être regroupés dans un heredoc pour être transmis d’un coup
    • Le format JSON complet @@cell {"cell_type": "..."} est également pris en charge
  • Compatible aussi avec stdin, ce qui facilite la composition de cellules dans les scripts et pipelines
    • printf '@@markdown\n## Summary\n\n@@code\ndf.describe()\n' | nb cell add report.ipynb --source -
  • La même philosophie de traitement par lots s’applique à l’exécution et à la suppression
    • Exécution d’une plage avec nb execute analysis.ipynb --start 2 --end 5
    • Suppression de cellules spécifiques avec nb cell delete analysis.ipynb -i 0 -i 2
    • Suppression d’une plage avec nb cell delete analysis.ipynb --range 0:3

• Exécution sensible à l’environnement

  • nb connect, nb execute et nb create prennent en charge les drapeaux --uv et --pixi, et recherchent serveur Jupyter et kernels via le gestionnaire d’environnement correspondant
  • nb status --python renvoie le préfixe de commande permettant d’exécuter Python dans le même environnement que le kernel connecté
    • Exemples de valeurs renvoyées : "uv run", "pixi run", ou une valeur vide pour le Python système
    • Utilisable dans un pipeline sous la forme $(nb status --python) python -c "..."

Cas d’usage concrets

• Workflows d’agents IA

  • Il est possible de relier en commandes la recherche de cellules en échec, la correction du code et la réexécution afin de manipuler le notebook comme une partie d’un workflow d’analyse
    • 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

• Intégration CI/CD

  • Permet de réaliser des tests et validations automatiques des notebooks dans les pipelines d’intégration continue
    • Exécution avec nb execute pipeline.ipynb --allow-errors, puis retour du code de sortie 1 si nb search ... --with-errors détecte des erreurs
    • Nettoyage des sorties avant commit avec nb output clear

• Génération programmatique de notebooks

  • Permet d’automatiser la création de documents, rapports et analyses
    • Création d’un notebook de rapport avec nb create report.ipynb
    • Ajout en une seule fois du titre, de l’introduction et du code d’analyse via une commande multi-cellules, puis remplissage des sorties avec nb execute

• Débogage de notebooks en production

  • Permet de diagnostiquer rapidement les problèmes de notebooks déployés
    • nb search failing_notebook.ipynb --with-errors pour extraire les cellules en erreur
    • nb search analysis.ipynb "pandas.np" pour rechercher l’usage d’API dépréciées
    • nb search notebook.ipynb "eval(" pour repérer des motifs à risque côté sécurité
    • nb read failing_notebook.ipynb --cell-index 5 pour voir la sortie complète d’une cellule spécifique
    • nb execute failing_notebook.ipynb --restart-kernel pour une vérification propre de la reproductibilité

Exemples de fonctionnement réels

• Example 1: création avec Claude d’un notebook de formation au reinforcement learning pour LLM

  • Prompt utilisateur : créer un notebook couvrant les concepts clés comme le modèle de politique, le modèle de récompense, la pénalité de divergence KL, PPO, GRPO, etc., et expliquer le fonctionnement dans chaque cellule
  • Utilise un petit modèle jouet basé sur un petit vocabulaire et un GRU, afin de pouvoir être exécuté entièrement sur CPU sans clé API

• Example 2: correction de plusieurs bugs d’un notebook avec Codex

  • Prompt utilisateur : corriger churn_analysis.ipynb, non mis à jour depuis 2023, pour qu’il s’exécute proprement jusqu’au bout ; identifier, corriger et valider chaque cellule en échec, puis ajouter au-dessus de chaque cellule modifiée une note Markdown expliquant le problème et la correction
  • Les 4 bugs corrigés par Codex
    • Chemin de fichier codé en dur
    • DataFrame.append() supprimé dans pandas 2.0
    • sklearn.cross_validation supprimé dans sklearn 0.20
    • plot_confusion_matrix supprimé dans sklearn 1.2
  • Vérifie qu’après correction, le notebook s’exécute correctement de bout en bout

Prise en main

• Trois voies d’installation sont proposées : script d’installation, cargo install nb-cli et compilation depuis les sources avec cargo build --release
• Lors de la compilation, le binaire est généré dans target/release/nb
• Pour que les agents IA utilisent nb pour toutes les tâches liées aux notebooks, la commande d’installation de skill npx skills install jupyter-ai-contrib/nb-cli est prise en charge

Développeurs et contribution

• Trois contributeurs du projet Jupyter chez AWS participent au développement
  • Andrii Ieroshenko : AWS Software Development Engineer, contributeur de longue date à JupyterLab et Jupyter AI, membre du Jupyter Media Strategy Working Group
  • Brian Granger : AWS Senior Principal Technologist, cofondateur de Project Jupyter, membre des conseils d’administration de Jupyter et de la PyTorch Foundation
  • Piyush Jain : AWS Principal Engineer, en charge de Jupyter et de l’agentic AI, membre du Jupyter Server Council
• nb-cli en est encore à ses débuts ; après installation et usage, les auteurs invitent à ouvrir des issues GitHub, à participer aux discussions jupyter-ai-contrib, et à contribuer via des rapports de bugs, demandes de fonctionnalités ou PR

[jessyt]

Merci d’avoir rédigé cela à partir de cas concrets, il y a beaucoup d’éléments utiles à retenir !