@juspay/neurolink 9.89.0 → 9.90.0

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

@@ -0,0 +1,159 @@
+/**
+ * Pinecone Vector Store Adapter
+ *
+ * Implements the `VectorStore` contract (see `src/lib/types/rag.ts`) against
+ * a Pinecone index, using client injection: callers construct their own
+ * `@pinecone-database/pinecone` client/index and pass it in. No Pinecone SDK
+ * is a runtime dependency of this package — `PineconeIndexLike` below is a
+ * minimal structural interface satisfied by the real `Index` object (and by
+ * hand-written mocks in tests).
+ *
+ * ## indexName -> namespace mapping
+ *
+ * The `VectorStore` contract's `indexName` parameter is mapped onto a
+ * Pinecone **namespace**, not a Pinecone index. Pinecone ties one client
+ * `Index` object to a single physical index (created ahead of time via
+ * Pinecone's control-plane API); namespaces are Pinecone's mechanism for
+ * partitioning data *within* that one index, and are the closest match to
+ * this SDK's per-call `indexName` concept.
+ *
+ * - If the injected client exposes `.namespace(name)` (as the real
+ *   `@pinecone-database/pinecone` `Index.namespace()` does), every
+ *   query/upsert/delete call routes through `client.namespace(indexName)`.
+ * - If the injected client does not expose `.namespace` (e.g. a caller
+ *   already pre-scoped their client to a fixed namespace, or a minimal
+ *   mock), calls go straight to the injected client and `indexName` has
+ *   no further effect. Document this for your callers if you construct a
+ *   `PineconeVectorStore` from a namespace-fixed client.
+ *
+ * ## Metadata filter translation
+ *
+ * `MetadataFilter` (Mongo/Sift-style) is translated to Pinecone's native
+ * filter DSL, which already shares the same `$op` shape for comparison
+ * operators. Supported operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`,
+ * `$lte`, `$in`, `$nin` (field-level) and `$and` / `$or` (logical,
+ * recursively translated). Any other operator — `$not`, `$nor`, `$exists`,
+ * `$contains`, `$regex`, `$size` — has no Pinecone equivalent and throws a
+ * clear `Error` naming the offending operator/field rather than silently
+ * mis-filtering (Pinecone's filter DSL has no negation, existence, string
+ * containment, regex, or array-length operators).
+ */
+/** Comparison operators Pinecone's filter DSL can express, verbatim. */
+const SUPPORTED_COMPARISON_OPS = new Set([
+    "$eq",
+    "$ne",
+    "$gt",
+    "$gte",
+    "$lt",
+    "$lte",
+    "$in",
+    "$nin",
+]);
+/** Logical operators Pinecone's filter DSL can express, verbatim. */
+const SUPPORTED_LOGICAL_OPS = new Set(["$and", "$or"]);
+/**
+ * Translate a `MetadataFilter` into Pinecone's native filter object.
+ *
+ * Throws a descriptive `Error` for any operator Pinecone cannot express
+ * ($not, $nor, $exists, $contains, $regex, $size) instead of silently
+ * dropping or mis-applying it.
+ */
+export function translatePineconeFilter(filter) {
+    const result = {};
+    for (const [key, value] of Object.entries(filter)) {
+        if (key.startsWith("$")) {
+            if (!SUPPORTED_LOGICAL_OPS.has(key)) {
+                throw new Error(`PineconeVectorStore: MetadataFilter operator "${key}" cannot be translated to Pinecone's filter DSL ` +
+                    `(supported logical operators: ${[...SUPPORTED_LOGICAL_OPS].join(", ")}). ` +
+                    `Restructure the filter to avoid "${key}".`);
+            }
+            const subFilters = value;
+            result[key] = subFilters.map((sub) => translatePineconeFilter(sub));
+            continue;
+        }
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            const ops = value;
+            const translatedOps = {};
+            for (const opKey of Object.keys(ops)) {
+                if (!SUPPORTED_COMPARISON_OPS.has(opKey)) {
+                    throw new Error(`PineconeVectorStore: MetadataFilter operator "${opKey}" on field "${key}" cannot be translated to ` +
+                        `Pinecone's filter DSL (supported: ${[...SUPPORTED_COMPARISON_OPS].join(", ")}). ` +
+                        `Restructure the filter to avoid "${opKey}" on "${key}".`);
+                }
+                translatedOps[opKey] = ops[opKey];
+            }
+            result[key] = translatedOps;
+        }
+        else {
+            // Primitive/array/null value: Pinecone treats a bare value as
+            // implicit equality, matching InMemoryVectorStore's direct-equality
+            // fallback for non-object filter values.
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Pinecone-backed implementation of the `VectorStore` contract.
+ *
+ * @example
+ * ```typescript
+ * import { Pinecone } from '@pinecone-database/pinecone';
+ * import { PineconeVectorStore } from '@juspay/neurolink/rag';
+ *
+ * const client = new Pinecone({ apiKey: process.env.PINECONE_API_KEY! });
+ * const store = new PineconeVectorStore(client.index('my-index'));
+ *
+ * await store.upsert('tenant-a', [{ id: '1', vector: [...], metadata: { text: 'hello' } }]);
+ * const results = await store.query({ indexName: 'tenant-a', queryVector: [...], topK: 5 });
+ * ```
+ */
+export class PineconeVectorStore {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Resolve the Pinecone client scoped to `indexName` (see class docs re: namespace mapping). */
+    resolveClient(indexName) {
+        return this.client.namespace
+            ? this.client.namespace(indexName)
+            : this.client;
+    }
+    async query(params) {
+        const { indexName, queryVector, topK = 10, filter, includeVectors = false, } = params;
+        const target = this.resolveClient(indexName);
+        const response = await target.query({
+            vector: queryVector,
+            topK,
+            ...(filter ? { filter: translatePineconeFilter(filter) } : {}),
+            includeMetadata: true,
+            includeValues: includeVectors,
+        });
+        const matches = response.matches ?? [];
+        return matches.map((match) => {
+            const metadata = match.metadata ?? {};
+            return {
+                id: match.id,
+                score: match.score,
+                text: metadata.text,
+                metadata,
+                ...(includeVectors && match.values ? { vector: match.values } : {}),
+            };
+        });
+    }
+    /** Add or update vectors in the namespace mapped from `indexName`. */
+    async upsert(indexName, items) {
+        const target = this.resolveClient(indexName);
+        await target.upsert(items.map((item) => ({
+            id: item.id,
+            values: item.vector,
+            metadata: item.metadata ?? {},
+        })));
+    }
+    /** Delete vectors by id from the namespace mapped from `indexName`. */
+    async delete(indexName, ids) {
+        const target = this.resolveClient(indexName);
+        await target.deleteMany(ids);
+    }
+}
+//# sourceMappingURL=pinecone.js.map

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

@@ -54,6 +54,8 @@ export * from "./taskClassification.js";
 export * from "./toolDedup.js";
 export * from "./toolRouting.js";
 export * from "./tools.js";
+export * from "./vectorStoreChroma.js";
+export * from "./vectorStorePinecone.js";
 export * from "./voice.js";
 export * from "./universalProviderOptions.js";
 export * from "./utilities.js";

package/dist/lib/types/index.js

@@ -55,6 +55,8 @@ export * from "./taskClassification.js";
 export * from "./toolDedup.js";
 export * from "./toolRouting.js";
 export * from "./tools.js";
+export * from "./vectorStoreChroma.js";
+export * from "./vectorStorePinecone.js";
 export * from "./voice.js";
 export * from "./universalProviderOptions.js";
 export * from "./utilities.js";

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

@@ -419,6 +419,36 @@ export type VectorStore = {
         includeVectors?: boolean;
     }): Promise<VectorQueryResult[]>;
 };
+/** Minimal shape of a query result, satisfied by both `pg` and `pglite`. */
+export type PgQueryResult<T = unknown> = {
+    rows: T[];
+};
+/**
+ * Minimal structural interface a caller-supplied Postgres client must
+ * satisfy. Both `pg.Pool` (`node-postgres`) and `@electric-sql/pglite`
+ * instances already expose a compatible `query(text, values?)` method —
+ * neither is a dependency of this package. Callers construct and own the
+ * client; `PgVectorStore` only ever calls `query()` on it.
+ */
+export type PgClientLike = {
+    query(text: string, values?: unknown[]): Promise<PgQueryResult>;
+};
+/** Construction options for `PgVectorStore`. */
+export type PgVectorStoreOptions = {
+    /**
+     * Prefix prepended to `indexName` to derive the backing table name.
+     * Must itself be a valid, unquoted Postgres identifier.
+     * @default "neurolink_vs_"
+     */
+    tablePrefix?: string;
+};
+/** Row shape returned by `PgVectorStore`'s SELECT queries. */
+export type PgVectorStoreRow = {
+    id: string;
+    metadata: unknown;
+    score: unknown;
+    embedding?: unknown;
+};
 /**
  * Document loader options
  */

package/dist/lib/types/vectorStoreChroma.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Structural types for the Chroma vector store adapter
+ * (`src/lib/rag/stores/chroma.ts`).
+ *
+ * These mirror the subset of the `chromadb` package's API the adapter
+ * calls (`ChromaClient.getOrCreateCollection`, `Collection.upsert/query/
+ * delete`). NeuroLink has zero runtime dependency on `chromadb` — callers
+ * construct their own client and inject an object satisfying
+ * `ChromaClientLike`.
+ */
+export type ChromaMetadataValue = string | number | boolean;
+export type ChromaMetadata = Record<string, ChromaMetadataValue>;
+/** Chroma's metadata `where` filter payload shape. */
+export type ChromaWhere = Record<string, unknown>;
+export type ChromaIncludeField = "embeddings" | "metadatas" | "documents" | "distances";
+export type ChromaUpsertParams = {
+    ids: string[];
+    embeddings?: number[][];
+    metadatas?: Array<ChromaMetadata | null>;
+    documents?: Array<string | null>;
+};
+export type ChromaQueryParams = {
+    queryEmbeddings: number[][];
+    nResults?: number;
+    where?: ChromaWhere;
+    include?: ChromaIncludeField[];
+};
+export type ChromaQueryResponse = {
+    ids: string[][];
+    embeddings?: Array<Array<number[] | null>> | null;
+    metadatas?: Array<Array<ChromaMetadata | null>> | null;
+    documents?: Array<Array<string | null>> | null;
+    distances?: Array<Array<number | null>> | null;
+};
+export type ChromaDeleteParams = {
+    ids?: string[];
+    where?: ChromaWhere;
+};
+/**
+ * Minimal structural interface for a Chroma collection handle, matching the
+ * subset of `Collection` (from `chromadb`) the adapter calls.
+ */
+export type ChromaCollectionLike = {
+    upsert(params: ChromaUpsertParams): Promise<unknown>;
+    query(params: ChromaQueryParams): Promise<ChromaQueryResponse>;
+    delete(params: ChromaDeleteParams): Promise<unknown>;
+};
+/**
+ * Minimal structural interface for a Chroma client, matching the subset of
+ * `ChromaClient` (from `chromadb`) the adapter calls.
+ */
+export type ChromaClientLike = {
+    getOrCreateCollection(params: {
+        name: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<ChromaCollectionLike>;
+};
+export type ChromaDistanceMetric = "cosine" | "l2" | "ip";
+export type ChromaVectorStoreOptions = {
+    /**
+     * The distance metric configured on the underlying Chroma collection(s)
+     * (Chroma's `hnsw:space`). Used only to convert returned distances into a
+     * `score`; see `src/lib/rag/stores/chroma.ts` module doc comment.
+     * Defaults to `"cosine"`.
+     */
+    distanceMetric?: ChromaDistanceMetric;
+};

package/dist/lib/types/vectorStoreChroma.js

@@ -0,0 +1,12 @@
+/**
+ * Structural types for the Chroma vector store adapter
+ * (`src/lib/rag/stores/chroma.ts`).
+ *
+ * These mirror the subset of the `chromadb` package's API the adapter
+ * calls (`ChromaClient.getOrCreateCollection`, `Collection.upsert/query/
+ * delete`). NeuroLink has zero runtime dependency on `chromadb` — callers
+ * construct their own client and inject an object satisfying
+ * `ChromaClientLike`.
+ */
+export {};
+//# sourceMappingURL=vectorStoreChroma.js.map

package/dist/lib/types/vectorStorePinecone.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Structural types for the Pinecone vector store adapter
+ * (`src/lib/rag/stores/pinecone.ts`).
+ *
+ * These mirror the subset of the `@pinecone-database/pinecone` package's API
+ * the adapter calls (`Index.query/upsert/deleteMany`, optional
+ * `Index.namespace`). NeuroLink has zero runtime dependency on the Pinecone
+ * SDK — callers construct their own client/index and inject an object
+ * satisfying `PineconeIndexLike`.
+ */
+/** A single scored match as returned by Pinecone's query API. */
+export type PineconeMatch = {
+    id: string;
+    score?: number;
+    values?: number[];
+    metadata?: Record<string, unknown>;
+};
+/** Shape of the response returned by `PineconeIndexLike.query()`. */
+export type PineconeQueryResponse = {
+    matches?: PineconeMatch[];
+};
+/** Request payload accepted by `PineconeIndexLike.query()`. */
+export type PineconeQueryRequest = {
+    vector: number[];
+    topK: number;
+    filter?: Record<string, unknown>;
+    includeMetadata?: boolean;
+    includeValues?: boolean;
+};
+/** A single record accepted by `PineconeIndexLike.upsert()`. */
+export type PineconeUpsertRecord = {
+    id: string;
+    values: number[];
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Minimal structural interface modeled on the `@pinecone-database/pinecone`
+ * `Index` object. Satisfied by the real SDK's `Index` without modification;
+ * callers never need to install the Pinecone SDK as a dependency of this
+ * package — they bring their own already-constructed client instance.
+ */
+export type PineconeIndexLike = {
+    /** Returns a client scoped to the given namespace, if the client supports namespacing. */
+    namespace?(ns: string): PineconeIndexLike;
+    query(request: PineconeQueryRequest): Promise<PineconeQueryResponse>;
+    upsert(records: PineconeUpsertRecord[]): Promise<unknown>;
+    deleteMany(ids: string[]): Promise<unknown>;
+};

package/dist/lib/types/vectorStorePinecone.js

@@ -0,0 +1,12 @@
+/**
+ * Structural types for the Pinecone vector store adapter
+ * (`src/lib/rag/stores/pinecone.ts`).
+ *
+ * These mirror the subset of the `@pinecone-database/pinecone` package's API
+ * the adapter calls (`Index.query/upsert/deleteMany`, optional
+ * `Index.namespace`). NeuroLink has zero runtime dependency on the Pinecone
+ * SDK — callers construct their own client/index and inject an object
+ * satisfying `PineconeIndexLike`.
+ */
+export {};
+//# sourceMappingURL=vectorStorePinecone.js.map

package/dist/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/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/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>;
+}