Skip to content

Instrument your app

Vector stores and rerankers

Adapters for pgvector and an in-memory store, and the small interface to write your own.

pgvector#

JavaScript
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
JavaScript
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.

JavaScript
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:

TypeScript
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, then threshold, then k, 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.

JavaScript
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:

TypeScript
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.