@juspay/neurolink 9.89.0 → 9.91.0

package/dist/neurolink.js

@@ -83,7 +83,10 @@ import { resolveModel } from "./utils/modelAliasResolver.js";
 // Import orchestration components
 import { ModelRouter } from "./utils/modelRouter.js";
 import { getBestProvider } from "./utils/providerUtils.js";
-import { isZodSchema } from "./utils/schemaConversion.js";
+import { isZodSchema, convertZodToJsonSchema, } from "./utils/schemaConversion.js";
+import { resolveToolPolicy } from "./tools/toolPolicy.js";
+import { applyToolGate } from "./tools/toolGate.js";
+import { directAgentTools } from "./agent/directTools.js";
 import { BinaryTaskClassifier } from "./utils/taskClassifier.js";
 // Tool detection and execution imports
 // Transformation utilities
@@ -284,6 +287,30 @@ export function markStreamProviderEmittedGenerationEnd(options) {
  * survives minification AND doesn't rely on method-name stability.
  */
 export const NEUROLINK_BRAND = Symbol.for("@juspay/neurolink/sdk-brand");
+/**
+ * Providers whose native tool-calling support is model-dependent or absent —
+ * i.e. every provider that overrides `supportsTools()` and can return false
+ * (verified against src/lib/providers: ollama and openrouter are
+ * model-dependent; huggingface is deployment-dependent; the rest are
+ * image/embedding providers). Only these still receive the full tool listing
+ * in the system prompt on the generate path, where no provider instance
+ * exists yet to ask directly; every other provider gets tool definitions
+ * natively via its `tools` parameter, so repeating them in the prompt was
+ * pure token duplication. The stream path asks the provider instance
+ * (`provider.supportsTools()`) instead of this list. Keep in sync with
+ * `supportsTools()` overrides when adding providers.
+ */
+const PROMPT_ONLY_TOOL_PROVIDERS = new Set([
+    "ollama",
+    "huggingface",
+    "openrouter",
+    "ideogram",
+    "recraft",
+    "replicate",
+    "stability",
+    "jina",
+    "voyage",
+]);
 /**
  * Type-guard for opaque values that should be a {@link NeuroLink} instance.
  *
@@ -379,6 +406,9 @@ export class NeuroLink {
     toolRoutingVectorCache;
     // Opt-in tool-signature deduplication config.
     toolDedupConfig;
+    toolsConfig;
+    /** Session-scoped pins of tools discovered via search_tools (tools.discovery mode). */
+    discoveryPins = new Map();
     // Add orchestration property
     enableOrchestration;
     // Authentication provider for secure access control
@@ -807,6 +837,11 @@ export class NeuroLink {
         if (config?.toolDedup) {
             this.toolDedupConfig = { ...config.toolDedup };
         }
+        if (config?.tools) {
+            // Shallow-clone so later caller mutations of the config object don't
+            // change this instance's tool policy mid-flight.
+            this.toolsConfig = { ...config.tools };
+        }
         // ModelPool: build one instance from config; null when not configured.
         this.modelPool = config?.modelPool ? new ModelPool(config.modelPool) : null;
         // RequestRouter: store the host-supplied function; null when not configured.
@@ -1108,10 +1143,15 @@ export class NeuroLink {
         // Use void to handle async registration without blocking constructor
         const registrations = Object.entries(fileTools).map(async ([toolName, toolDef]) => {
             const toolId = `direct.${toolName}`;
+            // Register the real parameter schema (converted from Zod) instead of a
+            // `{}` placeholder so tool listings and token-budget accounting see the
+            // schema that actually ships to providers.
+            const fileToolSchema = convertZodToJsonSchema((toolDef.inputSchema ??
+                toolDef.parameters));
             const toolInfo = {
                 name: toolName,
                 description: toolDef.description || `File tool: ${toolName}`,
-                inputSchema: {},
+                inputSchema: fileToolSchema,
                 serverId: "direct",
                 category: "built-in",
             };
@@ -5143,10 +5183,21 @@ Current user's request: ${currentInput}`;
         const circuitBreakerNote = unavailableTools.length > 0
             ? `\n\nNOTE: The following tools are temporarily unavailable due to repeated failures: ${unavailableTools.join(", ")}. Do not attempt to call these tools.`
             : "";
+        // Circuit-breaker-open tools are ENFORCED out of the native tool set via
+        // the per-call denylist — asking the model nicely (the note above) is
+        // informational, exclusion is the guarantee. Previously only the
+        // system-prompt listing was filtered; the native array still shipped them.
+        if (unavailableTools.length > 0) {
+            options.excludeTools = [
+                ...new Set([...(options.excludeTools ?? []), ...unavailableTools]),
+            ];
+        }
+        // Providers with native tool calling receive full definitions via their
+        // `tools` parameter; only prompt-based providers still get the listing.
+        const nativeToolSupport = !PROMPT_ONLY_TOOL_PROVIDERS.has(String(providerName).toLowerCase());
         const enhancedSystemPrompt = options.skipToolPromptInjection
             ? (options.systemPrompt || "") + circuitBreakerNote
-            : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools) +
-                circuitBreakerNote;
+            : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools, nativeToolSupport) + circuitBreakerNote;
         logger.debug("Tool-aware system prompt created", {
             requestId,
             originalPromptLength: options.systemPrompt?.length || 0,
@@ -5900,48 +5951,64 @@ Current user's request: ${currentInput}`;
     /**
      * Apply per-call tool filtering (whitelist/blacklist) to a ToolInfo array.
      * Used to filter the tool list before building the system prompt.
+     *
+     * Resolves the SAME policy as the native gate (`BaseProvider`
+     * `applyToolFiltering`) — per-call options plus the instance-level `tools`
+     * config — so what the model is told about tools never diverges from the
+     * tools it can actually call.
      */
     applyToolInfoFiltering(tools, options) {
-        // enabledToolNames is an additional whitelist — merged into toolFilter
-        const whitelist = [
-            ...(options.toolFilter ?? []),
-            ...(options.enabledToolNames ?? []),
-        ];
-        if (whitelist.length === 0 &&
-            (!options.excludeTools || options.excludeTools.length === 0)) {
-            return tools;
-        }
-        let filtered = tools;
-        if (whitelist.length > 0) {
-            const allowSet = new Set(whitelist);
-            filtered = filtered.filter((t) => allowSet.has(t.name));
-        }
-        if (options.excludeTools && options.excludeTools.length > 0) {
-            const denySet = new Set(options.excludeTools);
-            filtered = filtered.filter((t) => !denySet.has(t.name));
+        const policy = resolveToolPolicy({
+            options: {
+                disableTools: options.disableTools,
+                toolFilter: options.toolFilter,
+                enabledToolNames: options.enabledToolNames,
+                excludeTools: options.excludeTools,
+            },
+            instanceConfig: this.toolsConfig,
+            builtinToolNames: Object.keys(directAgentTools),
+        });
+        const record = {};
+        for (const tool of tools) {
+            if (!(tool.name in record)) {
+                record[tool.name] = tool;
+            }
         }
+        const gated = applyToolGate(record, policy);
+        const filtered = tools.filter((t) => t.name in gated);
         if (filtered.length !== tools.length) {
             logger.debug(`Tool info filtering applied for system prompt`, {
                 beforeCount: tools.length,
                 afterCount: filtered.length,
+                policySources: policy.sources,
                 toolFilter: options.toolFilter,
                 excludeTools: options.excludeTools,
             });
         }
         return filtered;
     }
-    createToolAwareSystemPrompt(originalSystemPrompt, availableTools) {
+    createToolAwareSystemPrompt(originalSystemPrompt, availableTools, nativeToolSupport) {
         // AI prompt generation with tool analysis and structured logging
         const promptGenerationData = {
             originalPromptLength: originalSystemPrompt?.length || 0,
             availableToolsCount: availableTools.length,
             hasOriginalPrompt: !!originalSystemPrompt,
+            nativeToolSupport,
         };
         logger.debug("AI prompt generation with tool schemas", promptGenerationData);
         if (availableTools.length === 0) {
             logger.debug("No tools available - returning original prompt");
             return originalSystemPrompt || "";
         }
+        if (nativeToolSupport) {
+            // The provider receives full tool definitions natively via its `tools`
+            // parameter — repeating name/description/parameters here was pure
+            // duplication (~850 tokens on the default surface, tens of thousands
+            // with MCP servers attached). Keep only a short, static (cache-stable)
+            // damping line so models don't over-reach for tools.
+            return ((originalSystemPrompt || "") +
+                "\n\nTools are available via native tool calling. Use them only when they genuinely improve your response; for creative or conversational requests, respond naturally without tools.");
+        }
         const toolDescriptions = transformToolsToDescriptions(availableTools.map((t) => ({
             name: t.name,
             description: t.description ?? "",
@@ -7746,10 +7813,13 @@ Current user's request: ${currentInput}`;
         let availableTools = await this.getAllAvailableTools();
         // Apply per-call tool filtering for system prompt tool descriptions
         availableTools = this.applyToolInfoFiltering(availableTools, options);
-        // Skip tool prompt injection if skipToolPromptInjection is true
+        // Skip tool prompt injection if skipToolPromptInjection is true.
+        // For providers with native tool calling (instance truth via
+        // supportsTools()), the listing is skipped and only the short damping
+        // line is appended — full definitions ship natively via `tools`.
         const enhancedSystemPrompt = options.skipToolPromptInjection
             ? options.systemPrompt || ""
-            : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools);
+            : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools, provider.supportsTools?.() ?? true);
         // Get conversation messages for context.
         // If the caller already supplied conversationMessages (e.g. proxy routes
         // forwarding a multi-turn Claude request), honour them — including an
@@ -8450,6 +8520,58 @@ Current user's request: ${currentInput}`;
     getToolDedupConfig() {
         return this.toolDedupConfig;
     }
+    /**
+     * Returns the instance-level `tools` config (master switch, include/exclude
+     * lists, discovery mode), or `undefined` when not provided at construction.
+     *
+     * Called by `BaseProvider.applyToolFiltering` so the tool gate composes the
+     * instance policy with per-call options on every generate/stream call.
+     */
+    getToolsConfig() {
+        return this.toolsConfig;
+    }
+    /**
+     * Tools discovered via `search_tools` for a session (`tools.discovery`
+     * mode). Pinned tools are sent in full on every subsequent call of that
+     * session instead of being deferred — discovery cost is paid once.
+     * Reading refreshes the session's recency (LRU), so active conversations
+     * are never the ones evicted at the session cap.
+     */
+    getDiscoveryPins(sessionKey) {
+        const pins = this.discoveryPins.get(sessionKey);
+        if (!pins) {
+            return new Set();
+        }
+        // Map iteration order is insertion order — re-inserting on access turns
+        // the eviction below into LRU rather than FIFO.
+        this.discoveryPins.delete(sessionKey);
+        this.discoveryPins.set(sessionKey, pins);
+        return pins;
+    }
+    /**
+     * Pin discovered tools to a session (called by the `search_tools`
+     * meta-tool on hydration). Append-only within a session; the map is
+     * bounded by evicting the least-recently-used session past 1000 sessions.
+     */
+    pinDiscoveredTools(sessionKey, toolNames) {
+        let pins = this.discoveryPins.get(sessionKey);
+        if (!pins) {
+            pins = new Set();
+        }
+        else {
+            this.discoveryPins.delete(sessionKey);
+        }
+        this.discoveryPins.set(sessionKey, pins);
+        for (const name of toolNames) {
+            pins.add(name);
+        }
+        if (this.discoveryPins.size > 1000) {
+            const oldest = this.discoveryPins.keys().next().value;
+            if (oldest !== undefined) {
+                this.discoveryPins.delete(oldest);
+            }
+        }
+    }
     /**
      * Curator P1-1: synchronous credential health check for a single provider.
      *
@@ -9809,8 +9931,11 @@ Current user's request: ${currentInput}`;
                     }
                 }
             }
-            // Return canonical ToolInfo[]; defer presentation transforms to call sites
-            const tools = uniqueTools;
+            // Return canonical ToolInfo[]; defer presentation transforms to call sites.
+            // Name-sorted: external MCP discovery completes in parallel, so Map
+            // insertion order varies across restarts — downstream consumers (tool
+            // listings, prompt construction, budget accounting) need a stable order.
+            const tools = uniqueTools.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
             // Update the cache
             this.toolCache = {
                 tools,

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>;
+}

package/dist/rag/stores/chroma.js

@@ -0,0 +1,280 @@
+/**
+ * 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 });
+    }
+}