MathBook Agent

MathBook Agent is a reusable workflow for writing mathematical books with Codex, source-grounded KBs, TeX, figures, review gates, and repair tools.

Workspace

Keep code, source material, and generated books separate:

parent\mathbook-agent        code repository
parent\book-resources       read-only source materials
parent\mathbook-experiments generated books and experiment results

Only mathbook-agent is maintained as a Git repository and pushed to a remote. book-resources and mathbook-experiments are private local data directories; MathBook never runs git init in either one. In particular, OCR output, images, KB indexes, agent logs, intermediate TeX, and generated PDFs stay out of Git.

Run commands from the cloned mathbook-agent directory. MathBook creates the two sibling directories when needed, copies registered sources into each experiment, and does not edit book-resources.

Setup

Required software: Python, uv, an authenticated Codex CLI, TeX Live, and PDF tools. See docs/local-install.md for the complete list.

cd mathbook-agent
uv sync
uv run mathbook skills --standalone

For local OCR credentials, copy .env.example to .env and fill in PADDLEOCR_TOKEN. The ignored .env is loaded automatically; existing environment variables take precedence.

Start A Book

uv run mathbook init "<direction-or-source>" --title "<title>"
uv run mathbook studio

The source path is relative to the sibling book-resources directory. It may name one file or a direction folder; folders are scanned recursively for PDF, TeX, and Markdown sources. The experiment directory is created automatically from the title. Studio opens the most recently used experiment when --repo is omitted.

Use --additional-source during initialization, or Studio [N], to add more PDF, TeX, or Markdown references. Native-source images/, imgs/, and figures/ directories are copied with their relative paths intact.

Studio Workflow

Studio is the normal interface. It keeps running in the current terminal and resumes from saved project state. Generated book directories do not need Git; Codex is invoked with its generated-workspace trust check disabled.

See docs/studio-workflow.md for the complete Chinese operation flow, menu reference, resume behavior, and blocker guide.

The default route is:

1. Describe the reader, book goal, source roles, style, and constraints.
2. Extract PDFs, repair only low-quality OCR, and build source-anchored KBs.
3. Review the generated source audit and approve the outline.
4. Draft and approve Chapter 01; Chapter 02 review is optional.
5. Generate later chapters automatically.
6. Repair, expand, inspect figures, add biographies, create the cover and write the afterword from the same terminal session.

Common Studio actions:

Key	Action
A	Continue the current workflow
G	Approve the current outline, biography, or cover review
1	Approve the current calibration chapter and continue automatically
2	After Chapter 01, stop once more to review Chapter 02
B	Resume unfinished later-chapter generation
R	Repair issues from problems.md
E	Expand selected chapters
V	Process and review figures
P	Plan and insert mathematician biographies
N	Add a reference source
C	Run the cover workflow
W	Run the afterword/QR workflow (reads chapter TeX only; images/OCR/KB are isolated)
X	Capture reusable repair experience

Project Artifacts

Each experiment is self-contained:

book.toml                 project configuration
book.tex                  root TeX document
sources/                  copied sources, OCR, repaired text, and KBs
blueprint/                source plan, outline, contracts, and ledgers
chapters/                 chapter TeX files
figures/ and images/      book assets
claims/                   source traceability
logs/                     reviews, gates, reports, and experiment summary
problems.md               current experiment's repair inbox
.mathbook/                resumable Studio state, tasks, and run logs

The active project's problems.md and deterministic checks are authoritative. Cross-experiment repair experience is advisory and never overrides the current book.

Design Rules

• MathBook is topic-agnostic. Source ratios, chapter mappings, page ranges, reader level, and editorial policy come from the project's initialization prompt.
• Chapter 01 requires human approval by default; Chapter 02 is optional; later chapters run automatically.
• PDFs pass through OCR and a quality gate. Clean OCR becomes canonical directly; scanned or uncertain output is repaired before KB construction.
• A PDF with a same-named Markdown or TeX source is treated as its layout/image companion and skips OCR, repair, and duplicate KB construction.
• Mathematical figures use the bundled OpenTikZ workflow and hash-bound visual review.
• Optional modules such as biographies, cover, afterword, and QR output are enabled per book.
• New references append to the existing KB and source plan without rebuilding unrelated indexes or rewriting approved chapters.

Development

uv run python -m unittest discover -s tests -v
uv build

Use uv run mathbook --help for the low-level CLI reference. Normal book work should use mathbook studio rather than assembling many CLI commands.