Instrument your app
Vector stores and rerankers
Adapters for pgvector and an in-memory store, and the small interface to write your own.
pgvector#
import pg from "pg";
import { pgvectorStore } from "@chunktrace/sdk";
const store = pgvectorStore({
name: "docs", // shown on the trace
db: new pg.Pool(), // anything with query(sql, params)
table: "chunks",
embed: async (text) => embedding(text), // your embedding function
});The adapter scores with cosine similarity and applies the filter and the threshold in SQL, before the limit.
It expects these columns. Rename any of them with columns:
| Column | Default name | Type |
|---|---|---|
| Chunk id | id |
text |
| Document id | document_id |
text |
| Chunk text | text |
text |
| Metadata | metadata |
jsonb |
| Embedding | embedding |
vector |
pgvectorStore({ name: "docs", db, table: "passages", embed, columns: { id: "passage_id", text: "body" } });Starting from nothing? pgvectorSchemaSql("chunks", 1536) returns the CREATE TABLE and index statements for a table with these defaults.
In memory#
For tests, demos and small corpora. Nothing to install or run.
import { hashedBagOfWords, memoryStore } from "@chunktrace/sdk";
const store = memoryStore({
name: "support-docs",
embed: hashedBagOfWords(), // a deterministic stand-in for an embedding model
chunks: [
{ chunk_id: "faq#3", document_id: "faq", metadata: { tenant: "acme" }, text: "How do I request a refund? …" },
],
});hashedBagOfWords() makes no network calls and gives the same scores every time, which is what you want in a test. Pass a real embedding function for real similarity.
Your own store#
A store is an object with a name and one method:
import type { VectorStore } from "@chunktrace/sdk";
const store: VectorStore = {
name: "products",
provider: "pinecone", // optional, shown on the trace
async search({ queryText, k, filter, threshold }) {
const matches = await index.query({ /* … */ });
return matches.map((m) => ({
chunk_id: m.id,
score: m.score, // higher is better
document_id: m.metadata.doc,
metadata: m.metadata,
text: m.metadata.text,
}));
},
};Two rules make the trace truthful:
- Apply
filter, thenthreshold, thenk, the way your production search does. The trace should record what your app really saw. - Handle a call with no filter and no threshold. That is the shadow query.
Return text if you use keyword labels or buildContext, and document_id if you use document labels.
Metadata filters#
A filter is an object. Every key must match.
metadata_filter: {
tenant: "acme", // equals
lang: { $in: ["en", "de"] }, // one of
status: { $ne: "archived" }, // not equal
year: { $gte: 2024, $lt: 2026 }, // numeric range: $gt, $gte, $lt, $lte
}The rule engine re-runs this filter over the shadow results, so a FILTER_REMOVED finding can name the key that failed and the value the chunk had. A chunk with no value for a key fails equality, $in and range clauses, and passes $ne.
There is no OR and no nesting.
Rerankers#
A reranker is an object with a score method:
import type { Reranker } from "@chunktrace/sdk";
const reranker: Reranker = {
model: "rerank-v3", // optional, shown on the trace
async score(queryText, hits) {
const scores = await api.rerank(queryText, hits.map((h) => h.text));
return hits.map((h, i) => ({ chunk_id: h.chunk_id, score: scores[i] }));
},
};
hits = await run.rerank(reranker, hits, { top_n: 3 });The SDK sorts by score and applies top_n and score_threshold, so the trace records every chunk's rank before and after.