nb-cli - Yapay zeka ajanları ve notebook otomasyonu için CLI

• AI kodlama ajanlarının Jupyter notebook’ları bir artefakt olarak ele alabilmesi için tasarlanmış deneysel bir açık kaynak CLI aracı; Rust tabanlı olarak geliştirildi ve hızlı, güvenilir notebook işlemleri sunuyor
• .ipynb JSON yapısının otomasyon ve LLM işleme için uygun olmaması sorununu çözmek amacıyla, nbformat belirtimine uyarak okuma, yazma, çalıştırma ve arama işlevlerini komut satırında sağlıyor
• Jupyter sunucusu olmadan da çalışıyor; sunucuya bağlandığında ise JupyterLab ile aynı Y.js CRDT protokolü üzerinden gerçek zamanlı işbirlikçi düzenlemeyi destekliyor
• LLM bağlam verimliliği için @@cell, @@output gibi sentinel tabanlı, yapay zeka için optimize edilmiş Markdown biçimini yeni baştan tasarlıyor
• Unix birleştirilebilirliği, kararlı hücre referansları, güçlü arama, çoklu hücre toplu işlemleri ve ortam farkındalıklı çalıştırma gibi ajan iş akışlarına uygun özellikleri entegre biçimde sunuyor

---

Arka plan: notebook’ların “kara kutu” sorunu

• AI kodlama ajanlarının yükselişiyle geliştirici araçlarının tanımı değişiyor; Claude ve GPT gibi LLM’ler, dokümantasyon, Stack Overflow ve GitHub’daki çok büyük CLI kullanım örnekleriyle eğitildiği için komut satırı arayüzlerini kullanmada son derece yetkin
• Mevcut araçlar, notebook içinde ajan çalıştırmaya odaklanmıştı; ancak notebook’un kendisini bir artefakt olarak ele alan ajanlar için araç tarafında boşluk vardı
• Jupyter notebook’larının .ipynb JSON yapısı, kabuk betikleri ve LLM’ler açısından programatik işlemeyi zorlaştıran bir sürtünme noktası oluşturuyor
• Otomasyon ve yapay zeka analizi gerektiren şu senaryolarda mevcut arayüzler yetersiz kalıyor
  • Otonom analiz: Veri bilimi iş akışını denetleyen bir yapay zeka ajanının, hattı hücre düzeyinde anlaması gerekiyor
  • Otomatik doğrulama: CI/CD sistemlerinin notebook’ları çalıştırıp çıktıları doğrulaması ve hataları önceden yakalaması gerekiyor
  • Büyük ölçekli dokümantasyon: Notebook içeriğinin temiz dokümantasyona otomatik dönüştürülmesi gerekiyor
  • Üretim ortamı hata ayıklama: Headless ortamlarda notebook çalıştırma hatalarının manuel müdahale olmadan teşhis edilmesi gerekiyor
  • Veri olarak notebook: Notebook’ların yapılandırılmış bir veritabanı gibi ele alınıp rapor, özet ve görselleştirme üretilmesi
• Bugüne kadar yaygın yaklaşım; JupyterLab arayüzünü elle kullanmak, karmaşık JSON’u ayrıştıran kırılgan Python betikleri yazmak veya gerçek zamanlı entegrasyonu olmayan çalıştırma araçlarını kullanmaktı
• nb-cli, önceliği CLI olan bir arayüz ve Unix birleştirilebilirliğini kullanarak notebook’ların yazılım yığınının birinci sınıf vatandaşı gibi ele alınmasını sağlıyor

Temel özellikler

• Jupyter sunucusu olsun ya da olmasın çalışır

  • Varsayılan olarak .ipynb dosyalarını doğrudan okur ve yazar, çalıştırma için de ZeroMQ üzerinden çekirdekle doğrudan iletişim kurar
  • Sunucu çalıştırmanın gereksiz olduğu betikler ve CI hatları için uygundur
    • nb create analysis.ipynb ile sunucusuz notebook oluşturma
    • nb cell add, nb execute, nb read komutlarıyla hücre ekleme, çalıştırma ve sonuç görüntüleme
  • Birden fazla kullanıcı veya ajanın aynı notebook’u eşzamanlı düzenlediği durumlarda sunucu bağlantısı faydalıdır; JupyterLab’ın kendi içinde kullandığı Y.js CRDT protokolü ile çakışmasız gerçek zamanlı senkronizasyon sunar
    • nb connect ile yerel sunucuyu otomatik algılar, --server seçeneğiyle belirli bir sunucu ve token belirtilebilir
    • --restart-kernel seçeneğiyle yeniden üretilebilirlik kontrolü için çekirdeği yeniden başlatarak çalıştırma desteklenir
  • Sunucu bağlantısı varken notebook’un JupyterLab’da açık olup olmadığını algılar; açık değilse doğal biçimde dosya tabanlı işleyişe geri döner

• Yapay zeka için optimize edilmiş Markdown biçimi

  • Dil modelleri JSON ayrıştırmaz, token tahmini yapar; bu yüzden derin iç içe geçmiş Jupyter JSON’u bağlam penceresinde verimsizdir
  • Jupyter’nin varsayılan biçiminde kaynak metin dizeleri, base64 blob çıktıları ve çok katmanlı iç içe metadata bulunur; bu nedenle LLM açısından token’ların %30-40’ı süslü parantez, köşeli parantez ve escape karakterleri gibi yapısal işaretlere anlamsız biçimde harcanır
  • Düz Markdown token verimliliği sağlar ama belirsizlik yüksektir
    • # işaretinin Markdown başlığı mı yoksa Python yorumu mu olduğu ayırt edilemez
    • Kod bloklarının notebook hücresi mi yoksa belge içi örnek mi olduğu ayırt edilemez
    • “7. hücredeki hatayı düzelt” dendiğinde hücre konumunu güvenilir şekilde tanımlayacak yapısal işaretler yoktur
  • Bunu çözmek için satır tabanlı sentinel biçimi tasarlanmış
    • @@notebook, @@cell, @@output gibi sentinel’lerle açık yapısal sınırlar sağlanıyor
    • Sentinel satırlarında hücre tipi, indeks ve çalıştırma sayısı satır içi JSON metadata olarak belirtiliyor; bu da attention mekanizmasının bilgi arama biçimiyle hizalanıyor
    • Dil ipucu eklenmiş kod blokları, modelin sözdizimi öğrenimini etkinleştiriyor
    • Her hücre bloğu kendi içinde tamamlandığı için kırpıldığında kademeli bozuluyor; JSON’daki gibi tek bir yerin kesilmesiyle tüm yapının çökmesi sorunu yaşanmıyor

• Birleştirilebilir tasarım

  • Unix geleneğini izleyerek düz metin çıktı, stdin desteği ve öngörülebilir çıkış kodları sunar
  • Ajan açısından tek bir kabuk komutu, birden çok araç çağrısı ve ara ayrıştırma adımının yerini alabilir
  • “Notebook’a bir özet bölümü ekle ve çalıştır” gibi işler, hücre ekleme, çalıştırma ve sonuç okuma adımlarını tek bir kabuk çağrısında işleyebilir
    • nb cell add ... && nb execute ... && nb read ... biçiminde zincirleme
    • Ajan, notebook’un tamamını yeniden okumadan yalnızca gereken çıktıyı alır
  • Aynı ilke hata ayıklamada da geçerlidir
    • nb search analysis.ipynb --with-errors tek başına yalnızca hata veren hücreleri döndürür; başarılı hücrelere token harcanmaz

• Kararlı hücre referansları

  • İki tür hücre referansını destekler
    • İndeks tabanlı --cell-index 0 (negatif indeksleme desteklenir, -1 son hücredir)
    • ID tabanlı --cell f68t57 (hücre taşınsa bile değişmez)
  • nb cell update ... --cell-index 0 --source "x = 42" gibi konuma göre referans verilebilir
  • Ya da nb cell update ... --cell ce456 --source "print('Done')" gibi kararlı ID ile referans verilerek hücre yeniden sıralansa da güvenli kalınır

• Güçlü arama işlevi

  • Hücre içeriği, türü ve çalıştırma hatalarına göre hızlı konum bulma yapılabilir
  • Varsayılan olarak hücre kaynak kodunda eşleşme yapar; scope filtresiyle çalıştırma çıktısına genişletilebilir
    • nb search analysis.ipynb "import pandas" ile desen arama
    • nb search analysis.ipynb --with-errors ile yalnızca hata hücrelerini çıkarma
    • nb search analysis.ipynb "KeyError" --scope output ile çıktıda arama
    • nb search analysis.ipynb "TODO" --cell-type markdown ile hücre türüne göre filtreleme
  • Ajan, --with-errors ile yalnızca başarısız hücreleri alıp işler; bunu --scope output ile birleştirerek hata traceback’ini doğrudan arayabilir
  • İnsan kullanıcılar da deprecated API denetimi, büyük notebook’larda fonksiyon konumu bulma ve refactor öncesi desen çıkarma için kullanabilir

• Çoklu hücre toplu işlemleri

  • Markdown başlığı → ayar kodu → analiz gibi hücre dizileri eklemek yaygın bir kalıptır; hücreleri tek tek eklemek gidip gelme sayısını ve indeks yönetimi yükünü artırır
  • Sentinel biçimiyle tek çağrıda birden fazla hücre ekleme desteklenir
    • @@markdown, @@code blokları heredoc ile gruplanıp tek seferde gönderilebilir
    • @@cell {"cell_type": "..."} biçimindeki tam JSON formatı da desteklenir
  • stdin ile de uyumludur; betik ve pipeline’larda hücre oluşturmayı kolaylaştırır
    • printf '@@markdown\n## Summary\n\n@@code\ndf.describe()\n' | nb cell add report.ipynb --source -
  • Aynı toplu işlem yaklaşımı çalıştırma ve silme için de geçerlidir
    • nb execute analysis.ipynb --start 2 --end 5 ile aralık çalıştırma
    • nb cell delete analysis.ipynb -i 0 -i 2 ile belirli hücreleri silme
    • nb cell delete analysis.ipynb --range 0:3 ile aralık silme

• Ortam farkındalıklı çalıştırma

  • nb connect, nb execute, nb create komutlarında --uv, --pixi bayrakları desteklenir; ilgili ortam yöneticisi üzerinden Jupyter sunucusu ve çekirdeği bulunur
  • nb status --python, bağlı çekirdekle aynı ortamda Python çalıştırmak için kullanılacak komut önekini döndürür
    • Dönen değer örnekleri: "uv run", "pixi run"; sistem Python’unda boş değer
    • $(nb status --python) python -c "..." biçiminde pipeline’larda kullanılabilir

Gerçek kullanım senaryoları

• Yapay zeka ajanı iş akışları

  • Başarısız hücreleri bulma → kodu düzeltme → yeniden çalıştırma komutları zincirlenerek analiz iş akışının bir parçası olarak notebook üzerinde işlem yapılabilir
    • 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 entegrasyonu

  • Sürekli entegrasyon hatlarında notebook’ların otomatik test ve doğrulaması yapılabilir
    • nb execute pipeline.ipynb --allow-errors ile çalıştırdıktan sonra, nb search ... --with-errors ile hata kontrolünde çıkış kodu 1 döndürme
    • Commit öncesinde nb output clear ile çıktıları temizleme

• Programatik notebook oluşturma

  • Doküman, rapor ve analizler otomatik üretilebilir
    • nb create report.ipynb ile rapor notebook’u oluşturma
    • Çoklu hücre komutuyla başlık, giriş ve analiz kodunu tek seferde ekleyip nb execute ile çıktıları doldurma

• Üretim ortamında notebook hata ayıklama

  • Dağıtılmış notebook’lardaki sorunlar hızlıca teşhis edilebilir
    • nb search failing_notebook.ipynb --with-errors ile hatalı hücreleri çıkarma
    • nb search analysis.ipynb "pandas.np" ile deprecated API kullanımını arama
    • nb search notebook.ipynb "eval(" ile güvenlik riski taşıyan desenleri arama
    • nb read failing_notebook.ipynb --cell-index 5 ile belirli bir hücrenin tam çıktısını görüntüleme
    • nb execute failing_notebook.ipynb --restart-kernel ile temiz yeniden üretilebilirlik kontrolü

Gerçek çalışma örnekleri

• Example 1: Claude ile LLM pekiştirmeli öğrenme eğitim notebook’u oluşturma

  • Kullanıcı istemi: politika modeli, ödül modeli, KL divergence cezası, PPO, GRPO gibi temel kavramları ele alan bir notebook oluştur ve her hücrede çalışma prensibini açıkla
  • API anahtarı gerektirmeden CPU üzerinde tamamen çalışabilmesi için küçük söz varlığına ve GRU tabanlı küçük bir oyuncak modele dayanacak şekilde kurgulanmış

• Example 2: Codex ile notebook’taki birden çok hatayı düzeltme

  • Kullanıcı istemi: 2023’ten beri güncellenmemiş churn_analysis.ipynb dosyasını baştan sona temiz biçimde çalışır hale getir; başarısız olan her hücreyi tanımla, düzelt, doğrula ve değiştirilen hücrelerin üstüne neyin nasıl sorun çıkardığını anlatan Markdown notları ekle
  • Codex’in düzelttiği 4 hata
    • Sabit kodlanmış dosya yolu
    • pandas 2.0’da kaldırılan DataFrame.append()
    • sklearn 0.20’de kaldırılan sklearn.cross_validation
    • sklearn 1.2’de kaldırılan plot_confusion_matrix
  • Düzeltmelerden sonra notebook’un uçtan uca sorunsuz çalıştığı doğrulanmış

Başlarken

• Kurulum betiği, cargo install nb-cli ve kaynak koddan derleme (cargo build --release) olmak üzere üç kurulum yolu sunuluyor
• Derleme sırasında ikili dosya target/release/nb içinde oluşturuluyor
• Yapay zeka ajanlarının tüm notebook görevlerinde nb kullanmasını sağlamak için skill kurulum komutu npx skills install jupyter-ai-contrib/nb-cli destekleniyor

Geliştiriciler ve katkı

• AWS bünyesindeki 3 Jupyter proje katkıcısı geliştirmede yer alıyor
  • Andrii Ieroshenko: AWS Software Development Engineer, JupyterLab ve Jupyter AI için uzun süredir katkı sunuyor, Jupyter Media Strategy Working Group üyesi
  • Brian Granger: AWS Senior Principal Technologist, Project Jupyter eş kurucusu, Jupyter ve PyTorch Foundation yönetim kurulu üyesi
  • Piyush Jain: AWS Principal Engineer, Jupyter ve Agentic AI alanında çalışıyor, Jupyter Server Council üyesi
• nb-cli henüz erken aşamada; kurulum ve kullanım sonrası GitHub issue açılması, jupyter-ai-contrib tartışmalarına katılım, hata raporu, özellik talebi ve PR ile katkı yapılması isteniyor

[jessyt]

Vaka odaklı yazdığınız için yararlanabileceğim çok şey var!