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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quarry-systems/drift-vector-chroma",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.1-alpha.1",
   "description": "Chroma vector store adapter for Drift RAG pipelines",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -30,7 +30,7 @@
     "vitest": "^2.1.0"
   },
   "files": [
-    "dist",
+    "src",
     "README.md",
     "LICENSE.md",
     "CHANGELOG.md"

package/src/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) 2025-2026 Quarry Systems (Brett Nye)
+ *
+ * This file is part of MCG (Managed Cyclic Graph).
+ *
+ * MCG is dual-licensed under:
+ * 1. GNU Affero General Public License v3.0 (AGPL-3.0)
+ *    See LICENSE-AGPL or https://www.gnu.org/licenses/agpl-3.0.html
+ * 2. Commercial License
+ *    See LICENSE-COMMERCIAL.md or contact licensing@quarry-systems.com
+ *
+ * You may use this file under the terms of either license.
+ *
+ * For commercial licensing inquiries:
+ * Email: licensing@quarry-systems.com
+ * Web: https://quarry-systems.com/license
+ */
+import type { VectorAdapter } from '@quarry-systems/drift-contracts';
+/**
+ * Chroma vector store configuration.
+ */
+export interface ChromaVectorConfig {
+    /** Collection name (default: 'mcg_vectors') */
+    collection?: string;
+    /** Chroma server URL (default: 'http://localhost:8000' for server mode) */
+    url?: string;
+    /** Path for local persistence (default: in-memory if not specified) */
+    persistPath?: string;
+    /** Embedding dimension (optional, auto-detected from first insert) */
+    dimension?: number;
+    /** Distance metric (default: 'cosine') */
+    distanceMetric?: 'cosine' | 'l2' | 'ip';
+}
+/**
+ * Create a Chroma vector adapter.
+ *
+ * @example
+ * ```typescript
+ * // In-memory (for testing)
+ * const vectors = await createChromaVector({ collection: 'test' });
+ *
+ * // Local persistence
+ * const vectors = await createChromaVector({
+ *   collection: 'docs',
+ *   persistPath: './chroma_data'
+ * });
+ *
+ * // Server mode
+ * const vectors = await createChromaVector({
+ *   collection: 'docs',
+ *   url: 'http://localhost:8000'
+ * });
+ *
+ * // Upsert vectors
+ * await vectors.upsert([
+ *   {
+ *     id: 'doc-1-chunk-0',
+ *     vector: [0.1, 0.2, 0.3, ...],
+ *     metadata: { docId: 'doc-1', sequence: 0 },
+ *     document: 'First paragraph...'
+ *   }
+ * ]);
+ *
+ * // Query
+ * const results = await vectors.query({
+ *   vector: [0.15, 0.25, 0.35, ...],
+ *   topK: 5
+ * });
+ * ```
+ */
+export declare function createChromaVector(config?: ChromaVectorConfig): Promise<VectorAdapter>;
+export type { VectorAdapter, VectorItem, VectorQueryOptions, VectorMatch, } from '@quarry-systems/drift-contracts';

package/src/index.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Copyright (c) 2025-2026 Quarry Systems (Brett Nye)
+ *
+ * This file is part of MCG (Managed Cyclic Graph).
+ *
+ * MCG is dual-licensed under:
+ * 1. GNU Affero General Public License v3.0 (AGPL-3.0)
+ *    See LICENSE-AGPL or https://www.gnu.org/licenses/agpl-3.0.html
+ * 2. Commercial License
+ *    See LICENSE-COMMERCIAL.md or contact licensing@quarry-systems.com
+ *
+ * You may use this file under the terms of either license.
+ *
+ * For commercial licensing inquiries:
+ * Email: licensing@quarry-systems.com
+ * Web: https://quarry-systems.com/license
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createChromaVector = createChromaVector;
+/**
+ * MCG Chroma Vector Adapter
+ *
+ * Chroma-based vector storage for semantic search and RAG.
+ * Ideal for local development, demos, and indie-tier deployments.
+ *
+ * @packageDocumentation
+ */
+const chromadb_1 = require("chromadb");
+// ============================================================================
+// Chroma Vector Implementation
+// ============================================================================
+/**
+ * Create a Chroma vector adapter.
+ *
+ * @example
+ * ```typescript
+ * // In-memory (for testing)
+ * const vectors = await createChromaVector({ collection: 'test' });
+ *
+ * // Local persistence
+ * const vectors = await createChromaVector({
+ *   collection: 'docs',
+ *   persistPath: './chroma_data'
+ * });
+ *
+ * // Server mode
+ * const vectors = await createChromaVector({
+ *   collection: 'docs',
+ *   url: 'http://localhost:8000'
+ * });
+ *
+ * // Upsert vectors
+ * await vectors.upsert([
+ *   {
+ *     id: 'doc-1-chunk-0',
+ *     vector: [0.1, 0.2, 0.3, ...],
+ *     metadata: { docId: 'doc-1', sequence: 0 },
+ *     document: 'First paragraph...'
+ *   }
+ * ]);
+ *
+ * // Query
+ * const results = await vectors.query({
+ *   vector: [0.15, 0.25, 0.35, ...],
+ *   topK: 5
+ * });
+ * ```
+ */
+async function createChromaVector(config = {}) {
+    const collectionName = config.collection || 'mcg_vectors';
+    const distanceMetric = config.distanceMetric || 'cosine';
+    // Initialize Chroma client
+    // Note: ChromaDB JS client defaults to in-memory mode when no path is provided
+    const clientConfig = {};
+    if (config.url) {
+        clientConfig.path = config.url;
+    }
+    // persistPath is not directly supported by chromadb JS client
+    // For persistence, users should run a Chroma server
+    const client = new chromadb_1.ChromaClient(clientConfig);
+    // Get or create collection
+    let collection;
+    try {
+        collection = await client.getOrCreateCollection({
+            name: collectionName,
+            metadata: {
+                'hnsw:space': distanceMetric,
+            },
+        });
+    }
+    catch (error) {
+        throw new Error(`Failed to initialize Chroma collection: ${error}`);
+    }
+    return {
+        name: 'chroma',
+        async upsert(items) {
+            if (items.length === 0)
+                return;
+            const ids = items.map(item => item.id);
+            const embeddings = items.map(item => item.vector);
+            // Convert metadata to Chroma's strict type (string | number | boolean values only)
+            const metadatas = items.map(item => {
+                if (!item.metadata)
+                    return {};
+                const chromaMeta = {};
+                for (const [key, value] of Object.entries(item.metadata)) {
+                    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                        chromaMeta[key] = value;
+                    }
+                    else if (value !== null && value !== undefined) {
+                        // Serialize complex values as JSON strings
+                        chromaMeta[key] = JSON.stringify(value);
+                    }
+                }
+                return chromaMeta;
+            });
+            // Filter out undefined documents
+            const documents = items.map(item => item.document ?? '');
+            await collection.upsert({
+                ids,
+                embeddings,
+                metadatas,
+                documents,
+            });
+        },
+        async query(options) {
+            const results = await collection.query({
+                queryEmbeddings: [options.vector],
+                nResults: options.topK,
+                where: options.filter,
+                include: [
+                    chromadb_1.IncludeEnum.Metadatas,
+                    chromadb_1.IncludeEnum.Documents,
+                    chromadb_1.IncludeEnum.Distances,
+                ],
+            });
+            if (!results.ids[0] || results.ids[0].length === 0) {
+                return [];
+            }
+            const matches = [];
+            for (let i = 0; i < results.ids[0].length; i++) {
+                const id = results.ids[0][i];
+                const distance = results.distances?.[0]?.[i] ?? 1;
+                // Convert distance to similarity score (0-1, higher is better)
+                // For cosine: distance is already 0-2, convert to similarity
+                // For L2: distance is euclidean, convert to similarity
+                let score;
+                if (distanceMetric === 'cosine') {
+                    // Cosine distance: 0 = identical, 2 = opposite
+                    score = 1 - (distance / 2);
+                }
+                else if (distanceMetric === 'l2') {
+                    // L2 distance: 0 = identical, higher = more different
+                    // Use exponential decay for similarity
+                    score = Math.exp(-distance);
+                }
+                else {
+                    // Inner product: higher is better (already similarity-like)
+                    score = distance;
+                }
+                // Apply minimum score filter
+                if (options.minScore !== undefined && score < options.minScore) {
+                    continue;
+                }
+                matches.push({
+                    id,
+                    score,
+                    metadata: results.metadatas?.[0]?.[i],
+                    document: results.documents?.[0]?.[i] ?? undefined,
+                });
+            }
+            return matches;
+        },
+        async delete(ids) {
+            if (ids.length === 0)
+                return;
+            await collection.delete({ ids });
+        },
+        async get(id) {
+            const results = await collection.get({
+                ids: [id],
+                include: [
+                    chromadb_1.IncludeEnum.Metadatas,
+                    chromadb_1.IncludeEnum.Documents,
+                    chromadb_1.IncludeEnum.Embeddings,
+                ],
+            });
+            if (!results.ids || results.ids.length === 0) {
+                return null;
+            }
+            return {
+                id: results.ids[0],
+                vector: results.embeddings?.[0] ?? [],
+                metadata: results.metadatas?.[0],
+                document: results.documents?.[0] ?? undefined,
+            };
+        },
+        async count() {
+            const result = await collection.count();
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../libs/drift/drift-plugins/mcg-vector-chroma/src/index.ts"],"names":[],"mappings":"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"}

package/src/plugin.manifest.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Plugin Manifest for @quarry-systems/mcg-vector-chroma
+ *
+ * This manifest declares the plugin's metadata, capabilities, and requirements.
+ * It enables future security policies, sandboxing, and hosted execution.
+ */
+import type { PluginManifest } from '@quarry-systems/drift-contracts';
+export declare const manifest: PluginManifest;
+export default manifest;

package/src/plugin.manifest.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Plugin Manifest for @quarry-systems/mcg-vector-chroma
+ *
+ * This manifest declares the plugin's metadata, capabilities, and requirements.
+ * It enables future security policies, sandboxing, and hosted execution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.manifest = void 0;
+exports.manifest = {
+    name: '@quarry-systems/mcg-vector-chroma',
+    version: '0.6.0',
+    apiVersion: '1.0',
+    description: 'ChromaDB vector store plugin for Managed Cyclic Graph (MCG)',
+    author: {
+        name: 'Quarry Systems',
+        email: 'support@quarrysystems.com',
+    },
+    license: 'ISC',
+    type: ['node'],
+    capabilities: {
+        network: true, // Makes API calls to ChromaDB
+        filesystem: false,
+        secrets: false,
+        subprocess: false,
+    },
+    nodes: [],
+    services: [
+        {
+            id: 'chromaVectorStore',
+            name: 'Chroma Vector Store Service',
+            description: 'ChromaDB-based vector storage and similarity search service',
+        },
+    ],
+    peerDependencies: {
+        '@quarry-systems/drift-core': '^0.6.0',
+        '@quarry-systems/drift-contracts': '^0.6.0',
+    },
+    keywords: ['drift', 'mcg', 'managed-cyclic-graph', 'plugin', 'vector', 'chroma', 'chromadb', 'embeddings', 'similarity'],
+    repository: {
+        type: 'git',
+        url: 'https://github.com/quarry-systems/quarry-systems',
+        directory: 'libs/drift/drift-plugins/mcg-vector-chroma',
+    },
+};
+exports.default = exports.manifest;
+//# sourceMappingURL=plugin.manifest.js.map

package/src/plugin.manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.manifest.js","sourceRoot":"","sources":["../../../../../../libs/drift/drift-plugins/mcg-vector-chroma/src/plugin.manifest.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAIU,QAAA,QAAQ,GAAmB;IACtC,IAAI,EAAE,mCAAmC;IACzC,OAAO,EAAE,OAAO;IAChB,UAAU,EAAE,KAAK;IAEjB,WAAW,EAAE,6DAA6D;IAE1E,MAAM,EAAE;QACN,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,2BAA2B;KACnC;IAED,OAAO,EAAE,KAAK;IAEd,IAAI,EAAE,CAAC,MAAM,CAAC;IAEd,YAAY,EAAE;QACZ,OAAO,EAAE,IAAI,EAAO,8BAA8B;QAClD,UAAU,EAAE,KAAK;QACjB,OAAO,EAAE,KAAK;QACd,UAAU,EAAE,KAAK;KAClB;IAED,KAAK,EAAE,EAAE;IAET,QAAQ,EAAE;QACR;YACE,EAAE,EAAE,mBAAmB;YACvB,IAAI,EAAE,6BAA6B;YACnC,WAAW,EAAE,6DAA6D;SAC3E;KACF;IAED,gBAAgB,EAAE;QAChB,4BAA4B,EAAE,QAAQ;QACtC,iCAAiC,EAAE,QAAQ;KAC5C;IAED,QAAQ,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,sBAAsB,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,CAAC;IAExH,UAAU,EAAE;QACV,IAAI,EAAE,KAAK;QACX,GAAG,EAAE,kDAAkD;QACvD,SAAS,EAAE,4CAA4C;KACxD;CACF,CAAC;AAEF,kBAAe,gBAAQ,CAAC"}