ibteda.pt: the deployed geometry model, with its card

README.md

@@ -45,148 +45,204 @@ audit regenerates this card and fails on any difference. -->
 
 # PageImprover Geometry Model
 
-A ResNet-34 regression model that predicts the two page crops of a photographed two-page spread. It is the first of
-three stages: the model proposes the crops, a per-book calibration of five spreads corrects them to the book's own
-margins, and a review queue sends the least trustworthy page sides to a person. It was trained and measured on one
-archive's books and is built to be pointed at anyone's; the calibration is what carries it to a book it has never
-seen. On its own it does not produce a finished page, and the figures below only mean anything as a trio.
+PageImprover is a ResNet-34 regression model that takes one photograph of an open book and returns the crop
+rectangles of its two pages, built to run inside a calibrate-and-review workflow on printed books.
 
-<img src="https://ibteda.org/journey/assets/full/bahar-correspondence-spread.jpg" width="480"
-     alt="A photographed two-page spread from the Ibteda archive on a dark table, with the two page crops drawn on it">
-
-*One photograph, two page crops: a spread as the model sees it.*
-
-Every performance number here is a row in [`docs/claims.md`](https://github.com/ibteda-org/pageimprover/blob/main/docs/claims.md), which names the cohort, the
-calibration state and the evidence behind it. A build gate refuses any figure that drifts from that ledger.
-
-## What it takes as input
-
-| | works | does not work |
-|---|---|---|
-| Capture | one photograph per spread, both facing pages in the frame | one page per photograph: the model predicts two crops per image and has nothing to predict on a single leaf |
-| Material | printed books | handwritten manuscripts, a documented blind spot: 0.0727<!--claim:manuscript_blindspot--> calibrated pass@80 |
-| Framing | the paper filling most of the frame, roughly centred, as in the training captures | a small paper block in a wide surround, which the release measures and reports but does not correct |
-| Image size and format | any size; the package letterboxes the image to the model's 704<!--claim:model_input--> px tile itself; JPEG, PNG, TIFF and WebP | |
+- **Model:** `ibteda.pt`, a TorchScript archive that carries its own preprocessing contract
+- **Input:** one photograph with both facing pages in frame, any size or format
+- **Output:** a left and a right page rectangle, from a direct pass and a flipped pass
+- **Trained on:** printed books from the Ibteda corpus
+- **Metric:** pass@80, scored per page side
+- **Needed to be useful:** a per-book calibration and a review step; the model is stage one of three
 
-Closed covers are recognised by the framing check and cropped from the detected paper block as single pages; the
-model is not asked about them.
-
-## Getting the model
+<img src="https://ibteda.org/journey/assets/full/bahar-correspondence-spread.jpg" width="480"
+     alt="A photographed spread from the Ibteda archive on a dark table, with the operators' finished page crops projected back onto it">
 
-Install `pageimprover` and run `pageimprover fetch model`. It downloads `ibteda.pt`, checks the bytes against the
-pinned digest and refuses any others. Nothing downloads on its own, and the model is loaded only through the
-package: it is a TorchScript archive carrying its own preprocessing contract, not a state dict.
+*One photograph, two page crops. The rectangles are the operators' finished pages projected back onto the spread:
+the target the model is trained to reproduce.*
 
-The pinned artifact is `ibteda.pt`, SHA-256 `359ae48b6a846e01d70a21c2c49426125f3b8950ae7b4736ba8cf954af60babe`. The code, its tests and the claim ledger every figure here is rendered from are at <https://github.com/ibteda-org/pageimprover>.
+Every figure in this card is a row in [`docs/claims.md`](https://github.com/ibteda-org/pageimprover/blob/main/docs/claims.md), which names its cohort, calibration state
+and evidence. A build gate rejects any figure that drifts from that ledger.
 
-## How the three stages work
+## Quick start
 
-**1. The model.** Given one spread, it predicts the left and right page rectangles as a single fixed-length
-vector. Geometric regression, not detection: no anchors, no proposals, no class labels. The 704 px input was chosen
-to fit a T4's memory, not for accuracy, and has never been tuned against the acceptance bar; a larger input is an
-untested lever, not a rejected one.
+```sh
+git clone https://github.com/ibteda-org/pageimprover && cd pageimprover
+uv sync --extra inference            # the app and the model runtime; no GPU needed
+uv run pageimprover fetch model      # downloads ibteda.pt and checks its digest; nothing else ever downloads
+uv run pageimprover sample           # a public book to try it on, or: add NAME FOLDER for your own photographs
+uv run pageimprover studio           # process, calibrate, review and export in the browser
+```
 
-A prediction is scored by its **worst corner**. A page side passes when the worst of its four corners lands within
-80<!--claim:pass_bar--> px of the operator's crop, measured in the fixed 2048×2897 finishing frame. This is
-`metrics.PASS_PX`, a geometry rule and nothing more: not an OCR score, not an aesthetic judgement, and not
-"accuracy" in any sense a reader should generalise.
+From Python, with the `inference` extra installed:
 
-**2. Per-book calibration.** The dominant residual is a per-book size constant: the margins a book was finished at
-leave no trace in a single image, so no model recovers them at any capacity. Ten operator crops do. Five spreads
-(k=5<!--claim:k_default-->), both sides, 10<!--claim:cal_crops--> crops per book, pooled into one offset
-(`calibrate/pooled_median.py`). The offset is applied only when its magnitude reaches 40<!--claim:cal_gate-->
-canonical px (`refusals.CALIBRATION_GATE_PX`); below that it is indistinguishable from an operator's own
-self-consistency and can only add noise.
+```python
+import cv2
+from pageimprover import model
 
-Two design choices are recorded as costs, not victories. Pooled, not per-side: splitting the same ten crops by page
-side harmed 8<!--claim:cal_harm_perside--> held-out books; pooling them harmed 2<!--claim:cal_harm_pooled-->, same
-crops, estimator the only difference. Five spreads, not seven: seven beat five by +0.0104<!--claim:k7_delta-->
-pass@80, decisively (p<0.0001), and was declined because at corpus scale that point costs thousands of extra
-operator pages.
+geometry = model.load()                                   # the verified ibteda.pt, refused if the digest differs
+prediction = geometry.predict(cv2.imread("spread.jpg"))   # any size; letterboxed to the model's tile internally
+left, right = prediction.side("left"), prediction.side("right")   # each has .direct and .mirrored rectangles
+```
 
-**3. Review routing.** A flip-consistency check runs the model on the spread and on its horizontally flipped copy
-and flags a side when the two disagree by more than 87<!--claim:route_threshold--> canonical px
-(`review.absolute`). Those sides go to a person; the rest ship.
+## Input and output
 
-## Measured performance
+| | works | does not work |
+|---|---|---|
+| Capture | one photograph per spread, both facing pages in frame | one page per photograph: the model predicts two crops and has nothing to predict on a single leaf |
+| Material | printed books | handwritten manuscripts: 0.0727<!--claim:manuscript_blindspot--> calibrated pass@80, a documented blind spot |
+| Framing | the paper filling most of the frame, roughly centred, as in the training captures | a small paper block in a wide surround; the release measures framing but does not correct it, so crop upstream |
+| Image | any size; the package letterboxes it to the model's 704<!--claim:model_input--> px tile | |
+| Format | JPEG, PNG, TIFF, WebP | |
+
+The contract, as the artifact itself declares it:
+
+```text
+photograph  →  1500×1000 working tile, letterboxed to 704×704
+            →  24 numbers: for each of {left, right} × {direct pass, flipped pass},
+               centre x, centre y, log width, log height, sin θ, cos θ
+            →  two page rectangles in the photograph's own pixels
+```
+
+Closed covers are recognised by the framing check and cropped from the detected paper block as single pages. The
+model is not asked about them.
 
-Two held-out cohorts, both inside the training archive. "Sealed" is a 54-book sensitivity test held back from every
-design decision; "confirmation" is a 192-book cohort unexposed during development. All figures are pass@80.
+## The three stages
+
+```text
+photographed spread
+        │
+        ▼
+1. geometry model          proposes the two page crops
+        │
+        ▼
+2. per-book calibration    five spreads, ten operator crops, one pooled offset
+        │
+        ▼
+3. review routing          the least trustworthy page sides go to a person
+        │
+        ▼
+finished page crops
+```
+
+**1. The model** predicts the left and right page rectangles as one fixed-length vector. Geometric regression, not
+detection: no anchors, no proposals, no class labels. Its 704 px input was chosen to fit a T4's memory, not for
+accuracy, and has never been tuned against the acceptance bar.
+
+**2. Calibration** corrects the one thing no photograph shows: how tightly this book's pages were finished. The
+tool picks five spreads spanning the book, skipping the front matter, and shows them one at a time. On each you
+adjust the left and right page crops. That is 10<!--claim:cal_crops--> crops from k=5<!--claim:k_default-->
+spreads, pooled into a single offset for the whole book (`calibrate/pooled_median.py`). The offset is applied only
+when it reaches 40<!--claim:cal_gate--> canonical px (`refusals.CALIBRATION_GATE_PX`); a smaller one is within an
+operator's own self-consistency and is not applied.
+
+**3. Review** runs the model on the spread and on a horizontally flipped copy. A page side whose two answers
+disagree by more than 87<!--claim:route_threshold--> canonical px (`review.absolute`) goes to a person; the rest
+ship. The disagreement is a routing signal, not a page error.
+
+## Performance
+
+pass@80: a page side passes when the worst of its four corners lands within 80<!--claim:pass_bar--> px of the
+operator's crop in the fixed 2048×2897 finishing frame (`metrics.PASS_PX`). A geometry rule only: not OCR accuracy,
+not aesthetics, not "accuracy" in any general sense.
+
+Two held-out cohorts inside the training archive, measured over **page sides**. Sealed: 54 books, 1,626 sides,
+held back from every design decision. Confirmation: 192 books, 5,636 sides, unexposed during development.
 
 | stage | sealed cohort | confirmation cohort |
 |---|---|---|
 | model alone | 0.6770<!--claim:geo_raw_sealed--> | — |
 | + per-book calibration | 0.8278<!--claim:route_sealed_baseline--> | 0.8334<!--claim:route_conf_baseline--> |
-| + review of the routed sides | 0.9151<!--claim:route_sealed_routed--> | 0.9248<!--claim:route_conf_routed-->, with 28.5%<!--claim:route_conf_share--> of page sides sent to a person |
+| + review of the routed sides | 0.9151<!--claim:route_sealed_routed--> | 0.9248<!--claim:route_conf_routed-->, with 28.5%<!--claim:route_conf_share--> of sides reviewed |
 
-The calibration gain was measured on its own, larger confirmation cohort: held-out pass@80 rose from
-0.7107<!--claim:cal_baseline--> uncalibrated to 0.8271<!--claim:cal_pooled--> with the single pooled offset, a gain
-bought with five spreads of operator work per book.
-
-The review share is an in-archive operating point, not a portable promise; a different collection's distribution
-moves it. Reaching a higher 0.930 target under a coverage *sweep*, which is explicitly not the deployed rule, needs
-34.5%<!--claim:route_sweep_930_sealed--> review on sealed and 30.5%<!--claim:route_sweep_930_conf--> on
-confirmation. A sweep point and the deployed point answer different questions, and the two were once mixed to
-produce a claim that had to be withdrawn.
+The review share is an operating point inside one archive, not a portable promise.
 
 ## Using it on another collection
 
 The model works on printed-book spreads from other scanning setups, on three conditions.
 
-- **Calibrate every book.** Five spreads, ten crops, as above. This is not optional away from the training archive:
-  the calibration is what adapts the model to a binding and a finishing convention it has never seen. On a public
-  seventeenth-century atlas photographed by another collection, the model located the text block on every spread
-  and the remaining error was one consistent margin offset, exactly what the ten crops remove. That run is a worked
-  example, not a measurement: no accuracy figure is claimed for other collections, and any figure you need must be
-  measured against a local operator's crops.
-- **Frame the paper as the training captures did.** The paper should fill most of the frame, roughly centred. The
-  release measures the framing of every frame and reports it, but applies no correction, so a capture with a wide
-  surround needs cropping upstream. Whether letterboxing or centring is better for a frame with no surround is
-  unmeasured.
-- **Do not carry the review numbers across.** The disagreement score's level does not transfer, its ordering was
-  found not to either, and the deployed threshold and review share describe one archive. Read the routed queue as
-  a list of sides to look at, not as a forecast of operator workload.
-
-## Known failure modes
-
-**Handwritten manuscripts.** The deployed model reads printed material well at correct framing and reads
-handwritten pages badly: 0.0727<!--claim:manuscript_blindspot--> calibrated pass@80 on the manuscript sides
-evaluated, with the routing signal actively anti-ranked rather than merely uninformative. A model built to fix this
-was measured and refused: it learned its manuscripts almost perfectly and still failed both foreign reads, so this
-model ships with the blind spot named rather than papered over. Anything quoting this model as adequate for
-manuscript work should quote that number instead.
-
-**The disagreement score away from the archive.** On foreign captures the flip-consistency gap is large, signed
-and material-dependent: it has overstated a small error by more than an order of magnitude on one book and tracked
-a large median on another, and on a fourth book its ranking put the two most nearly perfect sides last.
-`review.score.disagreement_px` is a routing signal, not a page error, and away from the archive it must not be read
-as one in either direction.
+- **Calibrate every book.** Away from the training archive this is not optional: the calibration is what adapts
+  the model to a binding and a finishing convention it has never seen. On a public seventeenth-century atlas
+  photographed by another collection, the model found the text block on every spread and the remaining error was
+  one consistent margin offset, which is what the ten crops remove. A worked example, not a measurement: no
+  accuracy figure is claimed for other collections.
+- **Frame the paper as the training captures did.** Most of the frame, roughly centred. A wide surround needs
+  cropping before inference.
+- **Do not carry the review numbers across.** The disagreement score's level and ordering do not transfer, and
+  the threshold and review share describe one archive. Read the routed queue as sides to look at, not as a
+  workload forecast.
 
-**Framing is never corrected.** The paper block must sit at roughly the training framing before the model has a
-fair chance. The release reports framing; it does not fix it.
+**Do not use it on handwritten manuscripts.** See the evaluation notes.
 
 ## Training data and attribution
 
-The model was trained on completed page crops from the **Ibteda corpus**: books finished by hand by the archive's
-operators, whose crops are the target the model regresses toward. That labour is the ground truth here; the model
-reproduces a finishing convention, it does not invent one. Any use of this model should credit the Ibteda corpus
-and its operators as the source of the training crops.
+Trained on completed page crops from the **Ibteda corpus**: books finished by hand by the archive's operators,
+whose crops are the target. The model reproduces a finishing convention; it does not invent one. Any use should
+credit the Ibteda corpus and its operators as the source of the training crops.
+
+The convention is narrow: 98.7%<!--claim:canvas_share--> of finished pages used one 2048×2897 Photoshop template,
+and the export round-trip reconstructs that historical output to a median residual of
+3.0<!--claim:canvas_residual--> px. Both are facts about one archive's finishing habit, not about the model.
+
+## Evaluation notes
 
-That convention is narrow and measured as such: 98.7%<!--claim:canvas_share--> of finished pages used a single
-2048×2897 Photoshop template, and the export round-trip reconstructs that historical output to a median residual
-of 3.0<!--claim:canvas_residual--> px. The high share is a fact about one archive's finishing habit, not a universal
-page ratio, and the residual describes the convention's reproducibility, not the model's quality.
+Methodological detail behind the figures above. Skip it to use the model; read it before quoting a number.
 
-## Intended use, and what would be misuse
+**Calibration design.** The calibration gain was measured on its own, larger cohort: held-out pass@80 rose from
+0.7107<!--claim:cal_baseline--> uncalibrated to 0.8271<!--claim:cal_pooled--> with the single pooled offset. Two
+choices are recorded as costs, not victories. Pooled, not per-side: splitting the same ten crops by page side
+harmed 8<!--claim:cal_harm_perside--> held-out books; pooling harmed 2<!--claim:cal_harm_pooled-->, same crops,
+estimator the only difference. Five spreads, not seven: seven beat five by +0.0104<!--claim:k7_delta--> pass@80,
+decisively (p<0.0001), and was declined because at corpus scale that point costs thousands of extra operator
+pages.
 
-Intended: locating and cropping page geometry for photographed two-page spreads of printed books, from the archive
-it was trained on or from any other scanning setup, as the first stage of the three-stage loop whose other two
-stages are a person's calibration crops and a person's review of the routed sides.
+**The review sweep, and a withdrawn claim.** Reaching a higher 0.930 target under a coverage *sweep*, which is not
+the deployed rule, needs 34.5%<!--claim:route_sweep_930_sealed--> review on sealed and
+30.5%<!--claim:route_sweep_930_conf--> on confirmation. A sweep point and the deployed point answer different
+questions; the two were once mixed to produce a claim that had to be withdrawn, which is why this card keeps them
+apart.
 
-Misuse: quoting any single number here as "accuracy"; treating the figures as a promise about another collection
-without re-measuring against a local operator's crops; deploying on handwritten manuscript pages; citing a review
-share as portable; or reading the disagreement score as a per-page error. The model does not finish a page on its
-own, and this card exists so that no figure in it is read as a claim that it does.
+**Manuscripts.** The deployed model reads handwritten pages badly: 0.0727<!--claim:manuscript_blindspot-->
+calibrated pass@80 on the manuscript sides evaluated, with the routing signal actively anti-ranked rather than
+merely uninformative. A model built to fix this was measured and refused: it learned its manuscripts almost
+perfectly and still failed both foreign reads. This model ships with the blind spot named rather than papered over.
+
+**The disagreement score away from the archive.** On foreign captures the flip-consistency gap is large, signed
+and material-dependent: it overstated a small error by more than an order of magnitude on one book, tracked a large
+median on another, and on a fourth book ranked the two most nearly perfect sides last.
+`review.score.disagreement_px` must not be read as a page error in either direction.
+
+**Untested levers.** A larger input than 704 px, and letterboxing versus centring for a frame with no surround.
+Both are unmeasured, not rejected.
+
+## Reproducibility and versions
+
+- File: `ibteda.pt`
+- SHA-256: `359ae48b6a846e01d70a21c2c49426125f3b8950ae7b4736ba8cf954af60babe`
+- Pinned by: pageimprover 0.1.0
+- Code, tests and the claim ledger: <https://github.com/ibteda-org/pageimprover>
+- Model identity, from the artifact's embedded contract: ResNet-34 trunk, checkpoint `best_pass80.pt` at epoch 59,
+  704 px letterboxed input built from a 1500×1000 working tile, 24 output numbers as declared above. The package
+  exposes this contract and refuses an artifact whose contract disagrees with the code.
+- Hub revision: pinned in `pageimprover.config.ARTIFACT` inside the package, never in this card, because the
+  revision exists only after the commit that publishes it. `pageimprover fetch model` requests that revision alone.
+- Evidence: [`docs/claims.md`](https://github.com/ibteda-org/pageimprover/blob/main/docs/claims.md) is derived from the research project's evidence ledger, committed
+  2026-09-04 as `1a259aaeeb8d05524695dba7a2a969e395a0e482`, and cites it by commit. The release audit reproduces each
+  value against that commit's retained result files.
+- Public benchmark: `pageimprover fetch benchmark coronelli_1693` from a checkout downloads a twelve-spread
+  seventeenth-century atlas with a digest per frame and reproduces the recorded framing measurements.
+
+## Citation
+
+```bibtex
+@software{pageimprover_2026,
+  title  = {PageImprover: page geometry for photographed book spreads},
+  author = {{Ibteda Digital Library}},
+  year   = {2026},
+  url    = {https://github.com/ibteda-org/pageimprover},
+  note   = {Model artifact ibteda.pt (CC BY 4.0); code Apache-2.0}
+}
+```
 
 ## Licence and authorization