Metadata-Version: 2.4
Name: bookmaker-studio
Version: 0.3.1
Summary: Akademik ve teknik kitap üretim stüdyosu
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.110
Requires-Dist: jinja2>=3.1
Requires-Dist: playwright>=1.59.0
Requires-Dist: prometheus-client>=0.20
Requires-Dist: pydantic>=2
Requires-Dist: python-docx>=1.1
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.33.1
Requires-Dist: rich>=13
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: sentence-transformers>=2.7
Requires-Dist: sqlite-vec>=0.1
Requires-Dist: sse-starlette>=2.0
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.29
Description-Content-Type: text/markdown

# bookMaker

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

```text
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](#kurulum)
- [Studio GUI](#studio-gui)
- [Kitap Proje Yapisi](#kitap-proje-yapisi)
- [Pipeline](#pipeline)
- [CLI Kullanim](#cli-kullanim)
- [Test](#test)
- [Dokumanlar](#dokumanlar)
- [Gelistirme Ilkeleri](#gelistirme-ilkeleri)

---

## Kurulum

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

**Baslangic:**

```powershell
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:

```powershell
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:

```text
<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:

```text
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`](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.

```text
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.

```text
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:

```yaml
# 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

```powershell
# 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

```powershell
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:

```powershell
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
