@juspay/neurolink 9.54.2 → 9.54.3

package/dist/lib/utils/toolCallRepair.js

@@ -0,0 +1,298 @@
+/**
+ * Schema-Driven Tool Call Repair (BZ-665)
+ *
+ * Implements `experimental_repairToolCall` for the Vercel AI SDK.
+ * When an LLM sends a wrong tool name or wrong parameter names,
+ * this module attempts deterministic, schema-driven repair:
+ *
+ *  1. Tool name: case-insensitive → substring → Levenshtein
+ *  2. Param names: compare against JSON schema properties dynamically
+ *  3. Type coercion: string→number, JSON string→object/array per schema
+ *
+ * Zero static alias maps. The tool's JSON schema is the only source of truth.
+ *
+ * @module utils/toolCallRepair
+ */
+import { logger } from "./logger.js";
+/**
+ * Create an `experimental_repairToolCall` handler for streamText/generateText.
+ * Fully dynamic — reads the tool schema at repair time, no configuration needed.
+ */
+export function createToolCallRepair() {
+    return async ({ toolCall, tools, inputSchema, error }) => {
+        // Import error classes lazily to avoid circular deps at module level
+        const { NoSuchToolError: NoSuchTool, InvalidToolInputError: InvalidInput } = await import("ai");
+        if (NoSuchTool.isInstance(error)) {
+            return repairToolName(toolCall, Object.keys(tools));
+        }
+        if (InvalidInput.isInstance(error)) {
+            try {
+                const schema = await inputSchema({ toolName: toolCall.toolName });
+                return repairToolInput(toolCall, schema);
+            }
+            catch {
+                // inputSchema() failed — can't repair without schema
+                return null;
+            }
+        }
+        return null;
+    };
+}
+// ─── Tool Name Repair ──────────────────────────────────────────────
+/**
+ * Attempt to match a wrong tool name against available tool names.
+ * Strategies (in order): case-insensitive exact → substring → Levenshtein.
+ */
+function repairToolName(toolCall, availableTools) {
+    const called = toolCall.toolName;
+    // Guard: empty or whitespace-only tool name cannot be meaningfully repaired
+    if (!called || called.trim().length === 0) {
+        return null;
+    }
+    // 1. Case-insensitive exact match
+    const ciMatch = availableTools.find((t) => t.toLowerCase() === called.toLowerCase());
+    if (ciMatch) {
+        logger.debug(`[ToolCallRepair] Name repair (case): "${called}" → "${ciMatch}"`);
+        return { ...toolCall, toolName: ciMatch };
+    }
+    // 2. Substring match: "search_file" is substring of "search_files" or vice versa.
+    // Only accept when exactly one tool matches to avoid ambiguous repairs.
+    const calledLower = called.toLowerCase();
+    const subCandidates = availableTools.filter((t) => {
+        const tLower = t.toLowerCase();
+        return tLower.includes(calledLower) || calledLower.includes(tLower);
+    });
+    if (subCandidates.length === 1) {
+        logger.debug(`[ToolCallRepair] Name repair (substring): "${called}" → "${subCandidates[0]}"`);
+        return { ...toolCall, toolName: subCandidates[0] };
+    }
+    // 3. Levenshtein distance — accept if normalized distance < 0.3
+    // Compare by normalized score (not raw edits) so length differences don't skew selection.
+    let bestMatch = null;
+    let bestNormalized = Infinity;
+    for (const t of availableTools) {
+        const dist = levenshtein(calledLower, t.toLowerCase());
+        const maxLen = Math.max(called.length, t.length);
+        const normalized = maxLen === 0 ? 0 : dist / maxLen;
+        if (normalized < 0.3 && normalized < bestNormalized) {
+            bestNormalized = normalized;
+            bestMatch = t;
+        }
+    }
+    if (bestMatch) {
+        logger.debug(`[ToolCallRepair] Name repair (levenshtein ${bestNormalized.toFixed(2)}): "${called}" → "${bestMatch}"`);
+        return { ...toolCall, toolName: bestMatch };
+    }
+    logger.debug(`[ToolCallRepair] Could not repair tool name "${called}". Available: [${availableTools.join(", ")}]`);
+    return null;
+}
+// ─── Tool Input Repair ─────────────────────────────────────────────
+/**
+ * Attempt to repair wrong parameter names and types using the JSON schema.
+ * Compares LLM-provided keys against schema properties dynamically.
+ *
+ * `toolCall.input` is a JSON string per LanguageModelV3ToolCall.
+ */
+function repairToolInput(toolCall, schema) {
+    let args;
+    try {
+        args = JSON.parse(toolCall.input);
+    }
+    catch {
+        return null; // input is not valid JSON — can't repair
+    }
+    if (!args || typeof args !== "object" || Array.isArray(args)) {
+        return null;
+    }
+    const schemaProps = schema.properties;
+    if (!schemaProps) {
+        return null;
+    }
+    const expectedKeys = Object.keys(schemaProps);
+    const inputObj = args;
+    const inputKeys = Object.keys(inputObj);
+    const repaired = Object.create(null);
+    let didRepair = false;
+    const dropUnknown = schema.additionalProperties === false;
+    for (const inputKey of inputKeys) {
+        // Already matches a schema property — keep as-is
+        if (expectedKeys.includes(inputKey)) {
+            repaired[inputKey] = inputObj[inputKey];
+            continue;
+        }
+        // Try to find a matching schema property
+        const mapped = findMatchingKey(inputKey, expectedKeys);
+        if (mapped) {
+            // Don't overwrite an already-populated canonical key — but still mark as repaired
+            // so the function returns the corrected object instead of null.
+            if (Object.prototype.hasOwnProperty.call(repaired, mapped)) {
+                didRepair = true;
+                continue;
+            }
+            logger.debug(`[ToolCallRepair] Param repair: "${inputKey}" → "${mapped}" (tool: ${toolCall.toolName})`);
+            repaired[mapped] = inputObj[inputKey];
+            didRepair = true;
+        }
+        else if (dropUnknown) {
+            // Schema forbids extra properties — drop unmapped keys
+            logger.debug(`[ToolCallRepair] Dropping unmapped key "${inputKey}" (additionalProperties: false, tool: ${toolCall.toolName})`);
+            didRepair = true;
+        }
+        else {
+            // Unknown key — pass through (schema allows additionalProperties)
+            repaired[inputKey] = inputObj[inputKey];
+        }
+    }
+    // Type coercion based on schema types
+    for (const key of Object.keys(repaired)) {
+        const propSchema = schemaProps[key];
+        if (!propSchema) {
+            continue;
+        }
+        const coerced = coerceType(repaired[key], propSchema);
+        if (coerced !== repaired[key]) {
+            logger.debug(`[ToolCallRepair] Type coercion on "${key}": ${typeof repaired[key]} → ${typeof coerced} (tool: ${toolCall.toolName})`);
+            repaired[key] = coerced;
+            didRepair = true;
+        }
+    }
+    if (didRepair) {
+        return { ...toolCall, input: JSON.stringify(repaired) };
+    }
+    return null;
+}
+/**
+ * Find a matching schema key for a mismatched input key.
+ * Strategies: case-insensitive → Levenshtein (threshold ≤2 edits).
+ */
+function findMatchingKey(inputKey, schemaKeys) {
+    const inputLower = inputKey.toLowerCase();
+    // Case-insensitive match
+    const ciMatch = schemaKeys.find((k) => k.toLowerCase() === inputLower);
+    if (ciMatch) {
+        return ciMatch;
+    }
+    // Levenshtein — threshold ≤2 edits
+    let best = null;
+    let bestDist = Infinity;
+    for (const k of schemaKeys) {
+        const dist = levenshtein(inputLower, k.toLowerCase());
+        if (dist <= 2 && dist < bestDist) {
+            bestDist = dist;
+            best = k;
+        }
+    }
+    return best;
+}
+// ─── Type Coercion ─────────────────────────────────────────────────
+/**
+ * Coerce a value to match the expected schema type.
+ * Handles: string→number, JSON string→object, JSON string→array, value→[value].
+ */
+function coerceType(value, propSchema) {
+    const expectedType = propSchema.type;
+    if (!expectedType || value === null || value === undefined) {
+        return value;
+    }
+    // String → Number (trim first, reject empty/whitespace, require finite result)
+    if (expectedType === "number" && typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed !== "") {
+            const num = Number(trimmed);
+            if (isFinite(num)) {
+                return num;
+            }
+        }
+    }
+    // String → Integer (strict: reject "12abc", "3.7", etc.)
+    if (expectedType === "integer" && typeof value === "string") {
+        const trimmed = value.trim();
+        if (/^[+-]?\d+$/.test(trimmed)) {
+            const num = Number(trimmed);
+            if (Number.isSafeInteger(num)) {
+                return num;
+            }
+        }
+    }
+    // String → Boolean
+    if (expectedType === "boolean" && typeof value === "string") {
+        if (value.toLowerCase() === "true") {
+            return true;
+        }
+        if (value.toLowerCase() === "false") {
+            return false;
+        }
+    }
+    // JSON string → Object
+    if (expectedType === "object" && typeof value === "string") {
+        try {
+            const parsed = JSON.parse(value);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Not valid JSON — return as-is
+        }
+    }
+    // JSON string → Array
+    if (expectedType === "array" && typeof value === "string") {
+        try {
+            const parsed = JSON.parse(value);
+            if (Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Not valid JSON — return as-is
+        }
+    }
+    // Single non-string value → Array (wrap).
+    // Strings are excluded because they are more likely a JSON-encoded array
+    // that failed to parse above, and wrapping "foo" into ["foo"] is rarely correct.
+    if (expectedType === "array" &&
+        !Array.isArray(value) &&
+        typeof value !== "string") {
+        return [value];
+    }
+    return value;
+}
+// ─── Levenshtein Distance ──────────────────────────────────────────
+/**
+ * Compute Levenshtein edit distance between two strings.
+ * Uses the iterative matrix approach — O(m*n) time, O(min(m,n)) space.
+ */
+function levenshtein(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    if (a.length === 0) {
+        return b.length;
+    }
+    if (b.length === 0) {
+        return a.length;
+    }
+    // Use shorter string as column to minimize space
+    if (a.length > b.length) {
+        [a, b] = [b, a];
+    }
+    const aLen = a.length;
+    const bLen = b.length;
+    let prev = new Array(aLen + 1);
+    let curr = new Array(aLen + 1);
+    for (let i = 0; i <= aLen; i++) {
+        prev[i] = i;
+    }
+    for (let j = 1; j <= bLen; j++) {
+        curr[0] = j;
+        for (let i = 1; i <= aLen; i++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[i] = Math.min(prev[i] + 1, // deletion
+            curr[i - 1] + 1, // insertion
+            prev[i - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[aLen];
+}
+//# sourceMappingURL=toolCallRepair.js.map

package/dist/neurolink.js

@@ -4831,15 +4831,31 @@ Current user's request: ${currentInput}`;
         catch {
             /* non-blocking */
         }
-        const fallbackRoute = ModelRouter.getFallbackRoute(originalPrompt || enhancedOptions.input.text || "", {
+        // BZ-1341: Support fallback provider override via options or env vars
+        const optFallbackProvider = enhancedOptions.fallbackProvider?.trim() || undefined;
+        const optFallbackModel = enhancedOptions.fallbackModel?.trim() || undefined;
+        const envFallbackProvider = process.env.FALLBACK_PROVIDER?.trim() || undefined;
+        const envFallbackModel = process.env.FALLBACK_MODEL?.trim() || undefined;
+        const modelConfigRoute = ModelRouter.getFallbackRoute(originalPrompt || enhancedOptions.input.text || "", {
             provider: providerName,
             model: enhancedOptions.model || "gpt-4o",
             reasoning: "primary failed",
             confidence: 0.5,
         }, { fallbackStrategy: "auto" });
+        const fallbackRoute = {
+            ...modelConfigRoute,
+            provider: optFallbackProvider ?? envFallbackProvider ?? modelConfigRoute.provider,
+            model: optFallbackModel ?? envFallbackModel ?? modelConfigRoute.model,
+        };
         logger.warn("Retrying with fallback provider", {
             originalProvider: providerName,
             fallbackProvider: fallbackRoute.provider,
+            fallbackModel: fallbackRoute.model,
+            fallbackSource: optFallbackProvider || optFallbackModel
+                ? "options"
+                : envFallbackProvider || envFallbackModel
+                    ? "env"
+                    : "model_config",
             reason: errorMsg,
         });
         try {

package/dist/providers/anthropic.js

@@ -799,6 +799,7 @@ export class AnthropicProvider extends BaseProvider {
                     stopWhen: stepCountIs(options.maxSteps || DEFAULT_MAX_STEPS),
                     toolChoice: resolveToolChoice(options, tools, shouldUseTools),
                     abortSignal: composeAbortSignals(options.abortSignal, timeoutController?.controller.signal),
+                    experimental_repairToolCall: this.getToolCallRepairFn(options),
                     experimental_telemetry: this.telemetryHandler.getTelemetryConfig(options),
                     onStepFinish: ({ toolCalls, toolResults }) => {
                         this.handleToolExecutionStorage(toolCalls, toolResults, options, new Date()).catch((error) => {

package/dist/providers/anthropicBaseProvider.js

@@ -94,6 +94,7 @@ export class AnthropicProviderV2 extends BaseProvider {
                     toolChoice: resolveToolChoice(options, tools, shouldUseTools),
                     abortSignal: composeAbortSignals(options.abortSignal, timeoutController?.controller.signal),
                     experimental_telemetry: this.telemetryHandler.getTelemetryConfig(options),
+                    experimental_repairToolCall: this.getToolCallRepairFn(options),
                     onStepFinish: ({ toolCalls, toolResults }) => {
                         this.handleToolExecutionStorage(toolCalls, toolResults, options, new Date()).catch((error) => {
                             logger.warn("[AnthropicBaseProvider] Failed to store tool executions", {

package/dist/providers/azureOpenai.js

@@ -124,6 +124,7 @@ export class AzureOpenAIProvider extends BaseProvider {
                 stopWhen: stepCountIs(options.maxSteps || DEFAULT_MAX_STEPS),
                 abortSignal: composeAbortSignals(options.abortSignal, timeoutController?.controller.signal),
                 experimental_telemetry: this.telemetryHandler.getTelemetryConfig(options),
+                experimental_repairToolCall: this.getToolCallRepairFn(options),
                 onStepFinish: (event) => {
                     this.handleToolExecutionStorage([...event.toolCalls], [...event.toolResults], options, new Date()).catch((error) => {
                         logger.warn("[AzureOpenaiProvider] Failed to store tool executions", {

package/dist/providers/googleAiStudio.js

@@ -478,6 +478,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 toolChoice: resolveToolChoice(options, tools, shouldUseTools),
                 abortSignal: composeAbortSignals(options.abortSignal, timeoutController?.controller.signal),
                 experimental_telemetry: this.telemetryHandler.getTelemetryConfig(options),
+                experimental_repairToolCall: this.getToolCallRepairFn(options),
                 // Gemini 3: use thinkingLevel via providerOptions
                 // Gemini 2.5: use thinkingBudget via providerOptions
                 ...(options.thinkingConfig?.enabled && {

package/dist/providers/googleVertex.js

@@ -994,6 +994,7 @@ export class GoogleVertexProvider extends BaseProvider {
             }),
             abortSignal: composeAbortSignals(options.abortSignal, timeoutController?.controller.signal),
             experimental_telemetry: this.telemetryHandler.getTelemetryConfig(options),
+            experimental_repairToolCall: this.getToolCallRepairFn(options),
             ...(options.thinkingConfig?.enabled && {
                 providerOptions: {
                     vertex: {

package/dist/providers/huggingFace.js

@@ -139,6 +139,7 @@ export class HuggingFaceProvider extends BaseProvider {
                 toolChoice: resolveToolChoice(options, (shouldUseTools ? streamOptions.tools || allTools : {}), shouldUseTools),
                 abortSignal: composeAbortSignals(options.abortSignal, timeoutController?.controller.signal),
                 experimental_telemetry: this.telemetryHandler.getTelemetryConfig(options),
+                experimental_repairToolCall: this.getToolCallRepairFn(options),
                 onStepFinish: ({ toolCalls, toolResults }) => {
                     this.handleToolExecutionStorage(toolCalls, toolResults, options, new Date()).catch((error) => {
                         logger.warn("[HuggingFaceProvider] Failed to store tool executions", {

package/dist/providers/litellm.js

@@ -169,6 +169,7 @@ export class LiteLLMProvider extends BaseProvider {
                 }),
                 abortSignal: composeAbortSignals(options.abortSignal, timeoutController?.controller.signal),
                 experimental_telemetry: this.telemetryHandler.getTelemetryConfig(options),
+                experimental_repairToolCall: this.getToolCallRepairFn(options),
                 onError: (event) => {
                     const error = event.error;
                     const errorMessage = error instanceof Error ? error.message : String(error);

package/dist/providers/mistral.js

@@ -67,6 +67,7 @@ export class MistralProvider extends BaseProvider {
                 toolChoice: resolveToolChoice(options, tools, shouldUseTools),
                 abortSignal: composeAbortSignals(options.abortSignal, timeoutController?.controller.signal),
                 experimental_telemetry: this.telemetryHandler.getTelemetryConfig(options),
+                experimental_repairToolCall: this.getToolCallRepairFn(options),
                 onStepFinish: ({ toolCalls, toolResults }) => {
                     this.handleToolExecutionStorage(toolCalls, toolResults, options, new Date()).catch((error) => {
                         logger.warn("[MistralProvider] Failed to store tool executions", {

package/dist/providers/openAI.js

@@ -330,6 +330,7 @@ export class OpenAIProvider extends BaseProvider {
                     stopWhen: stepCountIs(options.maxSteps || DEFAULT_MAX_STEPS),
                     toolChoice: resolvedToolChoice,
                     abortSignal: composeAbortSignals(options.abortSignal, timeoutController?.controller.signal),
+                    experimental_repairToolCall: this.getToolCallRepairFn(options),
                     experimental_telemetry: this.telemetryHandler.getTelemetryConfig(options),
                     onStepFinish: ({ toolCalls, toolResults }) => {
                         logger.info("Tool execution completed", {

package/dist/providers/openRouter.js

@@ -252,6 +252,7 @@ export class OpenRouterProvider extends BaseProvider {
                 }),
                 abortSignal: composeAbortSignals(options.abortSignal, timeoutController?.controller.signal),
                 experimental_telemetry: this.telemetryHandler.getTelemetryConfig(options),
+                experimental_repairToolCall: this.getToolCallRepairFn(options),
                 onError: (event) => {
                     const error = event.error;
                     const errorMessage = error instanceof Error ? error.message : String(error);

package/dist/providers/openaiCompatible.js

@@ -195,6 +195,7 @@ export class OpenAICompatibleProvider extends BaseProvider {
                 stopWhen: stepCountIs(options.maxSteps || DEFAULT_MAX_STEPS),
                 abortSignal: composeAbortSignals(options.abortSignal, timeoutController?.controller.signal),
                 experimental_telemetry: this.telemetryHandler.getTelemetryConfig(options),
+                experimental_repairToolCall: this.getToolCallRepairFn(options),
                 onStepFinish: (event) => {
                     this.handleToolExecutionStorage([...event.toolCalls], [...event.toolResults], options, new Date()).catch((error) => {
                         logger.warn("[OpenAiCompatibleProvider] Failed to store tool executions", {

package/dist/types/streamTypes.d.ts

@@ -325,6 +325,8 @@ export type StreamOptions = {
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
     disableTools?: boolean;
+    /** Disable the schema-driven tool call repair mechanism (BZ-665). Default: false (repair enabled). */
+    disableToolCallRepair?: boolean;
     maxSteps?: number;
     /**
      * Tool choice configuration for streaming generation.
@@ -432,6 +434,10 @@ export type StreamOptions = {
      * @internal Set by NeuroLink SDK — not typically used directly by consumers.
      */
     fileRegistry?: unknown;
+    /** BZ-1341: Override fallback provider name (takes precedence over env/model config). */
+    fallbackProvider?: string;
+    /** BZ-1341: Override fallback model name (takes precedence over env/model config). */
+    fallbackModel?: string;
     /** Callback invoked when streaming completes successfully. */
     onFinish?: OnFinishCallback;
     /** Callback invoked when streaming encounters an error. */

package/dist/utils/toolCallRepair.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Schema-Driven Tool Call Repair (BZ-665)
+ *
+ * Implements `experimental_repairToolCall` for the Vercel AI SDK.
+ * When an LLM sends a wrong tool name or wrong parameter names,
+ * this module attempts deterministic, schema-driven repair:
+ *
+ *  1. Tool name: case-insensitive → substring → Levenshtein
+ *  2. Param names: compare against JSON schema properties dynamically
+ *  3. Type coercion: string→number, JSON string→object/array per schema
+ *
+ * Zero static alias maps. The tool's JSON schema is the only source of truth.
+ *
+ * @module utils/toolCallRepair
+ */
+import type { ToolCallRepairFunction, ToolSet } from "ai";
+/**
+ * Create an `experimental_repairToolCall` handler for streamText/generateText.
+ * Fully dynamic — reads the tool schema at repair time, no configuration needed.
+ */
+export declare function createToolCallRepair(): ToolCallRepairFunction<ToolSet>;