Skip to content

About

Read a research paper beside its Lean proof code, with links to exact statements and a diagram of how the proof fits together.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Proof Reader

Will Cook’s home page: all projects and videos

Proof Reader displays a research paper beside its proof in Lean, a language for writing mathematical statements and proofs that a computer can check. Click a linked statement in the paper to open the authors' corresponding Lean code. You can also explore a diagram of the proof steps and the connections between them.

Read a paper in it: Contextual Embeddings by Frohlich, Foster, Kavvos and Wang (PLDI 2026), shown with the authors' Lean under CC BY 4.0. The links and comparisons between the paper and the Lean were made with AI and have not been reviewed by the authors.

A paper on the left page with one sentence highlighted, and on the right the graph of its Lean proof above the exact Lean lines the sentence describes.

For a specific example, open a paragraph and its five linked lines of Lean, linked to Lean lines 217 to 221.

The PCP collection contains a detailed argument, a specialist paper, and a worked exposition. In the reader these use the routes #/pcp-full-argument, #/pcp-specialist, and #/pcp-exposition; Troy Lee's original reading guide remains at #/pcp-reading-guide. The algebraic proof is due to Amireddy, Behera, Srinivasan, Sudan and Willumsgaard; Lee wrote the Lean formalization. Will Cook prepared the three explanations with AI assistance.

On a desktop, each visit opens with the paper on the left and the proof pane on the right: the graph above the Lean, or beside it on a very wide screen. Drag the divider between the paper and the proof to give either side more room, and the handle between the graph and the Lean to share the pane; both are remembered. Closing the proof pane lasts for that visit. As you scroll, the proof pane follows the linked passage you are reading: the Lean shows its declaration, and the graph shows that declaration with what it uses, with no click needed. A statement you open by clicking it stays until you read on to another statement. Above the Lean, the graph takes only the room its drawing needs. Click a statement or diagram card to see its Lean code. Use Back to return to the diagram without losing your place, or the Graph / Lean toggle to choose what stays beside the paper.

Citations and figures open beneath the paragraph that mentions them. Each linked statement has its own address, so you can send someone directly to it. The contents also include an index of named Lean definitions and theorems (called declarations), with the assumptions each proof uses (axioms).

For PDF papers, a program checks the reading copy against extracted text, and the original PDF is one click away. Markdown-source pages render their supplied text directly and check each linked quote against its exact source heading and block. Declaration titles, links, notes and comparisons are marked as AI-made and not reviewed by the authors. Comparisons can be held; where one cites a Lean check written for the page, the check and its reported axioms are shown.

Evidence differs by page. Some declaration data comes from Lean's report on compiled modules. For the three PCP companions, Lean compiled the listed modules of the authors' project in a GitHub Actions run, and every declaration's dependencies and axiom report is Lean's output from that run. The original guide's page keeps its earlier extraction, with a statement-only compilation of the headline theorem. Comparator accepted the authors' proofs of the three headline statements in a second run. Sentence-by-sentence comparisons of statements with their Lean have not been written. The source review records the source pin and hashes. Neither a source link nor a correspondence check establishes that the prose and Lean have the same meaning.

Run the site

Use Python 3.11 or later, Node 20.19 or later, and Poppler (brew install poppler on macOS; sudo apt-get install poppler-utils on Ubuntu). From a fresh clone:

git clone https://github.com/wcook04/proof-reader.git
cd proof-reader
cd web
npm ci
cd ..
python3 tools/paper.py build
cd web
npm run dev

Open the address it prints and choose a paper. The paper build creates the data the site needs from checked-in declaration records, so reading the existing papers does not require Lean. After changing a paper's files, run python3 tools/paper.py build again from the repository root.

From web/, npm run build writes a static site to web/dist. npm run preview serves that build locally. If you set VITE_BASE_PATH for the build, use the same setting for the preview. For example, a build made with VITE_BASE_PATH=/proof-reader/ npm run build needs VITE_BASE_PATH=/proof-reader/ npm run preview.

To test the reading controls in a real browser, build the site and run the browser test script. It needs Playwright for Python, and takes --browser firefox or webkit as well:

cd web && VITE_BASE_PATH=/proof-reader/ npm run build && cd ..
python3 tests/journey.py --shots /tmp/journey

tests/speed.py measures a paper's first screen on a home connection.

tools/capture_images.py retakes the social card, the picture above and the front page's two pictures of the reader from a running site.

Add a paper

To add a paper, create a folder containing its PDF or Markdown source, the Lean project, and links between passages and Lean statements. For a PDF, provide a reading copy as well. The build command turns those files into pages for the website.

papers/<slug>/
  paper.pdf      the authors' PDF, unchanged, for a PDF source
  paper.md       a PDF reading copy, or the supplied Markdown source
  paper.toml     title, authors, licences and the Lean modules to read
  lean/          the authors' Lean project, unchanged
  links.json     which passage goes with which declaration, plain titles, notes and comparisons
  checks/        optional Lean files of ours that test a statement against the authors' Lean
  comparator/    optional files of a Comparator run: challenge, solution, configuration, receipt
  generated/     recorded declaration data and its provenance, plus any compiled checks

The add-paper guide gives the PDF procedure for a person or an AI assistant. For a Markdown source, set [paper] markdown in paper.toml; links.json identifies exact unique quotations with a heading and block anchor. Source-read declarations must be labelled as such. Comparisons may be held with fidelity_held, in which case the page does not present them. The [reading.companions] table maps relative Markdown paths to other reader editions, for example "../companion/paper.md" = "companion". Links to those paths open the companion, and a heading fragment opens the corresponding section.

For a Markdown-source figure, put the image in the same paper folder (or a child folder) and refer to it with a relative Markdown image such as ![A proof map](proof-map.png). paper.py check rejects missing images and paths that leave the paper folder. paper.py build copies referenced images into web/public/papers/<slug>/ beside the reading HTML and records each image's SHA-256 in edition.json under source.images. Rebuild the paper and then the website after changing an image. An editable SVG can remain beside a PNG used by the Markdown and PDF renderer.

The PDF commands are:

python3 tools/paper.py new my-paper       # then add the PDF, Lean and paper.toml
python3 tools/paper.py extract my-paper   # build the Lean, list its declarations, compile checks/
python3 tools/transcribe.py my-paper      # draft paper.md from the PDF's structure
# define a result under claims in links.json, with its passage and Lean declaration
python3 tools/paper.py check my-paper     # compare the text and check the links
python3 tools/paper.py build              # write the data the site reads

extract needs elan, the Lean installer, and uses the Lean version specified by the paper's authors. check and build need Python 3.11 and Poppler, and, for a paper with a paper.md, Node with npm ci run in web/. transcribe.py also needs pypdf. The authors' code runs on your machine, so read a project you do not trust before extracting it.

What paper.py check establishes

For a PDF, the command compares the reading copy with extracted text. It skips the top 7.5% and bottom 5.5% of each page, repeated headers and footers, bullet marks, and words inside figure crops. The figures themselves are copied from the PDF.

It treats some typographic differences as equivalent, such as ligatures and line-break hyphens, and allows text blocks to move. These allowances can also let changes in word or character order pass. The check helps find transcription errors; a pass does not certify an exact copy. Review the reading copy alongside the original PDF.

For Markdown, it checks exact source quotations and heading/block anchors; it does not compare against a PDF. For both source types, it confirms that every quotation appears exactly once, that exact Lean lines lie inside their declaration and that every Lean name exists. No program confirms that a sentence is about the code it is linked to: a person has to read both. Names printed in the paper are linked by matching the name alone, so STLC in the paper's Haskell opens the Lean STLC. Lean reports what a proof depends on, and does not report whether a Lean statement means what the paper says.

When comparisons are provided, each claimed result and relevant author axiom carries a comparison: the Lean says the same as the paper, more, less, or something different. check stops if one is missing unless comparisons are explicitly held for the page. A comparison is AI judgement. Where it cites a check, the check is a Lean file of ours under papers/<slug>/checks/, compiled by extract against the authors' Lean, with the axioms Lean reports for it. check stops if a check file has changed since extract compiled it. Each page says that the links, notes and comparisons have not been reviewed by the authors, until an author has reviewed them.

A paper can show a Comparator run. Name the folder holding the run's files under [comparator] evidence in paper.toml; pages that show the same Lean name one shared folder, such as "../pcp-full-argument/comparator". The folder holds Challenge.lean, Solution.lean, the configuration, the rejected control and a receipt.json recording the run. The build reads each configured theorem's statement from Challenge.lean, with its lines, and links the files at the commit it builds. It stops if a file's SHA-256 differs from the receipt, if the challenge states no theorem of a configured name, or if the receipt does not record an accepted run and a rejected control. Each checked declaration then has a closed "Comparator evidence" fold beneath its axiom report. Comparator tests a proof against the challenge statement; it does not test whether that statement means what the paper says.

Repository map

Authored paper files and checked-in declaration records live under papers/. tools/paper.py build turns them into web/public/papers/. The website build command then packages them with the application in web/dist/. Both output directories are ignored by Git: change their sources and rebuild them.

Source What it holds
papers/ One folder for each paper
skills/add-paper/ How to fill in a new paper
tools/paper.py Extract the Lean, compare with the PDF and build the data
tools/transcribe.py Draft a paper's reading text from its PDF
tools/reading.py Compare the reading copy with the PDF and mark its linked statements
render-paper.mjs Typeset paper.md with Markdown and KaTeX
extract.lean.template The Lean program that lists a project's declarations
web/ The website
web/src/map/ The map, copied from lean-exposition
history.ts Saved reading position and open statements for the Back button
web/src/lean/ Code for displaying and colouring Lean source
web/src/proof/ The proof diagram and Lean panel beside the paper
check-source.mjs Find source files that the application and tools do not use; run with npm run check:source in web/
tests/ Python unit tests and the browser journey
Pages workflow Check every paper, build the site and publish to GitHub Pages

Related work and videos

Introduction to the projects · Proof Reader short · Full comparison of the three maths readers

Lean Exposition contains writing guides and tools for explaining a Lean proof in three papers with different levels of detail. Its reading website presents those draft explanations beside the graph; this video walks through that site. For PDF papers, Proof Reader's reading copy keeps the original paper's wording.

Licence

Code is Apache-2.0; see LICENSE and NOTICE. Each paper and Lean project keeps its own licence and credit, named in its paper.toml and on its page.

Proof Reader is one of Will Cook's sites. Find the other websites and code on Will's home page, and the project videos.

About

Read a research paper beside its Lean proof code, with links to exact statements and a diagram of how the proof fits together.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages