How it works

lurq's scores are computed from public signals, never hand-written. This page sketches the pipeline from raw data to the answer your agent receives.

Where the evidence comes from

Three kinds, and the distinction is the whole point.

Readable — npm, GitHub, deps.dev, OSV, and bundlephobia, re-synced daily. Downloads, release cadence, maintenance, advisories, deprecations, license, bundle cost. This is what scoring runs on.

Executed — an isolated sandbox that installs a package version, imports it, and records what happened. Co-installing a set is how compatibility is established: a successful co-install is positive proof two versions coexist, a failure is proof they conflict, and the error is kept as evidence.

Extracted — the shipped .d.ts and the shipped JavaScript of an exact version, parsed deterministically. No model is involved anywhere in this path. This is what usage, resolve_surface, and diff_surface answer from, and it's the only way to know that the function your agent is about to call was removed two majors ago.

Facts of the second and third kind appear in no changelog and no model's training data, and they go stale unless someone keeps re-running the experiment.

The pipeline

public APIs (npm, github, deps.dev, osv, bundlephobia)
  → ingestion
  → scoring (health + quality + field evidence + confidence)
  → summaries / usage guides
  → embeddings
  → postgres + pgvector  (hybrid lexical + semantic search)
  → { stdio MCP server, HTTP MCP service, CLI }

npm tarballs / CDN .d.ts → surface extraction → api surfaces + symbol diffs
sandbox co-install       → compatibility edges

Each stage is idempotent and tolerant of a single source being down, so a flaky upstream API degrades one signal rather than failing the whole index.

Scoring axes

A package's composite score blends two axes:

• Health: signals like maintenance cadence, adoption, reliability, and efficiency, drawn from release history, issue activity, dependents, and bundle size.
• Quality: a complementary axis so a brand-new but well-built package isn't penalized purely for being young.

The two are combined with a tunable weight (composite.lambda). You can inspect the model with lurq weights and adjust it locally with lurq edit-weights, see the CLI reference.

Confidence

Confidence labels (proven, emerging, promising, unproven) reflect the strength of the discovered evidence, not popularity alone. This matters for newer dependencies: a package can be young and lightly used yet still be a sound choice, and lurq surfaces it with an honest confidence label rather than hiding it.

Search

Retrieval is hybrid: two independent searches run over the same candidate set — lexical matching (Postgres full-text) for exact names and keywords, and semantic vector search via pgvector for intent-based queries like "debounce a function." This catches both "I know the name" and "I know what I want it to do."

The two are merged with Reciprocal Rank Fusion, which combines them using only each result's position in its list. That's deliberate: it means two incomparable scoring scales never have to be normalised against each other, and an exact-name hit the vector search ranks poorly still surfaces. The fused relevance is then blended with the composite score, so results are both relevant and good.

No model sits in the ranking path. That's why answers are fast, cheap, and the same for the same question.

Freshness

The index is refreshed on a schedule, and a package nobody has asked about yet is fetched and scored the first time someone does. Every response includes a dataAsOf timestamp so your agent can reason about how current the evidence is. (Self-hosters run the refresh themselves, see Self-hosting.)