📦 Smart Codebase Bundler

An on-demand CLI + GUI tool that turns a local codebase into modular text packages optimized for NotebookLM and similar LLM workflows.

Spec: srs.txt (SRS v8.0) · License: MIT · Türkçe kılavuz ↓

1. 🎯 Project Overview

Smart Codebase Bundler scans a project in your local development environment (Cursor / VS Code / any repo) and splits the source into orderly .txt packages that large language models can ingest efficiently.

What problem does it solve?

Problem	Solution
Dumping an entire repo into an LLM wastes tokens and loses context	Code is packed per module (`bundle_lib`, `bundle_web`, …)
Binaries / large files add noise	Text allow-list + 500 KB hard size cap
Re-packing from scratch every time is slow	MD5 + token cache rebuilds only what changed
Partial / corrupted packages when writing to Drive	All-or-nothing transfer + rollback
Manifest syncing too early (Google Drive race)	5-second delay after all packages, then `bundle_manifest.json`

In short: you trigger the tool (CLI or GUI) → it produces safe packages → if the output folder is a Google Drive sync path, Drive uploads them so NotebookLM can use them as sources.

⚠️ This tool does not call the Google Drive API. Point SMART_BUNDLER_OUTPUT at Drive’s local sync folder and let the desktop client handle upload.

2. ✨ Key Features

🖥️ CLI, GUI & control

On-demand runs — terminal (main.py) or graphical UI (gui.py)
--dry-run / -d — report which modules would rebuild and estimate tokens; write nothing
--force / -f — ignore cache and rebuild the whole project
Graceful shutdown — CLI: Ctrl+C (SIGINT) / SIGTERM; GUI: on window close, wait for the worker then cleanup() (TEMP removal, FR-1.2)
GUI safety — action buttons locked while a job runs; work on a background thread; ANSI stripped from logs; calls run_pipeline (never main(), which raises SystemExit); closing mid-run uses request_cancel so TEMP is not deleted under an active writer

🔍 Smart scanning

Hierarchical .gitignore stack (push on enter directory, pop on leave)
Virtual Smartignore — paths chosen in the GUI / set via env are ignored in RAM only (no ignore file written to disk; FR-4.1)
Windows MAX_PATH handled via \\?\ path normalization (pathlib)
Symlinks are never followed; inode keys guard against cycles
Broad text allow-list (.py, .dart, .toml, Dockerfile, Podfile, .env.example, …)
Binary / archive rejection (extension + byte sniff)
Files over 500 KB are skipped (yellow: Skipped (exceeds 500 KB limit): …)

🧠 Token & bundling

Module model: first-level folders under the project root → bundle_<folder>.txt; loose root files → bundle_general.txt
Empty modules are not emitted
Hybrid tokens: fast chars/4; tiktoken (cl100k_base) near capacity / for exact cache counts
Individual files are never split; overflow opens a new _partN
Directory tree appears only in Part 1
Each package starts with a NotebookLM-oriented SYSTEM NOTE
Soft packing limit ≈ 100k tokens per part (TOKEN_LIMIT in bundler/tokenizer.py)

💾 Cache & security

.bundle_cache.json lives outside the source tree: %APPDATA%/smart_bundler/ (Windows) or ~/.config/smart_bundler/
Portable cache fingerprint = folder name + sorted top-level child names (relocating the same tree reduces pointless full rebuilds; legacy path-hash caches migrate once)
Per-file MD5 + exact token count; unchanged content skips tiktoken recompute
Missing output parts force a mandatory rebuild (desync protection)
One changed file rebuilds all parts of that module

🚚 Transfer & sync

Sources streamed in 64 KB chunks; token probe uses SpooledTemporaryFile (memory-friendly, FR-4.1 / NFR-1.2)
Write to TEMP → MD5 compare → transfer only changed files
Failure on a multi-part module → rollback (previous good version kept)
Orphan bundle_*.txt cleanup — only files with the Smart Bundler SYSTEM NOTE header are deleted (personal bundle_notes.txt-style files are left alone)
After transfer, 5-second wait → write bundle_manifest.json (Drive race mitigation)

3. 🧰 Tech Stack

This repository is a Python CLI + tkinter GUI project (not a Flutter / Firebase app).

Layer	Technology	Role
Language	Python 3.10+	Runtime
CLI	`argparse`, `signal`	Flags & signal handlers
GUI	tkinter (stdlib)	Folder pickers, action buttons, log pane
Filesystem	`pathlib`, `tempfile`, `shutil`	Paths, TEMP, atomic moves
Tokens	tiktoken (`cl100k_base`)	Exact token counts
Terminal	colorama	Colored status / warnings (ANSI stripped in GUI)
Hashing	`hashlib` (MD5)	Change & desync detection
Stdlib	`json`, `threading`, `io` / spool	Manifest, timed reads, streaming, GUI worker
Spec	`srs.txt` (SRS v8.0)	Requirements source of truth

External dependencies (requirements.txt):

tiktoken>=0.7.0
colorama>=0.4.6

4. ⚙️ Setup & Installation

4.1 Prerequisites

Windows 10/11 (Linux / macOS supported; adjust paths for your OS)
Python 3.10+ — on Windows, the py -3 launcher is recommended
(Optional) Google Drive desktop app — if you want output under a Drive sync folder
(Optional) Git

4.2 Install

# 1) Clone
git clone https://github.com/<username>/notebook_script.git
cd notebook_script

# 2) Install deps (once)
py -3 -m pip install -r requirements.txt

4.3 Basic run (CLI)

Run from the project you want to pack, and pass the full path to the bundler script:

# Project to pack
cd C:\Users\<username>\Documents\GitHub\<your-project-folder>

# Output (e.g. Google Drive local folder)
$env:SMART_BUNDLER_OUTPUT = "G:\My Drive\NotebookLM_Bundles"

# Preview (no writes)
py -3 C:\Users\<username>\Documents\GitHub\notebook_script\main.py -d

# Real pack
py -3 C:\Users\<username>\Documents\GitHub\notebook_script\main.py

Environment variables

Variable	Meaning	Default
`SMART_BUNDLER_OUTPUT`	Folder where packages are written	`<project>/bundles`
`SMART_BUNDLER_ROOT`	Project root to scan	Current working directory (`cwd`)
`SMART_BUNDLER_VIRTUAL_IGNORE`	Absolute paths to exclude (comma-separated)	empty (none)

💡 In PowerShell, $env:... lasts only for that terminal session. Set it again in a new window.

CLI flags

py -3 ...\main.py          # Normal (changed modules only)
py -3 ...\main.py -d       # Dry-run / preview
py -3 ...\main.py -f       # Force — rebuild everything
py -3 ...\main.py -h       # Help

Flag	Equivalent	Behavior
(none)	Bundle	Write; rebuild only modules that need it
`-d`	Token cost / dry-run	No write; show rebuild plan + ~tokens
`-f`	Force run	Write; ignore cache
`-d -f`	Full dry-run	No write; treat everything as REBUILD for preview

5. 🖥️ GUI (Graphical User Interface) Guide

No extra GUI dependency (tkinter ships with Python).

Launch

Method	How
Desktop shortcut	`Smart Codebase Bundler.lnk` (once: `powershell -ExecutionPolicy Bypass -File .\create_desktop_shortcut.ps1`)
Double-click	`gui.bat` in the repo root
Terminal	`py -3 gui.py`

cd C:\Users\<username>\Documents\GitHub\notebook_script
py -3 gui.py
# or
.\gui.bat

UI regions

Region	What it does
Source / Output + Browse	Sets scan root and output folder → `SMART_BUNDLER_ROOT` / `SMART_BUNDLER_OUTPUT`
Virtual Ignore	Add files / Add folder / Clear → `SMART_BUNDLER_VIRTUAL_IGNORE` (RAM only; nothing written to disk)
1 · Token cost	`main.py -d` — no write; ~tokens for modules that would change
2 · Dry run	`main.py -d -f` — no write; preview all modules as REBUILD
3 · Force run	`main.py -f` — write; ignore cache; rebuild everything
4 · Bundle	`main.py` — write; rebuild changed modules only
Log	Live stdout/stderr (colorama ANSI stripped)
Window close (X)	After the worker finishes: `cleanup()` (FR-1.2 / TEMP). TEMP is not deleted while a write is in progress

The GUI does not modify bundler/ internals and does not call main() (SystemExit would kill the window). It sets env vars and runs run_pipeline on a worker thread. All four action buttons stay disabled until the job ends. Virtual Ignore paths become root-anchored gitignore-style rules in memory. Orphan cleanup only deletes bundle_*.txt files that carry the Smart Bundler SYSTEM NOTE header.

6. 📖 In-Depth User Guide

There are two entry points: CLI (main.py) and GUI (gui.py).

6.1 First-time usage

Install dependencies (pip install -r requirements.txt).
cd into the repo you want to pack.
Set SMART_BUNDLER_OUTPUT to your Drive folder (or use the default bundles).
Run with -d and read REBUILD / skip (cache) lines.
Run without flags → look for Done. and Manifest: ....
After Drive finishes syncing, add bundle_*.txt + bundle_manifest.json as NotebookLM sources.

6.2 Daily usage (after code changes)

cd C:\Users\<username>\Documents\GitHub\<your-project-folder>
$env:SMART_BUNDLER_OUTPUT = "G:\My Drive\NotebookLM_Bundles"
py -3 C:\Users\<username>\Documents\GitHub\notebook_script\main.py

Decision matrix:

Situation	Behavior
File content unchanged + output present	`skip (cache)` — no rewrite
File changed	That module `REBUILD`
A `bundle_*.txt` was deleted from the output/Drive folder	Desync → regenerate
You passed `-f`	All modules rebuild

6.3 Reading terminal / GUI logs

Cyan Dry-run — simulation mode; nothing written to disk (same text in the GUI, without color codes)
[REBUILD] / [skip (cache)] — which packages will refresh
Yellow Skipped (exceeds 500 KB limit): ... — large file intentionally dropped (not an error)
Yellow Skipping unreadable file... — locked / unreadable file; an error marker is left in the package
Yellow Orphan skip (not a Smart Bundler artifact) — name matches bundle_*.txt but no our header → not deleted
Green Done. — success; transferred file count and manifest path

6.4 Recommended NotebookLM scenario

Upload first: bundle_lib, bundle_backend, core domain packages, bundle_general, bundle_manifest.json
Add when needed: web / UI sources
Often defer: android, ios, windows and other native scaffold-heavy trees (high noise / token cost)

6.5 Copy-paste template (Windows PowerShell)

cd C:\Users\<username>\Documents\GitHub\<your-project-folder>

$env:SMART_BUNDLER_OUTPUT = "G:\My Drive\NotebookLM_Bundles"

py -3 C:\Users\<username>\Documents\GitHub\notebook_script\main.py -d
py -3 C:\Users\<username>\Documents\GitHub\notebook_script\main.py

Force:

py -3 C:\Users\<username>\Documents\GitHub\notebook_script\main.py -f

6.6 Pipeline (developer summary)

1. CLI + signal handlers
2. Scan with gitignore stack (+ virtual ignore)
3. Cache / desync analysis
4. Stream-pack modules that need rebuild
5. All-or-nothing transfer (+ MD5 skip)
6. Orphan cleanup → 5 s delay → manifest → TEMP cleanup

7. 🗂️ Folder & Module Structure

notebook_script/
├── main.py                 # 🚪 CLI entry — 6-stage pipeline
├── gui.py                  # 🖼️ tkinter GUI — run_pipeline + cleanup
├── gui.bat                 # ▶️ Double-click GUI launcher (Windows)
├── create_desktop_shortcut.ps1  # 🔗 Desktop .lnk helper
├── .gitignore              # 🚫 bundles/, venv/, __pycache__, …
├── LICENSE                 # ⚖️ MIT
├── requirements.txt        # 📦 tiktoken, colorama
├── srs.txt                 # 📋 Software requirements (SRS v8.0)
├── README.md               # 📘 This document
├── bundles/                # 📤 Default output (local tests; gitignored)
│   ├── bundle_*.txt
│   └── bundle_manifest.json
└── bundler/                # 🧩 Packing core
    ├── __init__.py
    ├── cli.py              # argparse, SIGINT/SIGTERM
    ├── scanner.py          # scan, gitignore, filters, MAX_PATH
    ├── cache.py            # AppData cache, MD5, desync
    ├── tokenizer.py        # hybrid tokens + tiktoken
    └── writer.py           # stream pack, transfer, rollback, manifest

Module responsibilities

File	Responsibility
`main.py`	Orchestration, dry-run report, cleanup / cancel registration
`gui.py`	tkinter UI; env paths; virtual ignore; threaded `run_pipeline`; X → deferred `cleanup`
`bundler/cli.py`	`-f` / `-d`, signals → cleanup
`bundler/scanner.py`	Discovery, gitignore stack, virtual ignore, filters
`bundler/cache.py`	Persistent cache path, rebuild decisions, identity fingerprint
`bundler/tokenizer.py`	Token limit (~100k) and hybrid counting
`bundler/writer.py`	Module grouping, stream write, transfer, orphan gate, manifest

Output naming

Single part: bundle_<module>.txt
Multi-part: bundle_<module>_part1.txt, _part2.txt, …
Root-level files: bundle_general.txt
Roadmap / index: bundle_manifest.json

Cache location (outside the source tree)

Windows: %APPDATA%\smart_bundler\<fingerprint>\.bundle_cache.json
Linux/macOS: ~/.config/smart_bundler/<fingerprint>/.bundle_cache.json

fingerprint = MD5(folder name + top-level child names). Moving the project to another path with the same name/structure keeps the cache; older absolute-path digests are migrated once on load.

8. 🤝 Contributing & Contact

Contributions are welcome. Short guide:

Follow the SRS — for behavior changes, use srs.txt (v8.0) as the reference.
Keep the memory / path / rollback rules described in srs.txt and the packing core intact.
Fork → feature branch → PR.

After changes, at least:

py -3 main.py -d
py -3 main.py
py -3 gui.py   # confirm GUI path still works

Regression-check large-file filtering, stream writes, and all-or-nothing transfer.
Avoid new dependencies; the stack is intentionally minimal (gui.py uses stdlib tkinter only).

Development tips

Token limits: bundler/tokenizer.py → TOKEN_LIMIT, CHAR_LIMIT
Size filter: bundler/scanner.py → MAX_FILE_SIZE
Manifest delay: bundler/writer.py → MANIFEST_DELAY_SEC = 5

Contact

Bugs / features: GitHub Issues (this repository)
Requirements discussion: align via srs.txt

📎 Appendix: Quick command card

Goal	Command
Install deps	`py -3 -m pip install -r requirements.txt`
Open GUI	`py -3 gui.py` or `gui.bat` / desktop shortcut
Preview	`py -3 ...\main.py -d`
Pack	`py -3 ...\main.py`
Force rebuild	`py -3 ...\main.py -f`
Output path	`$env:SMART_BUNDLER_OUTPUT = "G:\My Drive\..."`
Source root	`$env:SMART_BUNDLER_ROOT = "C:\...\project"`
Virtual ignore	`$env:SMART_BUNDLER_VIRTUAL_IGNORE = "C:\...\skip,D:\...\dir"`

Turkish Documentation / Türkçe Kullanım Kılavuzu

Kaynak kodunu NotebookLM (ve benzeri LLM araçları) için optimize edilmiş, modüler metin paketlerine dönüştüren on-demand CLI + GUI aracı.

1. 🎯 Proje Hakkında (Overview)

Smart Codebase Bundler, yerel geliştirme ortamındaki (Cursor / VS Code / herhangi bir repo) proje kodunu tarayıp, büyük dil modellerinin kolayca okuyabileceği düzenli .txt paketlerine ayırır.

Hangi problemi çözüyor?

Sorun	Çözüm
Tüm repoyu tek seferde LLM’e yüklemek token israfı ve bağlam kaybı yaratır	Kod modül bazlı (`bundle_lib`, `bundle_web`, …) paketlenir
Binary / büyük dosyalar gürültü üretir	Metin filtre + 500 KB üst sınırı
Her seferinde sıfırdan paketlemek zaman kaybı	MD5 + token önbelleği ile yalnızca değişenler yenilenir
Drive’a yazarken yarım kalan / bozulmuş paket riski	All-or-nothing transfer + rollback
Manifest’in erken senkron olması (Google Drive race)	Tüm paketlerden sonra 5 sn bekleme, sonra `bundle_manifest.json`

Özet: Geliştirici komutu veya GUI ile tetikler → script güvenli paketler üretir → çıktıyı Google Drive klasörüne yazarsanız Drive senkronu NotebookLM kaynağına taşır.

⚠️ Bu araç Google Drive API’sine doğrudan yükleme yapmaz. SMART_BUNDLER_OUTPUT ile Drive’ın yerel senkron klasörünü hedeflemeniz yeterlidir.

2. ✨ Öne Çıkan Özellikler (Key Features)

🖥️ CLI, GUI & kontrol

On-demand çalıştırma — terminal (main.py) veya grafik arayüz (gui.py)
--dry-run / -d — hiçbir dosya yazmadan hangi modüllerin yenileneceğini ve tahmini token’ı gösterir
--force / -f — önbelleği yok sayıp tüm projeyi sıfırdan paketler
Graceful shutdown — CLI’de Ctrl+C (SIGINT) / SIGTERM; GUI’de pencere kapatırken worker bitince cleanup() ile geçici klasör temizliği
GUI güvenlikleri — işlem süresince tüm aksiyon butonları kilitli, arka planda thread, ANSI’siz log, main() yerine run_pipeline; X sırasında TEMP race yok

🔍 Akıllı tarama

Hiyerarşik .gitignore yığını (dizine girince push, çıkınca pop)
Virtual Smartignore — GUI/env ile seçilen yolları RAM’de ignore et (diske yazılmaz)
Windows MAX_PATH aşımı için \\?\ yol normalizasyonu (pathlib)
Symlink takip edilmez; inode ile döngü koruması
Geniş metin allow-list (.py, .dart, .toml, Dockerfile, Podfile, .env.example, …)
Binary / arşiv eleme (uzantı + byte sniff)
500 KB üzeri dosyalar atlanır (sarı uyarı: Skipped (exceeds 500 KB limit): …)

🧠 Token & paketleme

Modül modeli: kökteki ilk seviye klasörler → bundle_<klasör>.txt; kökteki tekil dosyalar → bundle_general.txt
Boş modül üretilmez
Hibrit token: hızlı karakter/4; kritik dolulukta tiktoken (cl100k_base)
Bireysel dosyalar bölünmez; sınır aşılınca yeni _partN açılır
Dizin ağacı yalnızca Part 1’de
Her paketin başında NotebookLM için SYSTEM NOTE yönergesi

💾 Önbellek & güvenlik

.bundle_cache.json kaynak ağacında değil; %APPDATA%/smart_bundler/ (Windows) veya ~/.config/smart_bundler/
Cache fingerprint = klasör adı + üst seviye çocuklar (taşıma sonrası gereksiz REBUILD azalır)
Dosya başına MD5 + tam token saklanır; içerik aynıysa tiktoken tekrarlanmaz
Çıktıda eksik paket varsa zorunlu yeniden üretim (desync koruması)
Bir dosya değişince ilgili modülün tüm part’ları baştan üretilir

🚚 Transfer & senkron

Kaynaklar 64 KB chunk ile stream edilir; SpooledTemporaryFile ile bellek dostu probe
TEMP’e yazım → MD5 karşılaştırma → yalnızca değişenler taşınır
Çok parçalı modüllerde hata → rollback (eski sağlam sürüm korunur)
Yetim bundle_*.txt temizliği — yalnızca Smart Bundler SYSTEM NOTE başlıklı dosyalar
Transfer sonrası 5 saniye bekleme → bundle_manifest.json

3. 🧰 Teknoloji Yığını (Tech Stack)

Bu depo bir Python CLI + tkinter GUI projesidir (Flutter / Firebase uygulaması değildir).

Katman	Teknoloji	Rol
Dil	Python 3.10+	Ana çalışma zamanı
CLI	`argparse`, `signal`	Argümanlar & sinyal yönetimi
GUI	tkinter (stdlib)	Klasör seçimi, aksiyon butonları, log ekranı
Dosya sistemi	`pathlib`, `tempfile`, `shutil`	Yol, TEMP, atomik taşıma
Token	tiktoken (`cl100k_base`)	Tam token sayısı
Terminal	colorama	Renkli uyarı / durum çıktısı (GUI’de ANSI temizlenir)
Hash	`hashlib` (MD5)	Değişiklik & desync tespiti
Standart kütüphane	`json`, `threading`, `io` / spool	Manifest, timeout okuma, stream, GUI worker
Spesifikasyon	`srs.txt` (SRS v8.0)	Gereksinim kaynağı

Harici bağımlılıklar (requirements.txt):

tiktoken>=0.7.0
colorama>=0.4.6

4. ⚙️ Kurulum ve Çalıştırma (Setup & Installation)

4.1 Ön gereksinimler (Prerequisites)

Windows 10/11 (Linux / macOS da desteklenir; yollar OS’e göre değişir)
Python 3.10+ — Windows’ta py -3 launcher önerilir
(İsteğe bağlı) Google Drive masaüstü uygulaması — çıktıyı Drive klasörüne yazmak için
(İsteğe bağlı) Git

4.2 Kurulum

# 1) Repoyu klonla
git clone https://github.com/<username>/notebook_script.git
cd notebook_script

# 2) Bağımlılıkları kur (bir kez)
py -3 -m pip install -r requirements.txt

4.3 Çalıştırma (temel)

Bu aracı paketlemek istediğiniz projenin klasöründen çalıştırın; script yolunu tam verin:

# Paketlenecek proje
cd C:\Users\<username>\Documents\GitHub\<your-project-folder>

# Çıktı (ör. Google Drive yerel klasörü)
$env:SMART_BUNDLER_OUTPUT = "G:\My Drive\NotebookLM_Paketler"

# Önizleme (yazmaz)
py -3 C:\Users\<username>\Documents\GitHub\notebook_script\main.py -d

# Gerçek paketleme
py -3 C:\Users\<username>\Documents\GitHub\notebook_script\main.py

Ortam değişkenleri

Değişken	Anlamı	Varsayılan
`SMART_BUNDLER_OUTPUT`	Paketlerin yazılacağı klasör	`<proje>/bundles`
`SMART_BUNDLER_ROOT`	Taranacak proje kökü	Şu anki çalışma dizini (`cwd`)
`SMART_BUNDLER_VIRTUAL_IGNORE`	Paket dışı bırakılacak mutlak yollar (virgülle)	boş (yok)

💡 PowerShell’de $env:... ataması yalnızca o terminal oturumu için geçerlidir. Yeni pencerede tekrar yazmanız gerekir.

CLI bayrakları

py -3 ...\main.py          # Normal (yalnızca değişenler)
py -3 ...\main.py -d       # Dry-run / önizleme
py -3 ...\main.py -f       # Force — her şeyi yeniden paketle
py -3 ...\main.py -h       # Yardım

4.4 GUI (grafik arayüz)

Ek bağımlılık yok (tkinter Python ile gelir).

Başlatma

Yol	Nasıl
Masaüstü kısayolu	`Smart Codebase Bundler.lnk` (bir kez: `powershell -ExecutionPolicy Bypass -File .\create_desktop_shortcut.ps1`)
Çift tık	Repo kökündeki `gui.bat`
Terminal	`py -3 gui.py`

cd C:\Users\<username>\Documents\GitHub\notebook_script
py -3 gui.py
# veya
.\gui.bat

Bölüm	Ne yapar
Source / Output + Browse	Taranacak proje ve çıktı klasörü → `SMART_BUNDLER_ROOT` / `SMART_BUNDLER_OUTPUT`
Virtual Ignore	Add files / folder / Clear → `SMART_BUNDLER_VIRTUAL_IGNORE` (RAM; diske yazılmaz)
1 · Token cost	`main.py -d` — yazmaz; değişenlerin ~token tahmini
2 · Dry run	`main.py -d -f` — yazmaz; her şeyi REBUILD gibi önizler
3 · Force run	`main.py -f` — yazar; önbelleği yok sayıp hepsini paketler
4 · Bundle	`main.py` — yazar; yalnızca değişenleri paketler
Log	Terminal çıktısını anlık gösterir (colorama ANSI kodları temizlenir)
Window close (X)	Worker bitince `cleanup()` (FR-1.2 / TEMP); yazma sırasında TEMP silinmez

GUI, bundler/ çekirdeğine dokunmaz; main() çağırmaz (SystemExit pencereyi kapatırdı). Doğrudan run_pipeline kullanır. İşlem bitene kadar dört buton da kilitlidir. Virtual Ignore seçimleri tarayıcıda kök-göreli gitignore kurallarına çevrilir; geçici ignore dosyası oluşturulmaz (FR-4.1). Orphan temizliği yalnızca Smart Bundler SYSTEM NOTE başlıklı dosyaları siler.

5. 📖 Detaylı Kullanım Kılavuzu (User Guide)

İki giriş noktası vardır: terminal CLI (main.py) ve GUI (gui.py). Tipik CLI akışı:

5.1 İlk kullanım (sıfırdan)

notebook_script bağımlılıklarını kurun (pip install -r requirements.txt).
Paketlemek istediğiniz repoya cd yapın.
Drive klasörünüzü SMART_BUNDLER_OUTPUT ile verin (veya varsayılan bundles kullanın).
-d ile önizleyin → REBUILD / skip (cache) satırlarını okuyun.
Parametresiz çalıştırın → bitince Done. ve Manifest: ... görünür.
Çıktı klasöründeki bundle_*.txt + bundle_manifest.json dosyalarını NotebookLM’e kaynak olarak ekleyin (Drive senkronu tamamlandıktan sonra).

5.2 Günlük kullanım (kod değişince)

cd C:\Users\<username>\Documents\GitHub\<your-project-folder>
$env:SMART_BUNDLER_OUTPUT = "G:\My Drive\NotebookLM_Paketler"
py -3 C:\Users\<username>\Documents\GitHub\notebook_script\main.py

Script otomatik karar verir:

Durum	Davranış
Dosya içeriği aynı + çıktı yerinde	`skip (cache)` — yeniden yazmaz
Dosya değişti	İlgili modül `REBUILD`
Drive’daki `bundle_*.txt` silindi	Desync → yeniden üretir
`-f` verdiniz	Tüm modüller yeniden

5.3 Terminal / GUI log çıktısını okumak

Cyan Dry-run — deneme modu; disk yazılmaz (GUI’de renk kodu olmadan aynı metin)
[REBUILD] / [skip (cache)] — hangi paketlerin yenileneceği
Sarı Skipped (exceeds 500 KB limit): ... — büyük dosya bilinçli elendi (hata değil)
Sarı Skipping unreadable file... — kilitli / okunamayan dosya; pakette hata notu bırakılır
Sarı Orphan skip (not a Smart Bundler artifact) — bundle_*.txt ama bizim header yok → silinmez
Yeşil Done. — başarı; transfer edilen dosya sayısı ve manifest yolu

5.4 GUI ile kullanım

py -3 gui.py ile pencereyi açın.
Source folder = paketlenecek repo; Output folder = Drive / bundles vb.
İsteğe bağlı: Virtual Ignore → Add files / Add folder.
Önce Token cost veya Dry run → logda yazmadan önizleme.
Sonra Bundle (yalnızca değişenler) veya Force run (hepsi) → gerçek yazım.
İşlem sürerken dört buton kilitlidir; X ile kapatınca worker bitince TEMP temizlenir.

5.5 NotebookLM için önerilen senaryo

Öncelikli yükle: bundle_lib, bundle_backend, asıl iş mantığı paketleri, bundle_general, bundle_manifest.json
İhtiyaç olunca ekle: web / UI kaynakları
Çoğu zaman ertele: android, ios, windows gibi native şablon ağırlıklı klasörler (gürültü / token maliyeti yüksek olabilir)

5.6 Kopyala–yapıştır şablon (Windows PowerShell)

cd C:\Users\<username>\Documents\GitHub\<your-project-folder>

$env:SMART_BUNDLER_OUTPUT = "G:\My Drive\NotebookLM_Paketler"

py -3 C:\Users\<username>\Documents\GitHub\notebook_script\main.py -d
py -3 C:\Users\<username>\Documents\GitHub\notebook_script\main.py