npm package: @quarry-systems/drift-vector-chroma
Description: Chroma vector store adapter for Drift RAG pipelines
Author: Quarry Systems
Latest version: 0.1.1-alpha.1

# @quarry-systems/drift-vector-chroma

![Backend Only](https://img.shields.io/badge/runtime-node-green) ![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-blue)

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

```bash
npm install @quarry-systems/drift-vector-chroma
```

## Requirements

Chroma requires a running Chroma server. You can start one with Docker:

```bash
docker run -p 8000:8000 chromadb/chroma
```

Or install and run Chroma locally:

```bash
pip install chromadb
chroma run --host localhost --port 8000
```

## Usage

```typescript
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

```typescript
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:

```bash
# 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