Anvia Docs

@anvia/chroma connects Anvia's vector store interface to ChromaDB. Use it to store, search, and retrieve embedded documents through a ChromaDB instance.

Install

pnpm add @anvia/chroma

The ChromaDB client (chromadb) is a transitive dependency. You need a running ChromaDB server or use the in-process mode.

Quick Start

import { ChromaVectorStore } from "@anvia/chroma";
import { createFastEmbedEmbeddingModel } from "@anvia/fastembed";

const model = await createFastEmbedEmbeddingModel();

// Connect (creates collection if missing)
const store = await ChromaVectorStore.connect({
  collectionName: "documents",
});

// Upsert embedded documents
await store.upsertDocuments([
  {
    id: "doc-1",
    document: "Anvia is a TypeScript AI agent framework.",
    embeddings: await model.embedTexts(["Anvia is a TypeScript AI agent framework."]),
  },
]);

// Search
const index = store.index(model);
const results = await index.search({ query: "What is Anvia?", topK: 5 });
console.log(results[0].document);

Connection Options

type ChromaVectorStoreConnectOptions = {
  client?: ChromaClientLike;           // pre-configured ChromaDB client
  collectionName: string;              // required
  createIfMissing?: boolean;           // default: true
  metadata?: Record<string, unknown>;  // collection metadata (default: { "hnsw:space": "cosine" })
  configuration?: Record<string, unknown>;  // ChromaDB collection configuration
};

// Default: creates collection if missing, cosine distance
const store = await ChromaVectorStore.connect({ collectionName: "docs" });

// Don't create if missing (throws if collection doesn't exist)
const store = await ChromaVectorStore.connect({
  collectionName: "docs",
  createIfMissing: false,
});

// Custom distance metric
const store = await ChromaVectorStore.connect({
  collectionName: "docs",
  metadata: { "hnsw:space": "l2" },
});

// Pre-configured client
const store = await ChromaVectorStore.connect({
  client: existingChromaClient,
  collectionName: "docs",
});

Upserting Documents

Documents use the EmbeddedDocument type from @anvia/core/embeddings:

await store.upsertDocuments([
  {
    id: "doc-1",
    document: { title: "Getting Started", content: "..." },  // any JSON-serializable value
    metadata: { category: "guide", version: 2 },
    embeddings: await model.embedTexts(["Getting Started content..."]),
  },
]);

id is the logical document ID
document is the stored content (string or JSON-serializable object)
metadata is optional filterable metadata
embeddings is an array of Embedding objects (one per chunk)
Documents with multiple embeddings get indexed as doc-1#embedding:0, doc-1#embedding:1, etc.

Searching

const index = store.index(model);

// Basic search
const results = await index.search({ query: "agent tools", topK: 5 });

// With threshold
const results = await index.search({
  query: "agent tools",
  topK: 10,
  threshold: 0.7,  // minimum cosine similarity
});

// With metadata filter
const results = await index.search({
  query: "agent tools",
  topK: 5,
  filter: { type: "eq", key: "category", value: "guide" },
});

Metadata Filters

// Equality
{ type: "eq", key: "category", value: "guide" }

// Greater than / less than
{ type: "gt", key: "version", value: 2 }
{ type: "lt", key: "version", value: 5 }

// Logical combinators
{ type: "and", filters: [
  { type: "eq", key: "category", value: "guide" },
  { type: "gt", key: "version", value: 1 },
]}

{ type: "or", filters: [
  { type: "eq", key: "category", value: "guide" },
  { type: "eq", key: "category", value: "api" },
]}

Agent Tool

Expose the vector index as an agent tool:

import { AgentBuilder } from "@anvia/core";

const searchTool = index.asTool({
  name: "search_docs",
  description: "Search the documentation.",
});

const agent = new AgentBuilder("support", model)
  .tool(searchTool)
  .build();

Distance Metrics

Metric	ChromaDB `metadata` value	Notes
Cosine (default)	`"cosine"`	Best for text embeddings
L2 (Euclidean)	`"l2"`	Geometric distance
Inner product	`"ip"`	Dot product similarity

Error Handling

connect() throws if ChromaDB is unreachable
connect({ createIfMissing: false }) throws if the collection does not exist
upsertDocuments() throws if a document has zero embeddings
Metadata keys starting with __anvia_ are reserved and rejected

Retrieval Guide for RAG concepts
Chroma Reference for full API types
@anvia/fastembed or @anvia/transformers for local embeddings