ITheEqualizer/british-library-book-image-type-router

British Library Book Image Type Router v1.0.0

British Library Book Image Type Router is a compact four-class linear model for digital-library ingestion. It maps one pinned 1,152-dimensional SigLIP2 image embedding to covers, plates, medium, or embellishments.

Maintainer: Ali Zakaee (ITheEqualizer).

Intended decision and audience

The named consumer is a digital-library ingestion or indexing pipeline that must repeatedly decide whether an extracted historical-book image belongs in a cover display, a full-page plate index, a medium illustration workflow, or an embellishment workflow. The output is advisory metadata. It is not an art-historical judgment, a content-safety score, or authorization to discard an image.

Representative decisions:

• A front-cover embedding should route to covers for catalogue display.
• A full-page illustration should route to plates.
• A smaller illustration should route to medium.
• A decorative initial, border, or ornament should route to embellishments, not covers.

Tested quickstart

The included example uses an actual validation embedding from the pinned public dataset and exercises checksum verification, shape checks, secure skops loading, and prediction.

python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python predict_embedding.py example_embedding.npy

The expected label is recorded in example.json. Inputs must be finite float32 arrays with shape (1152,), produced by google/siglip2-so400m-patch16-256 at revision e8708ab72d125807e45b36fb7d4e0aacbb59f379 using the dataset's 256×256 preprocessing. Embeddings from another encoder, revision, pooling method, or preprocessing pipeline are out of contract.

Data, rights, and leakage controls

Training used revision c288990ce59b055e7bf9411f663d0f672ae16102 of biglam/british-library-book-images. The source images were released by the British Library on Flickr Commons with a Public Domain Mark; the mirror uses CC0 metadata. The embedding encoder is Apache-2.0 licensed. This learned linear artifact and its code are MIT licensed. See THIRD_PARTY_NOTICES.md.

One pinned 25,000-row embedding shard from each class was audited. All four file hashes are in model_manifest.json. Complete exact-feature duplicate sets were removed before splitting: 703 rows in 257 sets, with zero cross-label duplicate sets. The remaining 99,297 rows cover 18,645 book IDs. Splits were assigned by British Library system number: 70% train, 15% validation, and 15% untouched lockbox. No book ID crossed splits. Filename-normalized duplicate checks found no cross-book group.

The four labels are inherited algorithmic size-and-position heuristics, not curatorial labels. The bounded first-shard sample may retain ordering and publication-date bias and is not evidence for the full 1.08-million-image distribution.

Model and selection

The model is a training-only StandardScaler followed by an averaged SGDClassifier with logistic loss, balanced class weights, L2 regularization (alpha=1e-5), seed 20260809, and a fixed 200-epoch budget. This approach was chosen because it fits the already-computed semantic embeddings, stays below 100 KB, and can be securely serialized with skops. A nearest-centroid classifier over normalized embeddings was the strongest feasible compact baseline.

Architecture and hyperparameters were fixed before fitting. Validation alone selected a maximum-probability review threshold targeting at least 0.80 routed accuracy. The selected threshold is 0.25; it covered every validation example, so it is not a useful abstention policy by itself. Integrators should tune a review policy on their own representative validation data without using the published lockbox as selection data.

Measured results

Evaluation	Accuracy	Macro-F1	Worst-class recall	ECE
Validation	0.8167	0.8363	0.7075	0.1494
Untouched book-group lockbox	0.8499	0.8543	0.7612	0.0990
Lockbox nearest centroid	0.7650	0.7760	0.6852	0.4968
Lockbox majority baseline	0.2291	0.0932	0.0000	0.7709

The learned model improves lockbox macro-F1 by 0.0784 over nearest centroids. Book-group bootstrap 95% intervals are 0.8332–0.8697 for accuracy and 0.8392–0.8665 for macro-F1.

Lockbox confusion counts, rows=true and columns=predicted in label order covers, plates, medium, embellishments:

[[3573,    3,    0,    0],
 [ 130, 3087,  536,    5],
 [ 126,  736, 3292,  171],
 [  36,    6,  594, 3314]]

In plain language, the most consequential errors are the fuzzy source boundary between plates and medium: 736 medium images were routed as plates and 536 plates as medium. Another 594 embellishments were routed as medium. covers recall was 3,573/3,576, but 292 non-covers were falsely routed as covers. The probabilities are model scores, not calibrated guarantees; lockbox ECE is near the predeclared maximum and validation ECE is worse.

Reproduction

train.py verifies every pinned Parquet SHA-256, applies the exact duplicate and book-group split policy, fits new weights, and can compare every lockbox score, prediction, and label with reproduction_reference.npz:

python -m venv .train-venv
.train-venv/bin/python -m pip install -r requirements-train.txt
.train-venv/bin/python train.py \
  --data-dir /path/to/pinned/shards \
  --output-dir reproduced \
  --reference reproduction_reference.npz

The release was reproduced in a clean environment with exact lockbox scores and predictions. The skops artifact has an empty untrusted-type set.

Limitations and safe integration

• The labels reproduce a historical deposit heuristic; they do not establish subject matter, artistic medium, cultural significance, or truth.
• Late-Victorian material dominates the source corpus. Results may shift for earlier books, other libraries, born-digital documents, or modern covers.
• Historical and colonial-era imagery may be offensive; this classifier neither detects nor mitigates that content.
• SigLIP2 preprocessing or pooling drift invalidates the feature contract.
• Automatic deletion, suppression, or access control should not depend on this model alone. Keep source metadata and send uncertain or high-impact cases to human review.

Rollback is simple: remove the classifier from the routing path and restore the existing metadata or manual-review workflow. Verify model.skops against the SHA-256 in config.json before loading it, and load only with trusted=[].