Short reference for what each feature means and how the backend reads Chroma. Setup: README.md.
What it is: Your query text is embedded with the same kind of model the backend uses for LangChain (OpenAIEmbeddings), then Chroma returns the k stored rows whose vectors are most similar to that query vector (dense similarity search with scores).
What it is not: There is no keyword/BM25 leg, no fusion with metadata, and no where filter on this endpoint—results are pure vector similarity over the whole collection.
What it is: A Chroma where clause as JSON (metadata predicates). After Apply filter, the Documents table and the 2D projection request both pass this filter into Chroma’s get API so only rows matching the metadata match.
What it does not do: It does not change how Semantic search runs (search ignores this filter today).
In the UI, 2D projection and the embedding space chart are the same thing: a picture of your patterns as vectors.
- One dot = one row in the Chroma collection (for this repo, usually one LP pattern: one
patternId, one stored document, one embedding vector). - The dot is not a pixel on a landing page, not a wireframe box, and not “position on the real website.” It is only a marker in a math chart.
- Each pattern’s embedding is a long list of numbers (hundreds or thousands of dimensions). Humans cannot see that, so the backend runs UMAP or PCA to squeeze that list down to two numbers per pattern:
xandy. - The axes (e.g. −5 … 15) are those synthetic 2D coordinates. They are not labeled things like “hero vs footer” or “Japanese vs English”—unless two patterns happen to land apart by chance. Think of them as “left/right” and “up/down” on a map where the map is built only from vector similarity, not from design tokens you chose.
- The grid is just Plotly’s usual graph paper so you can read positions. It has no extra semantic beyond “this dot is at (x, y) in the projection.”
- Two dots close together → in this 2D view, their high-dimensional embeddings were placed nearby by the reducer. That usually means the embedding model treated those two document strings as somewhat alike (layout/code/card wording in the same ballpark). It is not a guarantee: squeezing many dimensions into two distorts distances, so use the plot as a rough map (clusters, outliers), not as exact ranking.
- Two dots far apart → less alike in this projection, or at least separated by the algorithm’s layout.
- Semantic search ranks patterns against your query and returns a scored list.
- The 2D plot does not use your search box. It only shows how patterns sit relative to each other in a fixed 2D layout for the subset loaded (up to
max_points, optionally after your metadata filter).
- Spot clumps (many similar patterns) vs loners (unusual vectors).
- Click a dot to open that pattern in Selection and read the real document/metadata.
- Optional k-means coloring: split the cloud into k color groups by vector similarity (still not “official” section types—just an automatic grouping).
The backend loads up to max_points rows with their stored embeddings, optionally filtered by metadata, then computes (x, y) per row (UMAP for larger sets, PCA for small ones, a trivial fallback for very few points). It does not re-embed document text for the chart; it uses vectors already in Chroma.
What it is: A paged scan of the collection: Chroma get with limit / offset and optional where. Each row shows id, document text, and metadata. The UI does not pull the whole collection in one request unless you page through it.
Embeddings in this view: The list endpoint can include vectors if requested; the default UI path loads documents + metadata only for the table (lighter payloads).
| Feature | Source | Load pattern |
|---|---|---|
| Collections list | PersistentClient |
Names + count() per collection. |
| Documents | collection.get(...) |
One page (limit/offset), optional where. Not “load entire store” in one call. |
| Semantic search | LangChain Chroma + similarity_search_with_score |
Vector search only (query embedding → nearest k). No hybrid sparse+dense mode in this app. |
| 2D projection | collection.get(..., include=[embeddings, documents, metadatas], limit=max_points, offset=0) |
First max_points rows of the (optionally filtered) collection in Chroma’s iteration order—not a random sample of the full set if the collection is larger than the cap. |
Everything reads the same on-disk persist directory (CHROMA_PERSIST_DIRECTORY). Nothing merges an external keyword index or SQL “hybrid” ranker in the current backend.