Printer compatibility recommendations for the Foomatic directory (GSoC 2026)

[gativarshney]

Summary

This PR adds a printer recommendation feature to the Foomatic printer directory. Every printer page now shows up to three similar printers, each with an explanation of why it was suggested, a confidence tier, and expanded capability information. A compact teaser next to the "Recommended driver" card in the page header makes the feature discoverable without scrolling; it links down to the full section.

Everything is generated offline at build time. There is no backend, no external API, and no data leaves the static site. This is an engineered similarity pipeline, not a trained model, which is what keeps every recommendation fully explainable.

Screenshots

Printer page

The compact teaser makes similar printers discoverable directly from the printer header, while the full section provides the detailed recommendations.

Similar printer recommendations

Each recommendation shows the similarity score, evidence tier, Linux support grade, and reasons for the recommendation.

Implementation

The pipeline runs as part of yarn generate:

1. foomatic-db XML is parsed and normalized into printer records (6,657 printers).
2. Each printer is encoded as a 463-dimension feature vector: driver families, command sets, PostScript/PCL levels, colour, mechanism type, resolution tiers, and support grade.
3. Candidates are ranked by IDF-weighted cosine similarity. IDF weighting means sharing a rare driver (necp6, 8 printers) counts for much more than sharing postscript (1,746 printers).
4. The cosine score is damped by how much evidence the pair actually shares, so two printers with mostly unknown data can no longer score as a perfect match, and is multiplied by penalties for capability conflicts (type, colour, extreme resolution gaps).
5. Results below a minimum score are dropped, the top 10 are kept with deterministic score-then-id ordering, and human-readable explanations are generated from the shared attributes.

Output is one small JSON shard per printer (median 3.3 KB). A printer page fetches its own printer record and recommendation shard, about 6 KB of JSON in total; the browser never downloads the 24 MB aggregate file or the full printer index. The teaser and the full section share a single request.

The UI presents scores as "N% similarity" under four evidence-aligned tiers (High confidence, Good match, Moderate match, Limited evidence). The score is a similarity value, not a probability and not a compatibility guarantee, and the wording avoids implying either. Each card also labels the candidate's own Foomatic grade as "Linux support:" so it cannot be confused with the similarity result.

Supporting work included in this PR:

• DOMPurify sanitization for upstream HTML (printer notes, driver comments), preserving trusted Snapcraft Printer Application embeds while rejecting untrusted iframe content
• Fix for the directory colour filter, which previously string-matched model names and found 122 of the 3,202 colour printers
• 87 unit tests, run in CI on every PR
• Reproducible evaluation harness under tools/eval/
• The generation pipeline also runs on Windows for local development (PPD compilation remains Linux-only)
• Five documents under docs/ covering architecture, data formats, regeneration, UI extension, and measured recommendation quality

CI note: PR builds skip similarity generation for speed (FOOMATIC_SKIP_SIMILARITY=1); the site builds and renders correctly without the artifacts. Deploy builds run the full pipeline, and a weekly cron regenerates recommendations as upstream foomatic-db changes. Please confirm the scheduled deploy is acceptable policy for this repository.

Validation

yarn foomatic:eval recomputes the dataset metrics below from the generated artifacts and fails if any documented constant drifts from the source. Numbers reflect the current foomatic-db snapshot and are regenerated with the data.

• 0% of displayed scores saturate at 1.0 (86.8% before the scoring corrections; the evolution is documented in docs/foomatic-recommendation-quality.md)
• 0.849 correlation between shared evidence and score (0.078 before, when weakly supported pairs actually outscored strongly supported ones)
• 0 untrue explanation strings out of 136,827 validated against the source data
• Type contradictions 0%, colour contradictions 0.2%, 4x resolution gaps 0.04%
• All 1,803 recommendations supported only by a generic driver fall in the lowest tier
• Artifacts are byte-identical across independent builds

node tools/eval/pairs.mjs prints real recommendation pairs with full source and target capabilities next to the explanation shown to users, for manual inspection.

Limitations

These are documented in detail in docs/foomatic-recommendation-quality.md:

• There is no human-labelled ground truth. The evaluation measures internal consistency, truthfulness of explanations, and discriminative behaviour; it does not establish human-validated relevance. A small hand-labelled pair set would be the most valuable follow-up.
• Only 1,096 distinct feature vectors exist across 6,657 printers. Many printers genuinely cannot be distinguished with the data Foomatic records; ties are ordered deterministically by id for reproducibility, not to suggest a ranking the data cannot support.
• 71 printers (1.07%) receive no recommendations because no candidate clears the evidence floor. The UI shows an explicit empty state.
• About 27% of printers ever appear as recommendations; driver-family clustering concentrates exposure.
• Many recommendations are same-manufacturer or rebadged models (the Ricoh badge family in particular). These are correct for driver compatibility but of limited value as alternatives; roughly 22% of recommendations cross to a genuinely different vendor.
• Generation is O(n²) over all printer pairs, roughly a minute on a typical development machine. Fine at this scale, but worth revisiting if the database grows substantially.

Follow-up

A local natural-language assistant for the printer directory (queries like "colour laser printer with duplex for Linux") is planned as a separate branch built on the artifacts this PR produces. It is intentionally not part of this PR.