D · Vector DB

  /** What it does: filters the records, scores every one by cosine, and returns the k best. */
  async query(vector: number[], k: number, filter?: Filter): Promise<Hit[]> {
    return (await this.all())
      .filter((r) => passes(r, filter))
      .map(({ vector: v, ...chunk }) => ({ chunk, score: cosine(vector, v) }))
      .sort((a, b) => b.score - a.score)
      .slice(0, k);
  }

  /** What it does: opens or creates our Chroma collection, and fails clearly if Chroma is down. */
  private async collection(): Promise<Collection> {
    if (!(await heartbeat())) {
      throw new Error(
        `Chroma is not reachable at ${config.chromaUrl}. Start it: podman compose up -d  (or use --store json)`,
      );
    }
    // cosine space: Chroma returns distance = 1 − cosine similarity
    /**
     * HNSW settings: we set only `space`. Chroma fills in the rest with its defaults
     * (see them in Bruno: collections → configuration_json → hnsw).
     * For a more accurate search, add more, for example { space: "cosine", ef_search: 200, max_neighbors: 32 }.
     * Higher means closer to exact, but slower. Checking every vector is brute force.
     * max_neighbors only applies when the collection is created: run npm run catchup -- 5.
     */
    return chroma.getOrCreateCollection({
      name: this.name,
      embeddingFunction: null,
      configuration: { hnsw: { space: "cosine" } },
    });
  }

  /** What it does: deletes one edition's old chunks, then adds the new ones in batches of 100. */
  async replaceEdition(edition: string, records: VectorChunk[]): Promise<void> {
    const col = await this.collection();
    await col.delete({ where: { edition } });
    for (let i = 0; i < records.length; i += 100) {
      const slice = records.slice(i, i + 100);
      await col.add({
        ids: slice.map((r) => r.id),
        embeddings: slice.map((r) => r.vector),
        documents: slice.map((r) => r.text),
        // metadata values must be plain strings/numbers — the section list becomes "2,3"
        metadatas: slice.map((r) => ({
          docId: r.docId,
          edition: r.edition,
          title: r.title,
          access: r.access,
          lang: r.lang,
          sections: r.sections.join(","),
        })),
      });
    }
  }

# One container: the vector database. Ollama is NOT here — it runs on your machine, where the models
# are already pulled and the GPU is.
#
#   podman compose up -d      # start Chroma in the background (http://localhost:8000)
#   podman compose ps         # is it healthy?
#   podman compose down       # stop it; the data stays in the volume
#   podman compose down -v    # stop it and delete the stored vectors
#
# No compose? The same thing in one line:
#   podman run -d --name chroma -p 8000:8000 -v chroma-data:/data docker.io/chromadb/chroma:1.5.9

services:
  chroma:
    image: docker.io/chromadb/chroma:1.5.9
    ports:
      - "8000:8000"
    volumes:
      - chroma-data:/data
    environment:
      ANONYMIZED_TELEMETRY: "false"
    healthcheck:
      test: ["CMD", "/bin/bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/8000 && echo -e 'GET /api/v2/heartbeat HTTP/1.0\\r\\n\\r\\n' >&3 && grep -q nanosecond <&3"]
      interval: 5s
      timeout: 3s
      retries: 12

volumes:
  chroma-data:

body:json {
  {
    "limit": 3,
    "include": ["documents", "metadatas"]
  }
}