@quarry-systems/drift-vector-chroma

Chroma vector store adapter for Drift RAG pipelines.

Features

• Local-first: Ideal for development and indie-tier deployments
• Semantic search: Vector similarity with cosine/L2/IP distance metrics
• Metadata filtering: Filter results by document metadata
• Provider-agnostic: Implements VectorAdapter contract

Installation

npm install @quarry-systems/drift-vector-chroma

Requirements

Chroma requires a running Chroma server. You can start one with Docker:

docker run -p 8000:8000 chromadb/chroma

Or install and run Chroma locally:

pip install chromadb
chroma run --host localhost --port 8000

Usage

import { createChromaVector } from '@quarry-systems/drift-vector-chroma';
import { getOpenAIEmbeddingAdapter } from '@quarry-systems/drift-openai';

// Create vector store
const vectors = await createChromaVector({
  collection: 'my_docs',
  url: 'http://localhost:8000',
  distanceMetric: 'cosine'
});

// Get embeddings
const embedder = getOpenAIEmbeddingAdapter();
const result = await embedder.embed({
  model: 'text-embedding-3-small',
  input: ['Hello world', 'How are you?']
});

// Index vectors
await vectors.upsert([
  {
    id: 'doc-1-chunk-0',
    vector: result.embeddings[0],
    metadata: { docId: 'doc-1', sequence: 0 },
    document: 'Hello world'
  },
  {
    id: 'doc-1-chunk-1',
    vector: result.embeddings[1],
    metadata: { docId: 'doc-1', sequence: 1 },
    document: 'How are you?'
  }
]);

// Query by vector
const queryResult = await embedder.embed({
  model: 'text-embedding-3-small',
  input: 'greeting'
});

const matches = await vectors.query({
  vector: queryResult.embeddings[0],
  topK: 5,
  filter: { docId: 'doc-1' }
});

console.log(matches);
// [
//   {
//     id: 'doc-1-chunk-0',
//     score: 0.95,
//     metadata: { docId: 'doc-1', sequence: 0 },
//     document: 'Hello world'
//   },
//   ...
// ]

Configuration

interface ChromaVectorConfig {
  /** Collection name (default: 'mcg_vectors') */
  collection?: string;
  
  /** Chroma server URL (default: 'http://localhost:8000') */
  url?: string;
  
  /** Distance metric (default: 'cosine') */
  distanceMetric?: 'cosine' | 'l2' | 'ip';
}

Testing

Tests require a running Chroma server:

# Start Chroma
docker run -p 8000:8000 chromadb/chroma

# Run tests
export CHROMA_URL=http://localhost:8000
npm test

Tests are automatically skipped if CHROMA_URL is not set.

API

createChromaVector(config?)

Creates a Chroma vector adapter.

VectorAdapter Methods

• upsert(items: VectorItem[]): Promise<void> - Insert or update vectors
• query(options: VectorQueryOptions): Promise<VectorMatch[]> - Search by vector
• get(id: string): Promise<VectorItem | null> - Get vector by ID
• delete(ids: string[]): Promise<void> - Delete vectors
• count(): Promise<number> - Count total vectors

Production Deployment

For production, consider:

1. Managed Chroma Cloud - Hosted service with automatic scaling
2. Self-hosted Chroma - Run Chroma server with persistent storage
3. Alternative adapters - Use drift-vector-pgvector for Postgres or drift-vector-pinecone for managed service

License

MIT