bookmaker-studio 0.4.0

Akademik ve teknik kitap üretim stüdyosu

bookMaker

LLM-assisted, author-controlled, quality-gated academic/technical book production studio.

book_manifest.yaml  →  6-stage pipeline  →  DOCX / PDF / EPUB / HTML
                    →  Studio GUI (localhost:8765)

---

Quick mental model

The framework is separate from book projects.

The framework (this repo): CLI, Studio GUI, generation pipeline, validation, release/export, supporting modules.

A book project (outside this repo): book-specific manifest, chapter manifests, prompts, drafts, finals, logs, exports. Lives at ~/projects/books/<name>/.

---

Start here

For agents and first-time users:

File	Purpose
START_HERE.md	Identity, pipeline overview, safe commands
AI_CONTEXT.md	Compact mental model for agents
.llm/reading_order.md	Task-specific reading order
docs/INDEX.md	Full documentation index
AGENTS.md	Full operating rules for coding agents

---

What bookMaker produces

• Validated LLM-generated chapter drafts (Markdown)
• Author-approved final chapters
• Structured book exports: DOCX, PDF, EPUB, HTML
• Quality reports, critique logs, release tags

---

Canonical book production pipeline

SPEC → VALIDATE → SEED → NORMALIZE → ENRICH → ASSEMBLE

Stage	What happens
SPEC	Build chapter specification from manifest
VALIDATE	Validate spec before generating
SEED	Generate initial chapter content
NORMALIZE	Clean and structure raw output
ENRICH	Add code examples, diagrams, callouts
ASSEMBLE	Combine into final draft.md

---

Installation

git clone https://github.com/bmdersleri/bookMaker.git
cd bookMaker
uv sync
uv run pre-commit install

Requirements: Python 3.12+, uv, Pandoc (for export), Node.js + npm (optional), mmdc (Mermaid, optional).

---

Minimal commands

# Start Studio GUI (http://localhost:8765)
uv run python -m bookmaker.studio.app

# Validate a book project (safe, no LLM calls)
uv run bookmaker check book <book-dir>

# Check toolchain
uv run bookmaker check toolchain

# Run fast tests
just fast

---

Documentation

File	Purpose
docs/00_BIG_PICTURE.md	Problem space, actors, artifacts
docs/01_BOOK_PRODUCTION_FLOW.md	Step-by-step production guide
docs/02_PROJECT_LAYOUT.md	Repo + book project layout
docs/03_COMMANDS.md	Command reference (safe vs costly)
docs/05_ARCHITECTURE_MAP.md	Compact module map
docs/architecture.md	Full architecture reference
docs/pipeline.md	Pipeline stage deep-dive
docs/studio.md	Studio GUI feature reference
docs/release.md	Release/export module
docs/AI_COPILOT_OPENCODE.md	OpenCode Copilot Integration
STATUS.md	Current project state
CHANGELOG.md	Version history

---

Agent onboarding

Agents new to this repository should read in this order:

1. START_HERE.md
2. AI_CONTEXT.md
3. .llm/reading_order.md
4. docs/01_BOOK_PRODUCTION_FLOW.md
5. docs/02_PROJECT_LAYOUT.md
6. AGENTS.md

See examples/minimal-book/ for a minimal valid book project layout.

---

Development validation

# Lint
uv run ruff check src/ tests/

# Fast test suite
just fast

# Full test suite
uv run pytest tests/ -q --tb=short

# Validate example book project
uv run bookmaker check book examples/minimal-book --json

---

Safety notes

• book_manifest.yaml is the single config source — everything else is derived.
• Do not run bookmaker generate * without explicit user approval (LLM API calls).
• Never commit .env, llm_config.json, or .claude/settings.local.json.
• Generated draft.md and pipeline_state.yaml are pipeline outputs — do not manually edit.
• Book projects live outside this repo (~/projects/books/ or $BOOKMAKER_PROJECTS_DIR).

---

Studio GUI tabs

Tab	Features
Bölümler	Chapter table, drag-drop reorder, inline edit, bulk delete, add wizard
Pipeline	Manual trigger, live progress, job detail panel, cancel, job history
Kalite	Quality summary (score/decision/errors/warnings), chapter table, full-text search
Build/Export	Export targets, readiness pre-check, code validation, Mermaid render, format export
Promptlar	Default/chapter prompt editor, dirty-state warning, load/save
Yapılandırma	book_manifest.yaml full editor (Book, Production, Style, Automation, Export subtabs)
Manifest Üret	8-agent manifest generation wizard (Architect→Pedagog→Debate→Engineer→Coder→Assessor→Editor→Author→CoherenceChecker)
Araştırma	Arxiv/Crossref/Semantic Scholar source suggestion + approval
Hafıza	sqlite-vec vector recall, reindex, stats, reviewer feedback log
Hakem	Profile/chapter selection, LLM reviewer simulation, feedback save
Release	Readiness check, approve/unapprove chapters, tag version, export