bookmaker-studio 0.3.1

Akademik ve teknik kitap üretim stüdyosu

bookMaker

LLM destekli, kalite kapili, proje tabanli akademik/teknik kitap uretim framework'u.

Kitap projesi  →  book_manifest.yaml  →  6 asamali pipeline  →  DOCX/PDF/EPUB/HTML
                                     →  Studio GUI (localhost:8765)

LLM'ler icin: Projeyi tam olarak anlamak isteyen AI ajanlari docs/architecture.md dosyasini okumali. Bu dosya mimari, pipeline, GUI ve tum ozellikleri tek bir dokumanda aciklar.

---

Icerik

• Kurulum
• Studio GUI
• Kitap Proje Yapisi
• Pipeline
• CLI Kullanim
• Test
• Dokumanlar
• Gelistirme Ilkeleri

---

Kurulum

git clone https://github.com/bmdersleri/bookMaker.git
cd bookMaker
uv sync

Baslangic:

uv run python -m bookmaker.studio.app    # GUI (http://localhost:8765)
bookmaker check book <kitap-dizini>      # CLI kalite kontrol
bookmaker check toolchain                # Gelistirme araci kontrolu

---

Development Environment

Onerilen gelistirme ortami:

• Python 3.12+
• uv
• Pandoc
• Node.js + npm
• Opsiyonel: Java JDK
• Opsiyonel: Dart/Flutter
• Opsiyonel: Mermaid CLI (mmdc)

Yerel kontrol:

uv sync
uv run pre-commit install
uv run ruff check src/ tests/
uv run pytest tests/ -q --tb=short

Run uv run pre-commit install once after cloning to enable commit-time checks.

Devcontainer/Codespaces destegi kaldirildi. Port 8765 uzerinden yerel olarak calistirilabilir.

---

Studio GUI

6 sekme, vanilla JS, karanlik/aydinlik mod destegi olmayan sade arayuz.

Sekme	Ozellikler
Bolumler	Tablo (sirala, filtrele, sayfala), drag-drop siralama, basliklara cift tiklayip inline edit, toplu silme, bolum ekleme wizard'i, bolum bazli Gor/ Kontrol/Build/Uret butonlari
Pipeline	Manuel tetikleme, canli progress bar, job detay paneli (adim adim prompt→cikti eslesmesi + sure), iptal, job gecmisi
Kalite	Kitap ozeti (skor/karar/hata/uyari), bolum kalite tablosu, kontrol modali, istatistikler, tam metin arama
Build/Export	Export hedefleri, readiness pre-check (/api/export/readiness), kod dogrulama (adapter tabanli ok/error/skipped), referans DOCX / lua filter / TOC derinligi secimi, kod cikarma, Mermaid render, birlestirme, format export (output/report linkleriyle), yedekleme
Promptlar	Varsayilan/bolum prompt editoru, dirty-state uyarisi, yukle/kaydet
Yapilandirma	book_manifest.yaml full editor (Kitap Bilgisi, Uretim, Stil, Otomasyon, Export alt sekmeleri)

---

Kitap Proje Yapisi

Her kitap book_projects/ altinda bagimsiz bir dizindir:

<kitap-adi>/
├── book_manifest.yaml          # TEK konfigurasyon kaynagi (kitap, uretim, stil, pandoc, output, bolumler)
├── pipeline_state.yaml         # Runtime durum, kalite skoru, otomasyon bayraklari
├── prompts/
│   ├── default_chapter.md      # Varsayilan bolum uretim promptu
│   └── default_review.md       # Varsayilan review promptu
├── chapters/
│   └── <bolum-alias>/
│       ├── chapter_manifest.yaml
│       ├── prompt.md
│       └── content/
│           ├── draft.md        # Uretilen taslak
│           ├── final.md        # Onaylanmis final
│           └── revisions/
├── exports/                    # Build ciktilari
│   ├── docx/
│   ├── pdf/
│   └── md/
└── logs/                       # Runtime loglar
    ├── production/             # Pipeline adim ciktilari (job bazli)
    │   └── export_<ts>.json    # Export readiness + sonuc raporu
    ├── errors/
    └── reviews/                # Kalite review raporlari

Kurallar:

• book_manifest.yaml tek konfigurasyon kaynagidir; book_profile.yaml sadece legacy okuma fallback'idir
• Bolum sirasi book_manifest.yaml > chapters listesinden alinir
• Dosya yollari YAML'de tekrarlanmaz — alias'tan convention ile turetilir
• pipeline_state.yaml runtime durumu tutar, framework tarafindan yonetilir

Desteklenen Python sürümü: en az 3.12, geliştirme ortamında 3.14.x kullanılır.

---

Pipeline

6 asamali LLM destekli bolum uretim hatti:

SPEC ──→ VALIDATE ──→ SEED ──→ NORMALIZE ──→ ENRICH ──→ ASSEMBLE
(plan)    (kontrol)    (uretim)  (temizlik)    (paralel)    (birlestirme)

Asama	Surec	Cikti
SPEC	LLM'e baslik + kavram verilir, KOD YAZMAZ, plan hazirlar	step0_spec.md + prompt0_spec.txt
VALIDATE	SPEC ciktisi format ve kapsam acisindan kontrol edilir	step0_validation.md
SEED	6 adimli pedagojik zincirle gercek bolum icerigi uretilir	step1_seed.md + prompt1_seed.txt
NORMALIZE	0-token regex temizligi, front matter ekleme, heading duzeltme	step2_normalized.md
ENRICH	6 paralel LLM cagrisi (ozet, sozluk, soru, alistirma, hata, kopru)	step3_enrich_*.md (6 dosya)
ASSEMBLE	Zenginlestirmeler birlestirilir, son normalize, draft'a yazilir	step4_final.md → draft.md

6 adimli pedagojik derinlik zinciri: TANIM → NEDEN VAR? → NASIL KULLANILIR? → NE ZAMAN TERCİH EDİLİR? → ALTERNATİFLERİ → YAYGIN HATALAR

Detayli dokumantasyon: docs/pipeline.md

---

Kod Dogrulama ve Adapter Mimarisi

src/bookmaker/code/adapters/ altinda profil-tabanli kod dogrulama adapter'lari bulunur. Her adapter kendi dilinin arac zincirini kullanarak kod bloklarini kontrol eder:

Profil	Adapter	Dil	Arac
Java	JavaCodeAdapter	Java	javac
Flutter	FlutterCodeAdapter	Dart	dart analyze (hazirlik)
Python	PythonCodeAdapter	Python	python -m py_compile
React	ReactCodeAdapter	JS	node --check (TS/JSX/TSX → review-only skip)
Diger	ReviewOnlyAdapter	Herhangi	Manuel inceleme

Adapter secimi code/runner.py icindeki select_code_adapter(profile, code_language) ile yapilir. quality_service.compile_code() adapter secimini otomatik olarak manifest profilinden yapar.

src/bookmaker/code/
├── adapters/
│   ├── base.py        # CodeAdapter (ABC) + ReviewOnlyAdapter
│   ├── java.py        # javac derleme + hata ayiklamasi
│   ├── flutter.py     # Dart/Flutter (placeholder, guvenli skip)
│   ├── python.py      # py_compile syntax kontrolu
│   └── react.py       # node --check (JS) + review-only (TS/JSX)
├── extractor.py       # extract_fenced_blocks() — Markdown'dan kod blogu cikarma
├── models.py          # CodeBlock, CodeTestResult dataclass'lari
├── report.py          # summarize_test_results() — sonuc ozeti
└── runner.py          # select_code_adapter() — profil/dil cozumu

---

Gorsel Motorlar: Mermaid ve Screenshot

Pipeline, iki gorsel uretim motoruyla entegre calisir:

Mermaid Tema Motoru

src/bookmaker/production/ altinda profil-tabanli Mermaid tema motoru bulunur:

Modul	Islev
mermaid_theme.py	5 profil temasi (flutter/java/python/react/default), JSON tabanli, config_file() context manager
mermaid_renderer.py	mmdc tabanli PNG renderer, MD5 cache ile idempotent, MermaidRenderConfig.from_manifest()
themes/	5 JSON tema dosyasi

normalize_with_mermaid() (postprocess.py) NORMALIZE asamasinda mermaid bloklarini PNG'ye donusturur. mmdc kurulu degilse sessizce gecer.

Screenshot Engine

src/bookmaker/production/screenshot_strategies/ altinda 5 strateji:

Strateji	Fence Syntax	Islev
python_plot	python plot	matplotlib/plotly/seaborn → PNG
python_console	python console	Terminal ciktisi → stillendirilmis PNG
react_component	jsx screenshot	React bileseni → headless Chromium PNG
flutter_golden	dart screenshot	Flutter widget → headless golden test PNG (~5s, emulator yok)
flutter_web	dart web-screenshot	Flutter ekrani → web build + Playwright PNG (~30-60s)

process_screenshots() (postprocess.py) ASSEMBLE sonrasi _save_chapter() icinde cagrilir. Playwright/Flutter SDK kurulu degilse sessizce gecer.

src/bookmaker/production/
├── screenshot_engine.py         # Ana motor, tagged block regex, cache
├── screenshot_strategies/
│   ├── base.py                  # ScreenshotStrategy (ABC) + ScreenshotConfig
│   ├── python_plot.py           # matplotlib/plotly/seaborn grafikleri
│   ├── python_console.py        # Terminal ciktisi (dark/light tema)
│   ├── react_component.py       # CDN React + Babel render
│   ├── flutter_golden.py        # Headless golden test (Dart VM)
│   ├── flutter_web.py           # Web build + Playwright screenshot
│   └── flutter_utils.py         # Dart kod analizi ve sablon ureticileri
├── mermaid_theme.py             # MermaidTheme + MermaidThemeManager
├── mermaid_renderer.py          # MermaidRenderer + MermaidRenderConfig
└── themes/                      # 5 profil temasi (JSON)

Her iki motor da manifest uzerinden yapilandirilir:

# book_manifest.yaml
mermaid:
  theme: flutter
  scale: 2
  background: white
  width: 900

production:
  screenshots:
    enabled: true
    python_timeout: 15
    terminal_theme: dark
    scale: 2

---

CLI Usage

# Book-level quality checks
bookmaker check book book_projects/flutter-ile-mobil-uygulama-gelistirme
bookmaker check book book_projects/flutter-ile-mobil-uygulama-gelistirme --json --verbose

# Single chapter check
bookmaker check chapter chapters/giris/content/draft.md --book-root book_projects/...

# Final Markdown render/code gate
bookmaker check final book_projects/veri-yapilari-ve-algoritmalar
bookmaker check final book_projects/veri-yapilari-ve-algoritmalar --verbose
bookmaker check final book_projects/veri-yapilari-ve-algoritmalar --json

# Retry only failed/fallback ENRICH sub-steps
bookmaker generate retry-enrich bolum-01 --path book_projects/veri-yapilari-ve-algoritmalar
bookmaker generate retry-enrich bolum-01 --path book_projects/veri-yapilari-ve-algoritmalar --types soru,sozluk --apply

# Generation iteration reports
bookmaker report chapter bolum-01 --path book_projects/veri-yapilari-ve-algoritmalar
bookmaker report book --path book_projects/veri-yapilari-ve-algoritmalar
bookmaker report book --path book_projects/veri-yapilari-ve-algoritmalar --last 10 --json

bookmaker check final validates generated content/final.md files before they are published or committed. It currently checks balanced code fences, orphan language markers, leftover model formatting such as Insight boxes, Markdown table column consistency, and Python fenced blocks with ast.parse.

Generated draft.md and VYA final.md save paths now call the same validation gate before writing user-facing Markdown. bookmaker generate retry-enrich can retry only failed or fallback ENRICH sub-steps and optionally apply the result through the gated save path.

---

Tests

uv run ruff check src/                      # lint
uv run pytest tests/ -q --tb=short
uv run bookmaker check book book_projects/flutter-ile-mobil-uygulama-gelistirme --json
uv run bookmaker check final book_projects/veri-yapilari-ve-algoritmalar

---

CI and Quality Gates

The project uses local and CI quality gates to prevent malformed generated content from entering the repository:

• Ruff lint (src/ and tests/)
• Pytest test suite
• Prompt validation
• Book-level quality checks
• Final Markdown render/code validation via bookmaker check final
• Automatic final Markdown gate before generated draft/final saves
• Selective ENRICH retry for failed/fallback sub-steps
• Generation iteration tracking (chapters/<alias>/logs/runs.jsonl)
• bookmaker report chapter/book iteration history with word delta and gate result
• Studio Quality tab "Üretim Geçmişi" panel
• Python 3.12 / 3.13 matrix

Recommended local checks:

uv run ruff check src/ tests/
uv run pytest tests/ -q --tb=short
uv run bookmaker check final book_projects/veri-yapilari-ve-algoritmalar

---

Dokumanlar

Dosya	Amac
docs/architecture.md	AI ajanlari icin eksiksiz proje aciklamasi + mimari referans (mimari, pipeline, GUI, API, tasarim kararlari)
STATUS.md	Guncel proje durumu — pre-commit hook ile otomatik guncellenir
docs/architecture.md	Mimari referans ve tasarim kararlari (LLM_EXPLANATION ile birlestirme)
CLAUDE.md	Claude Code agent talimatlari
docs/pipeline.md	6 asamali pipeline detayli dokumantasyonu
docs/studio.md	Studio GUI gelistirme yol haritasi (Faz 1-6 ✅, Faz 7 planlandi)
CHANGELOG.md	Surum gecmisi (v0.1.0, v0.2.0)
docs/_archive/todo-2026-05.md	Eski yapilacaklar listesi (arsivlendi, GitHub Issues'a tasindi)
docs/_archive/migration-2026-05.md	Project-based mimari gecis kaydi (tamamlandi, arsivlendi)
docs/release.md	Release oncesi kontrol listesi
docs/workspace.md	Kitap proje klasor standardi ve manifest ornekleri
docs/	Tarihi tasarim ve planlama dokumanlari arsivi
docs/_archive/kullanim-kilavuzu-2026-05.md	Eski Windows/PowerShell kullanim kilavuzu (arsivlendi)

---

Gelistirme Ilkeleri

• book_manifest.yaml tek dogruluk kaynagi — burada olmayan konfigurasyon yoktur
• Bolumleri alias ile referansla, numeric ID veya path ile degil
• Her patch sonrasi 3'lu kontrol: ruff check → pytest → bookmaker check book
• Kucuk, review edilebilir commit'ler; buyuk refactor'dan kacin
• llm_config.json ve .claude/settings.local.json asla commit edilmez
• Pipeline hata durumunda durmaz — non-fatal hatalarda devam eder, log'a yazar