bourbaki

package module
v0.0.0-...-27ce90d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 2, 2026 License: MIT Imports: 0 Imported by: 0

README

bourbaki-solver

Go toolchain that turns Bourbaki PDFs into a tagged Markdown corpus, translates it, and solves the exercises.

The corpus it produces lives in tamnd/bourbaki. This repo is code and specs.

What it does

PDF ──┬─ pdftotext -layout ──────────────┐
      │  (born digital: Algebra VIII)    │
      │                                  ├─ page files ─ assemble ─ split ─ tag ─ Markdown
      └─ pdftoppm ─ vision OCR fleet ────┘                                        │
         (scans: Algebra I-III, IV-VII)                                           │
                                                          translate (vi/zh/ja) ───┤
                                                          solve exercises ────────┘

Eight chapters of Algebra, 1699 pages. Two of the three volumes are 600 dpi JBIG2 scans whose legacy text layer is unusable for mathematics, so they go through vision OCR. The 2023 volume has a real text layer and extracts natively.

Install

go install github.com/tamnd/bourbaki-solver/cmd/bourbaki@latest

Needs poppler for pdfinfo, pdftotext, pdftoppm, pdfimages and pdffonts:

brew install poppler

Use

export BOURBAKI_CORPUS=$HOME/github/tamnd/bourbaki

bourbaki books add "pdf/en/Algebra Chapter 8 (2023, Springer Nature).pdf" --id alg-viii
bourbaki pagemap build --book alg-viii
bourbaki extract --book alg-viii
bourbaki assemble --book alg-viii
bourbaki split --book alg-viii --force --sync
bourbaki tags assign && bourbaki tags verify
bourbaki audit --report reports/audit.md

bourbaki --help lists everything else: fleet, ocr, queue, refs, translate, solve, eval, report, publish.

The fleet

Model calls go through tamnd/chatgpt-tool running on a few hosts. The listener is loopback only, so text stages talk to it over SSH tunnels and OCR is driven over SSH directly, because the proxy takes no image input over HTTP.

A round trip is around 150 seconds. That single number shapes most of the design: work is a durable on disk queue with leases, batches are large, every stage is resumable, and nothing assumes API latency. Kill the process mid run and start it again, it picks up where it stopped.

Host names, keys and the design notes stay out of this repo. The milestones are tracked as issues.

Layout

cmd/bourbaki      CLI
corpus            labels, tags, front matter, corpus model
pdfsrc            poppler wrappers
pagemap           printed page label to PDF page
extract           native text extraction
fleet             SSH, tunnels, routing, queue
api               chat client
assemble          pages to sections
share             public ChatGPT share pages, read whole over plain HTTP
translate         vi, zh, ja
solve             exercise solver and verifier
audit             corpus checks
publish           the static site, built out of the committed Markdown
katex             KaTeX under a JS engine, which sets the mathematics at build time

Licence

MIT for the code. The corpus it builds is derived from copyrighted material and is for personal study, see the licence in the corpus repo.

katex/ holds a vendored copy of KaTeX 0.18.4 with its stylesheet and its woff2 fonts, under the MIT licence in katex/LICENSE. The bytes are checked against katex/SHA256SUMS by a test.

Documentation

Overview

Package bourbaki builds a tagged, multilingual Markdown corpus from the PDFs of Bourbaki's Éléments de mathématique.

The pipeline is: extract each page, either natively for the born-digital volume or through vision OCR for the scans, assemble pages into sections, split out exercises, assign permanent tags, resolve cross-references, translate, and solve.

The subpackages carry the work. This root package holds only the version string, so that importers can depend on it without pulling in poppler or SSH.

Index

Constants

This section is empty.

Variables

View Source 
var Version = "dev"

Version is set at build time with -ldflags "-X github.com/tamnd/bourbaki-solver.Version=...".

Functions

This section is empty.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
Package api is the model transport: one request shape, one response shape, and a client that speaks the OpenAI chat completions wire.
 Package api is the model transport: one request shape, one response shape, and a client that speaks the OpenAI chat completions wire.
Package assemble puts the pages of a chapter back into the sections the book is written in.
 Package assemble puts the pages of a chapter back into the sections the book is written in.
Package audit reads an accepted page and points at the places worth one question.
 Package audit reads an accepted page and points at the places worth one question.
Package benchmark is the fixed set the verifier is measured against.
 Package benchmark is the fixed set the verifier is measured against.
Package book builds a printed volume back out of the corpus.
 Package book builds a printed volume back out of the corpus.
Package clip cuts a page out of a printed volume and asks a model to read the picture of it.
 Package clip cuts a page out of a printed volume and asks a model to read the picture of it.
cmd
bourbaki command
Command bourbaki builds the Markdown corpus in tamnd/bourbaki from the source PDFs.
 Command bourbaki builds the Markdown corpus in tamnd/bourbaki from the source PDFs.
ocrfixtures command
Command ocrfixtures records what this repository's acceptance rules and text normalisation actually do, as JSON, so that a reimplementation elsewhere can be tested against the original rather than against its author's memory of it.
 Command ocrfixtures records what this repository's acceptance rules and text normalisation actually do, as JSON, so that a reimplementation elsewhere can be tested against the original rather than against its author's memory of it.
Package corpus models the structure of the Bourbaki corpus: books, chapters, sections, statements, and the permanent tags that identify them.
 Package corpus models the structure of the Bourbaki corpus: books, chapters, sections, statements, and the permanent tags that identify them.
Package crosscheck reads a page twice and reports the words only one reading has.
 Package crosscheck reads a page twice and reports the words only one reading has.
Package fleet is the three rented boxes: what is installed on them, the tunnels that reach their loopback listeners, and the supervisor that puts a tunnel back when it dies.
 Package fleet is the three rented boxes: what is installed on them, the tunnels that reach their loopback listeners, and the supervisor that puts a tunnel back when it dies.
Package footnote is the mark a book prints beside a footnote, and what to do with it once the note is Markdown.
 Package footnote is the mark a book prints beside a footnote, and what to do with it once the note is Markdown.
Package glossary is the terminology contract between the four languages.
 Package glossary is the terminology contract between the four languages.
Package katex renders TeX to HTML at build time, with no Node and no network, by running the real katex.min.js inside a JavaScript engine.
 Package katex renders TeX to HTML at build time, with no Node and no network, by running the real katex.min.js inside a JavaScript engine.
Package mathtex is where the mathematics of a body starts and stops, and what to do about a character that was left outside its TeX.
 Package mathtex is where the mathematics of a body starts and stops, and what to do about a character that was left outside its TeX.
Package ocr reads the pages of a scanned volume through a model and decides whether what came back is a transcription.
 Package ocr reads the pages of a scanned volume through a model and decides whether what came back is a transcription.
Package pagemap builds the map from a PDF's own page numbering to the page numbering Bourbaki printed.
 Package pagemap builds the map from a PDF's own page numbering to the page numbering Bourbaki printed.
Package pdfglyph puts back the mathematics a printing hides in its glyph names.
 Package pdfglyph puts back the mathematics a printing hides in its glyph names.
Package pdfsrc wraps the poppler command line tools.
 Package pdfsrc wraps the poppler command line tools.
Package prompt holds the prompts the pipeline sends to a model.
 Package prompt holds the prompts the pipeline sends to a model.
Package publish turns the committed Markdown into a static site.
 Package publish turns the committed Markdown into a static site.
Package quality is the corpus audit: every quality claim this project makes, written down as a rule that runs.
 Package quality is the corpus audit: every quality claim this project makes, written down as a rule that runs.
Package queue is the work list on disk.
 Package queue is the work list on disk.
Package refs reads the cross-references Bourbaki writes into his prose and turns them into a graph over the permanent tags.
 Package refs reads the cross-references Bourbaki writes into his prose and turns them into a graph over the permanent tags.
Package render turns the scanned volumes into page images for vision OCR.
 Package render turns the scanned volumes into page images for vision OCR.
Package repair asks the model to fix a page it has already read, and proves that what came back is a fix rather than a rewrite.
 Package repair asks the model to fix a page it has already read, and proves that what came back is a fix rather than a rewrite.
Package report reads the run logs back and says what the fleet did.
 Package report reads the run logs back and says what the fleet did.
Package roundtrip is the sampled round trip over the translations.
 Package roundtrip is the sampled round trip over the translations.
Package route names the hosts a run can send model calls to, orders them, and keeps the run moving when one of them stops answering.
 Package route names the hosts a run can send model calls to, orders them, and keeps the run moving when one of them stops answering.
Package share reads a public ChatGPT share page.
 Package share reads a public ChatGPT share page.
Package solve builds what a model is shown when it is asked to do an exercise, and will hold the pipeline that asks.
 Package solve builds what a model is shown when it is asked to do an exercise, and will hold the pipeline that asks.
Package tags allocates and keeps the permanent identifiers of the corpus.
 Package tags allocates and keeps the permanent identifiers of the corpus.
Package textguard catches the ways a model's answer is not what was asked for, before it reaches the corpus.
 Package textguard catches the ways a model's answer is not what was asked for, before it reaches the corpus.
Package toc reads a volume's table of contents into the chapter, §, and no.
 Package toc reads a volume's table of contents into the chapter, §, and no.
Package translate turns an English section body into another language and refuses most of what comes back.
 Package translate turns an English section body into another language and refuses most of what comes back.
Package typography puts back the marks a printing sets that a reading of the page image writes as the nearest thing on a keyboard.
 Package typography puts back the marks a printing sets that a reading of the page image writes as the nearest thing on a keyboard.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.