Try it live → (landing
page, demo, and docs, served straight from this repo's main branch)
Attach <query-shaper> to a search input to turn a natural-language query
into something a search backend can actually use.
Instead of sending the raw text straight to your search index, Query Shaper uses the browser's built-in, on-device AI (the kind now shipping in browsers like Chrome) to rewrite what someone typed into better alternatives, mixed freely in one list, never labeled or capped by which of these a given one is:
- Structured queries: boolean/fielded query variants (e.g.
title:"climate change" AND year:[2020 TO 2023]) derived from the natural language input, once you describe your search fields - Typo corrections: likely misspellings caught and corrected before the search runs
- Completions: an unfinished word or phrase finished out, without making the user type the rest
- Query expansions: related terms, synonyms, and alternate phrasings that widen recall without the user having to think of them
The goal is more precise, more efficient searches, without asking users to learn a query syntax, and without sending their queries to a server-side LLM.
Because the language understanding happens on-device via the browser's built-in AI APIs, query interpretation:
- Adds no server-side LLM cost or latency
- Doesn't send the user's raw search input to a third-party inference API
- Works as a progressive enhancement: the search input still works normally in browsers without built-in AI support
Early development, pre-1.0, published to npm as
@internetarchive/query-shaper. The core behavior tracked in SPEC.md is
implemented: Suggestion generation (one Lucene-style string per Suggestion,
decomposed and re-rendered internally; Fields/Examples/Notes drive fielded
reformulation), the lucene/url-params/simple-query-string Formats,
Actions, History, the accessible popup UI, and the demo page. See
CONTEXT.md for the vocabulary and docs/adr/ for the hardest-to-reverse
architectural calls.
npm install @internetarchive/query-shaperimport '@internetarchive/query-shaper'Importing the module is enough: it registers <query-shaper> as a
custom element as a side effect. There's nothing to call to initialize
it.
Requires Node.js and Chrome 138+ (for the built-in LanguageModel API used
at runtime; not required just to build or test).
npm install
npm run dev # serves ./demo against the current source
npm test # run the unit test suite
npm run typecheck
npm run lint
npm run build # emits the npm package + CDN bundle to ./dist
npm run build:site # assembles a deployable copy of the landing/demo/docs pages in ./siteSession lifecycle and generation are logged to the console (timestamped,
prefixed [query-shaper <time>]) whenever the component is loaded via npm run dev: status transitions, session/parent establishment timing, the
Fields/Examples/Notes content primed into a session, the exact prompt text
and raw Suggestions sent/received per query, how each Suggestion parsed,
retries, aborts, and final Suggestion counts. This is dev-only: it's gated
on import.meta.env.DEV, which Vite replaces and tree-shakes away entirely
in npm run build. None of it ships in dist/.
The Dockerfile is multi-stage: dev and build are for local development
and CI; runtime, the default target (what plain docker build . produces),
is the only one meant for an actual deployment.
Dev runs the Vite dev server in watch mode. Bind-mount the repo over
/app so edits on your machine take effect immediately; the extra anonymous
volume on /app/node_modules keeps the image's own install from being
shadowed by whatever (or whatever's missing) in your local node_modules:
docker build --target dev -t query-shaper:dev .
docker run --rm -p 5173:5173 -v "$PWD":/app -v /app/node_modules query-shaper:dev
# -> http://localhost:5173/demo/ (also /docs/, / for the landing page)Prod runs typecheck/lint/test/build:site in an intermediate
stage, then serves the result with nginx as an unprivileged user (no Node in
the final image at all, since query-shaper is entirely client-side):
docker build -t query-shaper .
docker run --rm -p 8080:8080 query-shaper
# -> http://localhost:8080/Query Shaper is licensed under the GNU Affero General Public License v3.0.