@juspay/neurolink 9.88.12 → 9.90.0

package/dist/index.d.ts

@@ -426,7 +426,7 @@ export { AgentExecuteRequestSchema, AlreadyRunningError, AuthenticationError, Au
  * console.log(response.answer);
  * ```
  */
-export { assembleContext, batchRerank, CharacterChunker, ChunkerRegistry, CohereRelevanceScorer, CrossEncoderReranker, CSVLoader, chunkText, createChunker, createContextWindow, createHybridSearch, createRAGPipeline, createVectorQueryTool, executeWithCircuitBreaker, extractMetadata, formatContextWithCitations, GraphRAG, getAvailableStrategies, getCircuitBreaker, getDefaultChunkerConfig, getRecommendedStrategy, HTMLChunker, HTMLLoader, InMemoryBM25Index, InMemoryVectorStore, JSONChunker as RAGJSONChunker, JSONLoader, LaTeXChunker, LLMMetadataExtractor, linearCombination, loadDocument, loadDocuments, MarkdownChunker, MarkdownLoader, MDocument, PDFLoader, prepareRAGTool, processDocument, RAGCircuitBreaker, RAGCircuitBreakerManager, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
+export { assembleContext, batchRerank, CharacterChunker, ChunkerRegistry, CohereRelevanceScorer, CrossEncoderReranker, CSVLoader, chunkText, createChunker, createContextWindow, createHybridSearch, createRAGPipeline, createVectorQueryTool, executeWithCircuitBreaker, extractMetadata, formatContextWithCitations, GraphRAG, getAvailableStrategies, getCircuitBreaker, getDefaultChunkerConfig, getRecommendedStrategy, HTMLChunker, HTMLLoader, InMemoryBM25Index, InMemoryVectorStore, JSONChunker as RAGJSONChunker, JSONLoader, LaTeXChunker, LLMMetadataExtractor, linearCombination, loadDocument, loadDocuments, MarkdownChunker, MarkdownLoader, MDocument, PDFLoader, prepareRAGTool, processDocument, RAGCircuitBreaker, RAGCircuitBreakerManager, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, ChromaVectorStore, PgVectorStore, PineconeVectorStore, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
 export { ContextBuilder } from "./evaluation/contextBuilder.js";
 export { AuthProviderFactory, createAuthProvider, AuthProviderRegistry, AuthError as AuthErrorFactory, AuthErrorCodes, BaseAuthProvider, InMemorySessionStorage, AuthProviderError, createAuthMiddleware as createAuthProviderMiddleware, createRBACMiddleware, createProtectedMiddleware, createExpressAuthMiddleware, createRequestContext, extractToken, AuthMiddlewareError, AuthMiddlewareErrorCodes, UserRateLimiter, MemoryRateLimitStorage, RedisRateLimitStorage, createRateLimitByUserMiddleware, createAuthenticatedRateLimitMiddleware, createRateLimitStorage, SessionManager, MemorySessionStorage, RedisSessionStorage, createSessionStorage, AuthContextHolder, globalAuthContext, getAuthContext, getCurrentUser, getCurrentSession, isAuthenticated, hasRole, hasAnyRole, hasPermission, hasAllPermissions, requireAuth, requireRole, requirePermission, requireUser, runWithAuthContext, createAuthenticatedContext, RequestContext, NEUROLINK_RESOURCE_ID_KEY, NEUROLINK_THREAD_ID_KEY, createAuthValidatorFromProvider, } from "./auth/index.js";
 export { detectAndRedactPII } from "./utils/piiDetector.js";

package/dist/index.js

@@ -683,7 +683,7 @@ extractMetadata, formatContextWithCitations,
 // Graph RAG
 GraphRAG, getAvailableStrategies, getCircuitBreaker, getDefaultChunkerConfig, getRecommendedStrategy, HTMLChunker, HTMLLoader, InMemoryBM25Index, InMemoryVectorStore, JSONChunker as RAGJSONChunker, JSONLoader, LaTeXChunker, LLMMetadataExtractor, linearCombination, loadDocument, loadDocuments, MarkdownChunker, MarkdownLoader, MDocument, PDFLoader, 
 // RAG Integration for generate/stream
-prepareRAGTool, processDocument, RAGCircuitBreaker, RAGCircuitBreakerManager, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
+prepareRAGTool, processDocument, RAGCircuitBreaker, RAGCircuitBreakerManager, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, ChromaVectorStore, PgVectorStore, PineconeVectorStore, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
 // Legacy RAGAS evaluation classes are now exported from the unified
 // evaluation block above (via ./evaluation/index.js barrel).
 // ContextBuilder is the only class not covered by the barrel export.

package/dist/lib/adapters/tts/googleTTSHandler.d.ts

@@ -24,6 +24,7 @@ export declare class GoogleTTSHandler implements TTSHandler {
      * before invoking provider handlers, not inside this class.
      */
     readonly maxTextLength: number;
+    private readonly credentialsPath;
     constructor(credentialsPath?: string);
     /**
      * Validate that the provider is properly configured
@@ -31,6 +32,15 @@ export declare class GoogleTTSHandler implements TTSHandler {
      * @returns True if provider can generate TTS
      */
     isConfigured(): boolean;
+    /**
+     * Lazily construct (and cache) the Google Cloud TTS client.
+     *
+     * `@google-cloud/text-to-speech` is an optional dependency: importing it
+     * only happens here, on first actual use, so a handler instance can be
+     * constructed (e.g. during auto-registration at module load) without the
+     * package being installed.
+     */
+    private getClient;
     /**
      * Get available voices for the provider
      *

package/dist/lib/adapters/tts/googleTTSHandler.js

@@ -1,12 +1,3 @@
-/**
- * Google Cloud Text-to-Speech Handler
- *
- * Handler for Google Cloud Text-to-Speech API integration.
- *
- * @module adapters/tts/googleTTSHandler
- * @see https://cloud.google.com/text-to-speech/docs
- */
-import { TextToSpeechClient } from "@google-cloud/text-to-speech";
 import { TTSError, TTS_ERROR_CODES } from "../../utils/ttsProcessor.js";
 import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
 import { logger } from "../../utils/logger.js";
@@ -36,11 +27,10 @@ export class GoogleTTSHandler {
      * before invoking provider handlers, not inside this class.
      */
     maxTextLength = GoogleTTSHandler.DEFAULT_MAX_TEXT_LENGTH;
+    credentialsPath;
     constructor(credentialsPath) {
-        const path = credentialsPath ?? process.env.GOOGLE_APPLICATION_CREDENTIALS;
-        if (path) {
-            this.client = new TextToSpeechClient({ keyFilename: path });
-        }
+        this.credentialsPath =
+            credentialsPath ?? process.env.GOOGLE_APPLICATION_CREDENTIALS;
     }
     /**
      * Validate that the provider is properly configured
@@ -48,7 +38,24 @@ export class GoogleTTSHandler {
      * @returns True if provider can generate TTS
      */
     isConfigured() {
-        return this.client !== null;
+        return this.credentialsPath !== undefined;
+    }
+    /**
+     * Lazily construct (and cache) the Google Cloud TTS client.
+     *
+     * `@google-cloud/text-to-speech` is an optional dependency: importing it
+     * only happens here, on first actual use, so a handler instance can be
+     * constructed (e.g. during auto-registration at module load) without the
+     * package being installed.
+     */
+    async getClient() {
+        if (!this.client) {
+            const { TextToSpeechClient } = await import("@google-cloud/text-to-speech");
+            this.client = new TextToSpeechClient({
+                keyFilename: this.credentialsPath,
+            });
+        }
+        return this.client;
     }
     /**
      * Get available voices for the provider
@@ -60,7 +67,7 @@ export class GoogleTTSHandler {
      * @returns List of available voices
      */
     async getVoices(languageCode) {
-        if (!this.client) {
+        if (!this.isConfigured()) {
             throw new TTSError({
                 code: TTS_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
                 message: "Google Cloud TTS client not initialized. Set GOOGLE_APPLICATION_CREDENTIALS or pass credentials path.",
@@ -69,6 +76,7 @@ export class GoogleTTSHandler {
                 retriable: false,
             });
         }
+        const client = await this.getClient();
         const span = SpanSerializer.createSpan(SpanType.TTS, "tts.google.listVoices", {
             "tts.operation": "listVoices",
             "tts.provider": "google",
@@ -84,7 +92,7 @@ export class GoogleTTSHandler {
                 return this.voicesCache.voices;
             }
             // Call Google Cloud listVoices API
-            const [response] = await this.client.listVoices(languageCode ? { languageCode } : {});
+            const [response] = await client.listVoices(languageCode ? { languageCode } : {});
             if (!response.voices || response.voices.length === 0) {
                 logger.warn("Google Cloud TTS returned no voices");
                 const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
@@ -149,7 +157,7 @@ export class GoogleTTSHandler {
      * @returns Audio buffer with metadata
      */
     async synthesize(text, options) {
-        if (!this.client) {
+        if (!this.isConfigured()) {
             throw new TTSError({
                 code: TTS_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
                 message: "Google Cloud TTS client not initialized. Set GOOGLE_APPLICATION_CREDENTIALS or pass credentials path.",
@@ -158,6 +166,7 @@ export class GoogleTTSHandler {
                 retriable: false,
             });
         }
+        const client = await this.getClient();
         const voiceId = options.voice ?? "en-US-Neural2-C";
         const span = SpanSerializer.createSpan(SpanType.TTS, "tts.google.synthesize", {
             "tts.operation": "synthesize",
@@ -196,7 +205,7 @@ export class GoogleTTSHandler {
                     volumeGainDb: options.volumeGainDb ?? 0.0,
                 },
             };
-            const [response] = await this.client.synthesizeSpeech(request, {
+            const [response] = await client.synthesizeSpeech(request, {
                 timeout: GoogleTTSHandler.DEFAULT_API_TIMEOUT_MS,
             });
             const audioContent = response.audioContent;

package/dist/lib/agent/directTools.js

@@ -3,7 +3,6 @@ import * as fs from "fs";
 import * as path from "path";
 import { execFile } from "child_process";
 import { logger } from "../utils/logger.js";
-import { VertexAI } from "@google-cloud/vertexai";
 import { CSVProcessor } from "../utils/csvProcessor.js";
 import { shouldEnableBashTool } from "../utils/toolUtils.js";
 import { tool } from "../utils/tool.js";
@@ -604,6 +603,7 @@ export const directAgentTools = {
                     };
                 }
                 const limitedResults = Math.min(Math.max(maxResults, 1), 5);
+                const { VertexAI } = await import("@google-cloud/vertexai");
                 const vertex_ai = new VertexAI({
                     project: hasProjectId,
                     location: projectLocation,

package/dist/lib/index.d.ts

@@ -426,7 +426,7 @@ export { AgentExecuteRequestSchema, AlreadyRunningError, AuthenticationError, Au
  * console.log(response.answer);
  * ```
  */
-export { assembleContext, batchRerank, CharacterChunker, ChunkerRegistry, CohereRelevanceScorer, CrossEncoderReranker, CSVLoader, chunkText, createChunker, createContextWindow, createHybridSearch, createRAGPipeline, createVectorQueryTool, executeWithCircuitBreaker, extractMetadata, formatContextWithCitations, GraphRAG, getAvailableStrategies, getCircuitBreaker, getDefaultChunkerConfig, getRecommendedStrategy, HTMLChunker, HTMLLoader, InMemoryBM25Index, InMemoryVectorStore, JSONChunker as RAGJSONChunker, JSONLoader, LaTeXChunker, LLMMetadataExtractor, linearCombination, loadDocument, loadDocuments, MarkdownChunker, MarkdownLoader, MDocument, PDFLoader, prepareRAGTool, processDocument, RAGCircuitBreaker, RAGCircuitBreakerManager, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
+export { assembleContext, batchRerank, CharacterChunker, ChunkerRegistry, CohereRelevanceScorer, CrossEncoderReranker, CSVLoader, chunkText, createChunker, createContextWindow, createHybridSearch, createRAGPipeline, createVectorQueryTool, executeWithCircuitBreaker, extractMetadata, formatContextWithCitations, GraphRAG, getAvailableStrategies, getCircuitBreaker, getDefaultChunkerConfig, getRecommendedStrategy, HTMLChunker, HTMLLoader, InMemoryBM25Index, InMemoryVectorStore, JSONChunker as RAGJSONChunker, JSONLoader, LaTeXChunker, LLMMetadataExtractor, linearCombination, loadDocument, loadDocuments, MarkdownChunker, MarkdownLoader, MDocument, PDFLoader, prepareRAGTool, processDocument, RAGCircuitBreaker, RAGCircuitBreakerManager, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, ChromaVectorStore, PgVectorStore, PineconeVectorStore, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
 export { ContextBuilder } from "./evaluation/contextBuilder.js";
 export { AuthProviderFactory, createAuthProvider, AuthProviderRegistry, AuthError as AuthErrorFactory, AuthErrorCodes, BaseAuthProvider, InMemorySessionStorage, AuthProviderError, createAuthMiddleware as createAuthProviderMiddleware, createRBACMiddleware, createProtectedMiddleware, createExpressAuthMiddleware, createRequestContext, extractToken, AuthMiddlewareError, AuthMiddlewareErrorCodes, UserRateLimiter, MemoryRateLimitStorage, RedisRateLimitStorage, createRateLimitByUserMiddleware, createAuthenticatedRateLimitMiddleware, createRateLimitStorage, SessionManager, MemorySessionStorage, RedisSessionStorage, createSessionStorage, AuthContextHolder, globalAuthContext, getAuthContext, getCurrentUser, getCurrentSession, isAuthenticated, hasRole, hasAnyRole, hasPermission, hasAllPermissions, requireAuth, requireRole, requirePermission, requireUser, runWithAuthContext, createAuthenticatedContext, RequestContext, NEUROLINK_RESOURCE_ID_KEY, NEUROLINK_THREAD_ID_KEY, createAuthValidatorFromProvider, } from "./auth/index.js";
 export { detectAndRedactPII } from "./utils/piiDetector.js";

package/dist/lib/index.js

@@ -683,7 +683,7 @@ extractMetadata, formatContextWithCitations,
 // Graph RAG
 GraphRAG, getAvailableStrategies, getCircuitBreaker, getDefaultChunkerConfig, getRecommendedStrategy, HTMLChunker, HTMLLoader, InMemoryBM25Index, InMemoryVectorStore, JSONChunker as RAGJSONChunker, JSONLoader, LaTeXChunker, LLMMetadataExtractor, linearCombination, loadDocument, loadDocuments, MarkdownChunker, MarkdownLoader, MDocument, PDFLoader, 
 // RAG Integration for generate/stream
-prepareRAGTool, processDocument, RAGCircuitBreaker, RAGCircuitBreakerManager, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
+prepareRAGTool, processDocument, RAGCircuitBreaker, RAGCircuitBreakerManager, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, ChromaVectorStore, PgVectorStore, PineconeVectorStore, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
 // Legacy RAGAS evaluation classes are now exported from the unified
 // evaluation block above (via ./evaluation/index.js barrel).
 // ContextBuilder is the only class not covered by the barrel export.

package/dist/lib/neurolink.js

@@ -171,7 +171,7 @@ const isNonRetryableProviderError = sharedIsNonRetryableProviderError;
  *
  * Main SDK class providing unified access to 14+ AI providers with enterprise features:
  * - Multi-provider support (OpenAI, Anthropic, Google AI Studio, Google Vertex, AWS Bedrock, etc.)
- * - MCP (Model Context Protocol) tool integration with 58+ external servers
+ * - MCP (Model Context Protocol) tool integration — connect any MCP-compliant server
  * - Human-in-the-Loop (HITL) security workflows for regulated industries
  * - Redis-based conversation memory and persistence
  * - Enterprise middleware system for monitoring and control

package/dist/lib/rag/index.d.ts

@@ -56,6 +56,7 @@ export { prepareRAGTool } from "./ragIntegration.js";
 export { batchRerank, CohereRelevanceScorer, CrossEncoderReranker, createReranker, getAvailableRerankers, getAvailableRerankerTypes, getRegisteredRerankerMetadata, getReranker, getRerankerDefaultConfig, getRerankerMetadata, RerankerFactory, RerankerRegistry, rerank, rerankerFactory, rerankerRegistry, simpleRerank, } from "./reranker/index.js";
 export * from "./resilience/index.js";
 export { createHybridSearch, createVectorQueryTool, InMemoryBM25Index, InMemoryVectorStore, linearCombination, reciprocalRankFusion, } from "./retrieval/index.js";
+export * from "./stores/index.js";
 export * from "../types/index.js";
 import type { Chunk, ChunkingStrategy, ExtractParams } from "../types/index.js";
 /**

package/dist/lib/rag/index.js

@@ -76,6 +76,8 @@ RerankerRegistry, rerank, rerankerFactory, rerankerRegistry, simpleRerank, } fro
 export * from "./resilience/index.js";
 // Retrieval
 export { createHybridSearch, createVectorQueryTool, InMemoryBM25Index, InMemoryVectorStore, linearCombination, reciprocalRankFusion, } from "./retrieval/index.js";
+// Vector store adapters (Pinecone, pgvector, Chroma — client-injection)
+export * from "./stores/index.js";
 // Types
 export * from "../types/index.js";
 // Convenience functions

package/dist/lib/rag/stores/chroma.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Chroma vector store adapter
+ *
+ * Implements the `VectorStore` contract (see `src/lib/types/rag.ts`) against
+ * a Chroma collection. This module has zero runtime dependency on the
+ * `chromadb` package: callers construct their own `ChromaClient` (or any
+ * compatible object) and inject it here. The structural interfaces below
+ * mirror the subset of the `chromadb` API this adapter relies on
+ * (`getOrCreateCollection`, `collection.upsert/query/delete`).
+ *
+ * ## Distance -> similarity scoring
+ *
+ * Chroma returns *distances*, not similarities, and the meaning of that
+ * distance depends entirely on the collection's configured `hnsw:space`
+ * (this adapter does not — and cannot — set that; it is chosen when the
+ * collection is created on the Chroma side). `distanceMetric` tells this
+ * adapter which space the collection uses so it can invert the distance
+ * into a `score` consistent with `InMemoryVectorStore` (higher = more
+ * similar):
+ *
+ * - `"cosine"` (default): Chroma returns `distance = 1 - cosineSimilarity`,
+ *   so `score = 1 - distance` reproduces `InMemoryVectorStore`'s cosine
+ *   score exactly.
+ * - `"ip"`: Chroma returns `distance = 1 - dot(a, b)`, so
+ *   `score = 1 - distance` yields the raw dot product — only equal to
+ *   cosine similarity if both vectors are unit-normalized.
+ * - `"l2"`: Chroma returns squared Euclidean distance, range
+ *   `[0, Infinity)`, which has no exact inverse into a cosine-similarity
+ *   scale. It is converted via `score = 1 / (1 + distance)`, a
+ *   monotonically decreasing-in-distance map into `(0, 1]`. This preserves
+ *   result ordering but is NOT numerically comparable to cosine scores.
+ *
+ * Passing a `distanceMetric` that does not match the collection's actual
+ * `hnsw:space` will silently produce meaningless scores (Chroma has no way
+ * to report its configured space back to the client), so callers must keep
+ * the two in sync.
+ *
+ * ## Metadata round-tripping
+ *
+ * Chroma metadata values must be strings, numbers, or booleans. Values that
+ * are `undefined` are dropped (Chroma rejects `undefined`); any other
+ * non-primitive value (object, array, `null`) is `JSON.stringify`-ed on
+ * write. This is lossy: such values come back as JSON-encoded strings on
+ * read, not their original type. Store only primitive metadata values if
+ * you need exact round-tripping.
+ *
+ * ## indexName -> collection mapping
+ *
+ * `indexName` is used verbatim as the Chroma collection name (1:1,
+ * lazily created via `getOrCreateCollection` and cached for the lifetime of
+ * this adapter instance).
+ */
+import type { ChromaClientLike, ChromaVectorStoreOptions, ChromaWhere, MetadataFilter, VectorQueryResult, VectorStore } from "../../types/index.js";
+/**
+ * Translates a `MetadataFilter` into a Chroma `where` clause.
+ *
+ * Throws a clear error for any operator Chroma's metadata `where` clause
+ * cannot express ($not, $nor, $exists, $contains, $regex, $size) rather than
+ * silently dropping the constraint and mis-filtering results.
+ */
+export declare function translateMetadataFilter(filter: MetadataFilter): ChromaWhere;
+export declare class ChromaVectorStore implements VectorStore {
+    private readonly client;
+    private readonly collections;
+    private readonly distanceMetric;
+    constructor(client: ChromaClientLike, options?: ChromaVectorStoreOptions);
+    private getCollection;
+    /**
+     * Add or update vectors in an index (Chroma collection).
+     */
+    upsert(indexName: string, items: Array<{
+        id: string;
+        vector: number[];
+        metadata?: Record<string, unknown>;
+    }>): Promise<void>;
+    /**
+     * Query vectors by similarity.
+     */
+    query(params: {
+        indexName: string;
+        queryVector: number[];
+        topK?: number;
+        filter?: MetadataFilter;
+        includeVectors?: boolean;
+    }): Promise<VectorQueryResult[]>;
+    /**
+     * Delete vectors from an index (Chroma collection) by id.
+     */
+    delete(indexName: string, ids: string[]): Promise<void>;
+}

package/dist/lib/rag/stores/chroma.js

@@ -0,0 +1,281 @@
+/**
+ * Chroma vector store adapter
+ *
+ * Implements the `VectorStore` contract (see `src/lib/types/rag.ts`) against
+ * a Chroma collection. This module has zero runtime dependency on the
+ * `chromadb` package: callers construct their own `ChromaClient` (or any
+ * compatible object) and inject it here. The structural interfaces below
+ * mirror the subset of the `chromadb` API this adapter relies on
+ * (`getOrCreateCollection`, `collection.upsert/query/delete`).
+ *
+ * ## Distance -> similarity scoring
+ *
+ * Chroma returns *distances*, not similarities, and the meaning of that
+ * distance depends entirely on the collection's configured `hnsw:space`
+ * (this adapter does not — and cannot — set that; it is chosen when the
+ * collection is created on the Chroma side). `distanceMetric` tells this
+ * adapter which space the collection uses so it can invert the distance
+ * into a `score` consistent with `InMemoryVectorStore` (higher = more
+ * similar):
+ *
+ * - `"cosine"` (default): Chroma returns `distance = 1 - cosineSimilarity`,
+ *   so `score = 1 - distance` reproduces `InMemoryVectorStore`'s cosine
+ *   score exactly.
+ * - `"ip"`: Chroma returns `distance = 1 - dot(a, b)`, so
+ *   `score = 1 - distance` yields the raw dot product — only equal to
+ *   cosine similarity if both vectors are unit-normalized.
+ * - `"l2"`: Chroma returns squared Euclidean distance, range
+ *   `[0, Infinity)`, which has no exact inverse into a cosine-similarity
+ *   scale. It is converted via `score = 1 / (1 + distance)`, a
+ *   monotonically decreasing-in-distance map into `(0, 1]`. This preserves
+ *   result ordering but is NOT numerically comparable to cosine scores.
+ *
+ * Passing a `distanceMetric` that does not match the collection's actual
+ * `hnsw:space` will silently produce meaningless scores (Chroma has no way
+ * to report its configured space back to the client), so callers must keep
+ * the two in sync.
+ *
+ * ## Metadata round-tripping
+ *
+ * Chroma metadata values must be strings, numbers, or booleans. Values that
+ * are `undefined` are dropped (Chroma rejects `undefined`); any other
+ * non-primitive value (object, array, `null`) is `JSON.stringify`-ed on
+ * write. This is lossy: such values come back as JSON-encoded strings on
+ * read, not their original type. Store only primitive metadata values if
+ * you need exact round-tripping.
+ *
+ * ## indexName -> collection mapping
+ *
+ * `indexName` is used verbatim as the Chroma collection name (1:1,
+ * lazily created via `getOrCreateCollection` and cached for the lifetime of
+ * this adapter instance).
+ */
+// Structural Chroma client/collection types (`ChromaClientLike`,
+// `ChromaCollectionLike`, `ChromaUpsertParams`, etc.) live in
+// `src/lib/types/vectorStoreChroma.ts` per this repo's canonical-type-
+// location rule (see CLAUDE.md Critical Rules 2 & 12) and are imported from
+// the types barrel above. This file only re-exports runtime values
+// (`ChromaVectorStore`, `translateMetadataFilter`) — consumers who need the
+// structural types should import them from `@juspay/neurolink` (root) or
+// the types barrel directly, per Critical Rule 13.
+// ---------------------------------------------------------------------------
+// MetadataFilter -> Chroma `where` translation
+// ---------------------------------------------------------------------------
+const CHROMA_SUPPORTED_FIELD_OPS = new Set([
+    "$eq",
+    "$ne",
+    "$gt",
+    "$gte",
+    "$lt",
+    "$lte",
+    "$in",
+    "$nin",
+]);
+const CHROMA_UNSUPPORTED_FIELD_OP_REASONS = {
+    $exists: 'Chroma metadata filtering has no existence check on the "where" clause.',
+    $contains: 'Chroma metadata filtering has no substring-match operator on the "where" clause (Chroma\'s substring matching only applies to document text via "where_document", not metadata field values).',
+    $regex: 'Chroma metadata filtering has no regular-expression operator on the "where" clause.',
+    $size: 'Chroma metadata filtering has no array-length operator on the "where" clause.',
+};
+function unsupportedFieldOpError(opKey, field) {
+    const reason = CHROMA_UNSUPPORTED_FIELD_OP_REASONS[opKey] ??
+        `Chroma metadata filtering does not support the "${opKey}" operator on the "where" clause.`;
+    return new Error(`Unsupported operator "${opKey}" (field "${field}"): ${reason}`);
+}
+/**
+ * Translates a field-level filter value (either a direct-equality primitive
+ * or an operator bag) into a Chroma `where` clause fragment for that field.
+ *
+ * Returns `undefined` when the filter value carries no enforceable
+ * constraint (an array, or an operator bag with no recognized keys) — this
+ * mirrors `InMemoryVectorStore.matchesFilter`, which treats any non-null
+ * object value as an "operator bag" and silently applies none of its checks
+ * when no recognized `$`-key is present, i.e. the field matches
+ * unconditionally. Omitting the field from the Chroma `where` clause
+ * reproduces that same "always matches" behavior.
+ */
+function translateFieldFilter(field, value) {
+    if (Array.isArray(value)) {
+        return undefined;
+    }
+    if (value === null || typeof value !== "object") {
+        return { [field]: { $eq: value } };
+    }
+    const ops = value;
+    const opKeys = Object.keys(ops);
+    if (opKeys.length === 0) {
+        return undefined;
+    }
+    const chromaOps = {};
+    for (const opKey of opKeys) {
+        if (!CHROMA_SUPPORTED_FIELD_OPS.has(opKey)) {
+            throw unsupportedFieldOpError(opKey, field);
+        }
+        chromaOps[opKey] = ops[opKey];
+    }
+    return { [field]: chromaOps };
+}
+function translateLogicalOperator(key, value) {
+    switch (key) {
+        case "$and":
+            return {
+                $and: value.map(translateMetadataFilter),
+            };
+        case "$or":
+            return {
+                $or: value.map(translateMetadataFilter),
+            };
+        case "$not":
+            throw new Error('Chroma metadata filtering has no negation operator on the "where" clause; "$not" cannot be translated. Rewrite the filter using $ne/$nin instead.');
+        case "$nor":
+            throw new Error('"$nor" is declared on MetadataFilter but is not implemented by InMemoryVectorStore either, and Chroma has no negation operator on the "where" clause. Rewrite using $and of $ne/$nin clauses.');
+        default:
+            throw new Error(`Unknown logical operator "${key}" in MetadataFilter.`);
+    }
+}
+/**
+ * Translates a `MetadataFilter` into a Chroma `where` clause.
+ *
+ * Throws a clear error for any operator Chroma's metadata `where` clause
+ * cannot express ($not, $nor, $exists, $contains, $regex, $size) rather than
+ * silently dropping the constraint and mis-filtering results.
+ */
+export function translateMetadataFilter(filter) {
+    const clauses = [];
+    for (const [key, value] of Object.entries(filter)) {
+        const clause = key.startsWith("$")
+            ? translateLogicalOperator(key, value)
+            : translateFieldFilter(key, value);
+        if (clause !== undefined) {
+            clauses.push(clause);
+        }
+    }
+    if (clauses.length === 0) {
+        return {};
+    }
+    if (clauses.length === 1) {
+        return clauses[0];
+    }
+    // Chroma requires a single top-level operator; combine multiple field/
+    // logical clauses with an explicit $and (mirrors matchesFilter ANDing
+    // every top-level entry).
+    return { $and: clauses };
+}
+// ---------------------------------------------------------------------------
+// Metadata <-> Chroma metadata conversion
+// ---------------------------------------------------------------------------
+function toChromaMetadataValue(value) {
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    // Chroma metadata values must be string | number | boolean. Non-primitive
+    // values (object, array, null) are JSON-stringified — lossy on read back,
+    // see module doc comment.
+    return JSON.stringify(value);
+}
+function toChromaMetadata(metadata) {
+    const result = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (value === undefined) {
+            // Chroma rejects `undefined` metadata values outright.
+            continue;
+        }
+        result[key] = toChromaMetadataValue(value);
+    }
+    return result;
+}
+function distanceToScore(distance, metric) {
+    switch (metric) {
+        case "cosine":
+        case "ip":
+            return 1 - distance;
+        case "l2":
+            return 1 / (1 + distance);
+        default: {
+            const exhaustive = metric;
+            throw new Error(`Unknown Chroma distance metric: ${String(exhaustive)}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// ChromaVectorStore
+// ---------------------------------------------------------------------------
+export class ChromaVectorStore {
+    client;
+    collections = new Map();
+    distanceMetric;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.distanceMetric = options.distanceMetric ?? "cosine";
+    }
+    getCollection(indexName) {
+        let collection = this.collections.get(indexName);
+        if (!collection) {
+            collection = this.client.getOrCreateCollection({ name: indexName });
+            this.collections.set(indexName, collection);
+        }
+        return collection;
+    }
+    /**
+     * Add or update vectors in an index (Chroma collection).
+     */
+    async upsert(indexName, items) {
+        if (items.length === 0) {
+            return;
+        }
+        const collection = await this.getCollection(indexName);
+        await collection.upsert({
+            ids: items.map((item) => item.id),
+            embeddings: items.map((item) => item.vector),
+            metadatas: items.map((item) => toChromaMetadata(item.metadata ?? {})),
+        });
+    }
+    /**
+     * Query vectors by similarity.
+     */
+    async query(params) {
+        const { indexName, queryVector, topK = 10, filter, includeVectors = false, } = params;
+        const collection = await this.getCollection(indexName);
+        const include = ["metadatas", "distances"];
+        if (includeVectors) {
+            include.push("embeddings");
+        }
+        const response = await collection.query({
+            queryEmbeddings: [queryVector],
+            nResults: topK,
+            ...(filter ? { where: translateMetadataFilter(filter) } : {}),
+            include,
+        });
+        const ids = response.ids[0] ?? [];
+        const metadatasRow = response.metadatas?.[0] ?? [];
+        const distancesRow = response.distances?.[0] ?? [];
+        const embeddingsRow = response.embeddings?.[0] ?? [];
+        return ids.map((id, i) => {
+            const metadata = (metadatasRow[i] ?? {});
+            const distance = distancesRow[i];
+            const score = distance === null || distance === undefined
+                ? undefined
+                : distanceToScore(distance, this.distanceMetric);
+            return {
+                id,
+                score,
+                text: metadata.text,
+                metadata,
+                ...(includeVectors ? { vector: embeddingsRow[i] ?? [] } : {}),
+            };
+        });
+    }
+    /**
+     * Delete vectors from an index (Chroma collection) by id.
+     */
+    async delete(indexName, ids) {
+        if (ids.length === 0) {
+            return;
+        }
+        const collection = await this.getCollection(indexName);
+        await collection.delete({ ids });
+    }
+}
+//# sourceMappingURL=chroma.js.map

package/dist/lib/rag/stores/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Vector Store Adapters
+ *
+ * Client-injection adapters implementing the `VectorStore` contract
+ * (see `src/lib/types/rag.ts`) against real vector database backends.
+ * Each adapter accepts an already-constructed vendor client typed as a
+ * minimal structural interface — no vendor SDK is a runtime dependency
+ * of this package; callers bring their own client instance.
+ *
+ * @example
+ * ```typescript
+ * import { PineconeVectorStore } from '@juspay/neurolink/rag';
+ * import { Pinecone } from '@pinecone-database/pinecone';
+ *
+ * const client = new Pinecone({ apiKey: '...' });
+ * const store = new PineconeVectorStore(client.index('my-index'));
+ * ```
+ */
+export * from "./pinecone.js";
+export * from "./pgvector.js";
+export * from "./chroma.js";

package/dist/lib/rag/stores/index.js

@@ -0,0 +1,22 @@
+/**
+ * Vector Store Adapters
+ *
+ * Client-injection adapters implementing the `VectorStore` contract
+ * (see `src/lib/types/rag.ts`) against real vector database backends.
+ * Each adapter accepts an already-constructed vendor client typed as a
+ * minimal structural interface — no vendor SDK is a runtime dependency
+ * of this package; callers bring their own client instance.
+ *
+ * @example
+ * ```typescript
+ * import { PineconeVectorStore } from '@juspay/neurolink/rag';
+ * import { Pinecone } from '@pinecone-database/pinecone';
+ *
+ * const client = new Pinecone({ apiKey: '...' });
+ * const store = new PineconeVectorStore(client.index('my-index'));
+ * ```
+ */
+export * from "./pinecone.js";
+export * from "./pgvector.js";
+export * from "./chroma.js";
+//# sourceMappingURL=index.js.map