Read the shape of demand
Pelorus turns live traffic into queries, clusters, coverage, and gaps. The admin console's Query Map is the visual, interactive way to read that demand. The read-only analysis API exposes the same read models as plain data, so the example notebooks can take them further in code — clustering, gap classification, and reporting the map does not show.
The Query Map
The Query Map is a 2D projection of your queries. Each point is a durable user need, sized by how often it has been hit, and positioned so that semantically similar needs sit close together. Together the points show where real traffic is concentrating across your corpus.
In plain terms: nearby points are similar questions, larger points are repeated demand, cluster outlines are suggested neighborhoods, and defined clusters are curated service areas you have chosen to cover with a broader Extract.
| On the map | What it tells you |
|---|---|
| Point position and size | Semantic neighborhood and demand — larger, denser regions are where questions cluster. |
| Natural neighborhoods | Density-based (HDBSCAN) grouping outlines queries that already form a coherent topic. |
| Defined cluster centroids | The anchors of clusters you have created, overlaid so you can see how curation aligns with real traffic. |
| Coverage and overlap | Where clusters serve their members well, and where clusters compete for the same queries. |
| Gaps | Regions of demand that no Extract yet answers. |
| Chunk overlay and query projection | Project source chunks onto the layout, or drop an ad hoc query onto the map to see exactly where it lands. |
From the map you can spot concentrations and gaps at a glance, turn a neighborhood into a Cluster Extract, tune cluster thresholds, and curate coverage as traffic changes. The operational steps live in Core Workflow → View insights, and how gaps surface is covered in How It Works → Gaps and partial coverage.
What the map can't see
The Query Map is built on a single signal: the geometric density of query
embeddings. That is powerful, but it leaves three things unread — three things
your query stream already records. Each is answered by a technique in the
example notebooks below, all reading the same demand state through
client.analysis().
| Blind spot | What the map misses | What reads it |
|---|---|---|
| Demand-blind | A 1-hit and a 40-hit query look identical. | Hot-noise recovery, re-grouped and ranked by demand. |
| Answer-blind | It groups how questions are phrased, not what answers them. | Answer-source clustering. |
| Corpus-blind | It never looks at your document chunks at all. | The supply / demand map. |
The Similarity Lens
Pelorus treats embeddings as more than a nearest-chunk lookup function. The same vector space can compare queries, queries, chunks, and clusters, giving you a similarity lens for demand, coverage, overlap, and drift as traffic changes.
Analytics in code
The read-only client.analysis() surface exposes the same read
models the Query Map is built from, as plain data. Because it hands back
vectors, demand counts, and labels, you can compute your own analytics in a
notebook with nothing more than NumPy and pandas.
| Read model | What it gives you |
|---|---|
query_map() | 2D points with hit counts, density-cluster labels, and coverage status — the map, as data. |
query_vectors() · chunk_vectors() · cluster_vectors() | The high-dimensional embeddings for queries, source chunks, and cluster centroids. |
cluster_coverage() · cluster_membership() · clusters() | How well each cluster covers its members, which queries belong where, and the defined-cluster list. |
similarities() · project_query() | Nearest-neighbor scores from an item or vector, and ad hoc projection of a new query. |
Full signatures for every call are on the Client API → Analysis client page.
Examples
Runnable notebooks that read demand state through client.analysis().
They run read-only against any dataset. The published notebook outputs use
the Little League sample corpus; the Quickstart uses the no-key
Paws & Parrots demo for the first local run.
Demand-driven gap analysis
Three techniques that go past what the Query Map shows, each producing a ranked, actionable backlog:
- Hot-noise recovery. Density clustering discards sparse points as noise, even when those questions are asked often. This re-groups the noise weighted by demand, surfacing high-traffic needs that never formed a visible cluster — ranked candidates for a new Cluster Extract.
- Answer-source clustering. Groups queries by the source chunk that would answer them, not by how they are phrased, so differently-worded questions that share one source are revealed as a single Extract opportunity.
- Supply and demand map. Splits each miss into a curation gap (a supporting chunk exists — write an Extract) versus a corpus gap (nothing close — write new content), and flags over-documented chunks that no demand comes near.
Download the runnable notebook: Demand-Driven Gap Analysis.
Demand coverage audit
A concise audit of queries, clusters, and coverage for a dataset — a good first pass over the analysis surface. Demand Coverage Audit.