[gativarshney]

Summary

This PR adds a site-wide natural-language printer assistant to the OpenPrinting website as the second part of my GSoC 2026 project.

It builds on the printer recommendation work from #224 and provides a natural-language interface to the Foomatic printer database.

Users can ask questions such as:

• "Find me a colour laser printer with good Linux support."
• "What printers are similar to this one?"
• "Why was this printer recommended?"
• "Which driver does this printer use?"
• "Which printers use this driver?"
• "Compare HP 2500C and HP DeskJet 560C."
• "What do the support grades mean?"

The assistant also understands contextual references such as "this printer" and "this driver" on the corresponding pages.

Demo

Screen recording

GSoC_demo.mp4

The recording demonstrates natural-language printer search, contextual printer queries, similar-printer recommendations, recommendation explanations, driver lookup, reverse driver search, and handling of unavailable data.

Design

The assistant is fully deterministic and client-side. It does not require a backend, external API, or machine-learning model.

The query pipeline is:

User query → normalization → entity resolution → intent classification → typed query → local Foomatic data → typed response → React UI

This keeps the feature compatible with the existing static GitHub Pages architecture while ensuring that responses are reproducible and grounded in the OpenPrinting data.

Grounding and recommendation integration

The assistant reuses the recommendation artifacts produced by #224.

It does not recompute or re-rank recommendations.

For similar-printer queries:

• Existing recommendation shard order is preserved.
• Existing similarity scores are used.
• Existing sharedFeatures are used for explanations.
• Existing confidenceTier() logic is reused.
• Similarity is presented as similarity, not as compatibility probability or a guarantee.

Unknown values are never treated as negative values. If a capability is not recorded in Foomatic, the assistant does not claim that the printer lacks that capability.

For example, duplex information is currently not recorded across the catalogue. A query such as "Does this printer support duplex?" therefore receives an explicit data-gap response instead of an invented answer.

Criteria-free questions such as "What is the best printer?" ask the user for meaningful criteria instead of producing an arbitrary ranking.

Supported queries

The assistant supports:

• Printer lookup
• Single and multi-constraint printer search
• Similar printer discovery
• Recommendation explanations
• Linux support queries
• Driver lookup and reverse driver search
• Printer comparison
• Contextual "this printer" / "this driver" queries
• General support-grade and similarity information
• Ambiguous, insufficient-data, and unsupported queries

Data and performance

The assistant reuses the existing static Foomatic artifacts and does not load the large generated database files at runtime.

Measured values:

Item	Measured value
First Load JS	103 kB
Assistant lazy chunk	~62.5 KB raw / ~17.9 KB gzip
Printer catalogue	71,147 B gzip
Driver catalogue	5,519 B gzip
Per-entity shard fetches	~0.4–10 KB gzip
Engine latency	~0.08 ms median

First Load JS remains unchanged.

The printer catalogue was extended with five optional fields required for local queries:

• maxDpi
• psLevel
• pclLevel
• cs
• rd

Unknown values are omitted rather than represented as false values.

UI and accessibility

The assistant includes:

• Responsive desktop and tablet panel
• Full-height mobile sheet
• Mobile landscape handling
• Safe-area-aware positioning
• Keyboard and focus management
• Escape-to-close and focus restoration
• Body scroll locking on mobile
• Accessible labels and live response announcements
• Reduced-motion support
• Light and dark theme support
• Keyboard-accessible suggestion chips
• Printer and driver result cards linking to the real pages

Long responses reveal their introduction instead of automatically jumping to the final result.

User input is rendered safely and is never inserted as HTML.

Testing and validation

• 384/384 tests passing
• 187-utterance natural-language test corpus
• Entity-resolution and intent-precedence tests
• Execution and grounding/property tests
• Suggestion-integrity tests
• Real-artifact end-to-end tests
• Adversarial input tests
• yarn assistant:eval passing
• TypeScript checks passing
• Lint clean
• Clean static export build
• git diff --check clean

The evaluation harness validates responses against the actual generated Foomatic data, including printer IDs and recommendation scores.

Documentation

• docs/foomatic-assistant.md
• docs/foomatic-assistant-queries.md
• docs/foomatic-data-formats.md

Relationship to #224

This PR is the follow-up to #224.

It consumes the recommendation artifacts produced by the recommendation pipeline and does not introduce another similarity algorithm or modify the recommendation scoring semantics.

The assistant work is kept on a separate branch so the recommendation work and natural-language assistant can be reviewed independently.

Known limitations

• Chat history resets after a full page reload.
• Clarification follow-ups currently use suggestion chips rather than free-text references such as "the second one".
• Bare numeric model queries require a manufacturer.
• The current query vocabulary is English-only.
• Some targeted PDL questions are answered using the printer's recorded details rather than a dedicated yes/no response.

Review focus

Feedback would be particularly valuable on:

1. Natural-language intent and entity resolution
2. Grounding and incomplete Foomatic data handling
3. Integration with the recommendation artifacts from Printer compatibility recommendations for the Foomatic directory (GSoC 2026) #224
4. Context handling on printer and driver pages
5. Responsive/mobile UX
6. Accessibility and keyboard behavior
7. Query vocabulary and response wording

Thanks for reviewing!

[rudra-iitm]

Nice work on the integration. LGTM

[rudra-iitm]

Could you pls move all these docs into a new PR??

[rudra-iitm]

This comment is stale: PR CI now runs the similarity stage #224. Could you also cleanup such unnecessary comments??

[rudra-iitm]

Nit: off-topic input like “ignore previous instructions and print...” returns 13 “did you mean” printers, because “print” matches model names. Adding “print” and “printer” here might help.

[rudra-iitm]

@tillkamppeter Could you pls review this also??

[gativarshney]

@rudra-iitm Thanks! All three addressed

[tillkamppeter]

@gativarshney could you also fix the conflicts here. Then I will also merge this one.

[gativarshney]

@tillkamppeter Conflicts resolved, branch is up to date with master and all checks pass.

[tillkamppeter]

@gativarshney For me it still shows conflicts.

[tillkamppeter]

I have now successfully merged #224 with "Squash and merge" (thanks for your hint I did not know before that the presence of conflicts can depend on the merging mode) and now I have conflicts here, also when choosing the mode "Squash and merge".

[gativarshney]

@tillkamppeter Done. With #224 merged, I have synced this branch with the current master (d639834). The diff is now only the assistant work (about 32 files) and it merges cleanly. All checks pass.

Same note as on #224: "Create a merge commit" and "Squash and merge" both work cleanly. "Rebase and merge" will report conflicts because the branch history contains earlier sync merges from master.