@quarry-systems/drift-vector-chroma 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,149 @@
+# @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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@quarry-systems/drift-vector-chroma",
+  "version": "0.1.0-alpha.1",
+  "description": "Chroma vector store adapter for Drift RAG pipelines",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "drift",
+    "vector",
+    "chroma",
+    "embeddings",
+    "rag",
+    "similarity-search"
+  ],
+  "author": "Quarry Systems",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chromadb": "^1.9.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md",
+    "CHANGELOG.md"
+  ],
+  "type": "commonjs"
+}