@juspay/neurolink 9.64.0 → 9.65.0

package/dist/providers/jina.js

@@ -0,0 +1,217 @@
+import { JinaModels } from "../constants/enums.js";
+import { BaseProvider } from "../core/baseProvider.js";
+import { isNeuroLink } from "../neurolink.js";
+import { createProxyFetch } from "../proxy/proxyFetch.js";
+import { AuthenticationError, InvalidModelError, ProviderError, RateLimitError, } from "../types/index.js";
+import { logger } from "../utils/logger.js";
+import { createJinaConfig, getProviderModel, validateApiKey, } from "../utils/providerConfig.js";
+const JINA_DEFAULT_BASE_URL = "https://api.jina.ai/v1";
+const REQUEST_TIMEOUT_MS = 60_000;
+const getJinaApiKey = () => validateApiKey(createJinaConfig());
+const getDefaultJinaModel = () => getProviderModel("JINA_MODEL", JinaModels.JINA_EMBEDDINGS_V3);
+/**
+ * Jina AI Provider — embeddings + reranking.
+ *
+ * Native API at api.jina.ai/v1. Chat / streaming / tool calling are not
+ * supported. Use `embed()` / `embedMany()` for embeddings, or call
+ * `rerank()` directly for retrieval reranking (Jina's strength).
+ *
+ * @see https://jina.ai/embeddings/
+ */
+export class JinaProvider extends BaseProvider {
+    apiKey;
+    baseURL;
+    proxyFetch;
+    constructor(modelName, sdk, _region, credentials) {
+        const validatedNeurolink = isNeuroLink(sdk) ? sdk : undefined;
+        super(modelName, "jina", validatedNeurolink);
+        const overrideKey = credentials?.apiKey?.trim();
+        this.apiKey =
+            overrideKey && overrideKey.length > 0 ? overrideKey : getJinaApiKey();
+        this.baseURL =
+            credentials?.baseURL ??
+                process.env.JINA_BASE_URL ??
+                JINA_DEFAULT_BASE_URL;
+        this.proxyFetch = createProxyFetch();
+        logger.debug("Jina Provider initialized (embeddings + reranking)", {
+            modelName: this.modelName,
+            baseURL: this.baseURL,
+        });
+    }
+    getProviderName() {
+        return this.providerName;
+    }
+    getDefaultModel() {
+        return getDefaultJinaModel();
+    }
+    supportsTools() {
+        return false;
+    }
+    getDefaultEmbeddingModel() {
+        return getDefaultJinaModel();
+    }
+    getAISDKModel() {
+        throw new Error("Jina AI is an embeddings + reranking provider; chat completions are not available. Use `embed()` / `embedMany()` / `rerank()`.");
+    }
+    async executeStream(_options, _analysisSchema) {
+        throw new Error("Jina AI is an embeddings + reranking provider; streaming chat is not available.");
+    }
+    formatProviderError(error) {
+        const message = error instanceof Error
+            ? error.message
+            : typeof error === "string"
+                ? error
+                : "Unknown error";
+        if (message.includes("401") ||
+            message.toLowerCase().includes("unauthorized")) {
+            return new AuthenticationError("Invalid Jina AI API key. Get one at https://jina.ai/?sui=apikey", "jina");
+        }
+        if (message.includes("429") ||
+            message.toLowerCase().includes("rate limit")) {
+            return new RateLimitError("Jina AI rate limit exceeded. Back off and retry.", "jina");
+        }
+        if (message.includes("404") ||
+            message.toLowerCase().includes("model_not_found")) {
+            return new InvalidModelError(`Jina AI model '${this.modelName}' not found. See https://jina.ai/embeddings/`, "jina");
+        }
+        return new ProviderError(`Jina AI error: ${message}`, "jina");
+    }
+    async embed(text, modelName) {
+        const vectors = await this.callEmbeddings([text], modelName);
+        if (!vectors[0]) {
+            throw new Error("Jina AI returned no embedding for the provided text");
+        }
+        return vectors[0];
+    }
+    async embedMany(texts, modelName) {
+        if (texts.length === 0) {
+            return [];
+        }
+        return this.callEmbeddings(texts, modelName);
+    }
+    /**
+     * Rerank a list of documents against a query.
+     *
+     * Returns the documents sorted by relevance (highest first), with
+     * score and original index preserved so callers can map back.
+     *
+     * Note: not exposed on `BaseProvider` — accessed by casting to
+     * `JinaProvider` or via the dedicated rerank route on the public API
+     * (`POST /api/agent/rerank` in the server module, when added).
+     *
+     * Per-call credentials can be supplied via `options.credentials?.jina`,
+     * overriding the instance-level credentials for this request only.
+     */
+    async rerank(query, documents, options = {}) {
+        if (documents.length === 0) {
+            return [];
+        }
+        const model = options.model ?? JinaModels.JINA_RERANKER_V2_BASE_MULTILINGUAL;
+        // Resolve per-call credentials first, then fall back to instance-level.
+        const perCallCreds = options.credentials;
+        const effectiveApiKey = perCallCreds?.apiKey?.trim() || this.apiKey;
+        const effectiveBaseURL = perCallCreds?.baseURL || this.baseURL;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        let response;
+        try {
+            response = await this.proxyFetch(`${effectiveBaseURL}/rerank`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${effectiveApiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    model,
+                    query,
+                    documents,
+                    top_n: options.topN ?? documents.length,
+                }),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                throw this.formatProviderError(new Error(`Jina rerank request timed out after ${REQUEST_TIMEOUT_MS / 1000}s`));
+            }
+            throw this.formatProviderError(err);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+        if (!response.ok) {
+            const text = await response.text();
+            throw this.formatProviderError(new Error(`Jina rerank failed: ${response.status} — ${text}`));
+        }
+        const data = (await response.json());
+        return (data.results ?? []).map((r) => ({
+            index: r.index,
+            score: r.relevance_score,
+            document: documents[r.index] ?? r.document?.text ?? "",
+        }));
+    }
+    async callEmbeddings(inputs, modelName, credentials) {
+        const model = modelName ?? this.modelName;
+        // Resolve per-call credentials first, then fall back to instance-level.
+        const effectiveApiKey = credentials?.apiKey?.trim() || this.apiKey;
+        const effectiveBaseURL = credentials?.baseURL || this.baseURL;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        let response;
+        try {
+            response = await this.proxyFetch(`${effectiveBaseURL}/embeddings`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${effectiveApiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    input: inputs,
+                    model,
+                }),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                throw this.formatProviderError(new Error(`Jina embeddings request timed out after ${REQUEST_TIMEOUT_MS / 1000}s`));
+            }
+            throw this.formatProviderError(err);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+        if (!response.ok) {
+            const text = await response.text();
+            throw this.formatProviderError(new Error(`Jina embeddings failed: ${response.status} — ${text}`));
+        }
+        const data = (await response.json());
+        if (!data.data || data.data.length === 0) {
+            throw new Error("Jina embeddings response missing data");
+        }
+        // Validate that the response covers all requested inputs.
+        if (data.data.length !== inputs.length) {
+            throw new Error(`Jina embeddings response count mismatch: expected ${inputs.length}, got ${data.data.length}`);
+        }
+        // Sort by index and verify sequential coverage (0 … n-1).
+        const sorted = data.data.slice().sort((a, b) => a.index - b.index);
+        for (let i = 0; i < sorted.length; i++) {
+            if (sorted[i].index !== i) {
+                throw new Error(`Jina embeddings response has unexpected index ordering: position ${i} has index ${sorted[i].index}`);
+            }
+        }
+        return sorted.map((d) => d.embedding);
+    }
+    async validateConfiguration() {
+        return typeof this.apiKey === "string" && this.apiKey.trim().length > 0;
+    }
+    getConfiguration() {
+        return {
+            provider: this.providerName,
+            model: this.modelName,
+            defaultModel: getDefaultJinaModel(),
+            baseURL: this.baseURL,
+        };
+    }
+}
+export default JinaProvider;

package/dist/providers/llamaCpp.js

@@ -3,46 +3,16 @@ import { stepCountIs, streamText } from "ai";
 import { BaseProvider } from "../core/baseProvider.js";
 import { DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
-import { createProxyFetch, maskProxyUrl } from "../proxy/proxyFetch.js";
-import { tracers, ATTR, withClientSpan } from "../telemetry/index.js";
+import { isNeuroLink } from "../neurolink.js";
+import { createProxyFetch } from "../proxy/proxyFetch.js";
+import { createLoggingFetch } from "../utils/loggingFetch.js";
+import { tracers, ATTR, withClientStreamSpan } from "../telemetry/index.js";
+import { NetworkError, ProviderError } from "../types/index.js";
 import { logger } from "../utils/logger.js";
 import { composeAbortSignals, createTimeoutController, TimeoutError, } from "../utils/timeout.js";
 import { emitToolEndFromStepFinish } from "../utils/toolEndEmitter.js";
 import { resolveToolChoice } from "../utils/toolChoice.js";
 import { toAnalyticsStreamResult } from "./providerTypeUtils.js";
-const makeLoggingFetch = (provider) => {
-    const base = createProxyFetch();
-    return (async (input, init) => {
-        const url = typeof input === "string"
-            ? input
-            : input instanceof URL
-                ? input.toString()
-                : input.url;
-        const reqSize = init?.body && typeof init.body === "string" ? init.body.length : 0;
-        const response = await base(input, init);
-        if (!response.ok) {
-            // Mask any embedded credentials / signed query params before logging.
-            // Fall back to "<redacted>" rather than the raw URL on a masking miss.
-            const safeUrl = maskProxyUrl(url) ?? "<redacted>";
-            // Don't log the raw upstream body — it can echo prompt fragments or
-            // tool payloads. Log size + status + URL only. Opt into bodies via
-            // NEUROLINK_DEBUG_HTTP=1 for local debugging.
-            if (process.env.NEUROLINK_DEBUG_HTTP === "1") {
-                const clone = response.clone();
-                const body = await clone.text().catch(() => "<unreadable>");
-                logger.warn(`[${provider}] upstream ${response.status}`, {
-                    url: safeUrl,
-                    body: body.slice(0, 800),
-                    reqSize,
-                });
-            }
-            else {
-                logger.warn(`[${provider}] upstream ${response.status} url=${safeUrl} reqSize=${reqSize}`);
-            }
-        }
-        return response;
-    });
-};
 const LLAMACPP_DEFAULT_BASE_URL = "http://localhost:8080/v1";
 const LLAMACPP_PLACEHOLDER_KEY = "llamacpp";
 const FALLBACK_MODEL = "loaded-model";
@@ -66,9 +36,7 @@ export class LlamaCppProvider extends BaseProvider {
     discoveredModel;
     llamaCppClient;
     constructor(modelName, sdk, _region, credentials) {
-        const validatedNeurolink = sdk && typeof sdk === "object" && "getInMemoryServers" in sdk
-            ? sdk
-            : undefined;
+        const validatedNeurolink = isNeuroLink(sdk) ? sdk : undefined;
         super(modelName, "llamacpp", validatedNeurolink);
         this.requestedModelName = modelName;
         this.baseURL = credentials?.baseURL ?? getLlamaCppBaseURL();
@@ -82,7 +50,7 @@ export class LlamaCppProvider extends BaseProvider {
         this.llamaCppClient = createOpenAI({
             baseURL: this.baseURL,
             apiKey: this.apiKey,
-            fetch: makeLoggingFetch("llamacpp"),
+            fetch: createLoggingFetch("llamacpp"),
         });
         logger.debug("llama.cpp Provider initialized", {
             modelName: this.modelName,
@@ -169,7 +137,7 @@ export class LlamaCppProvider extends BaseProvider {
         // Pass the caller's abort signal so user cancellation / per-request
         // timeouts are honored during the discovery probe.
         await this.getAISDKModel(options.abortSignal);
-        return withClientSpan({
+        return withClientStreamSpan({
             name: "neurolink.provider.stream",
             tracer: tracers.provider,
             attributes: {
@@ -178,7 +146,7 @@ export class LlamaCppProvider extends BaseProvider {
                 [ATTR.GEN_AI_OPERATION]: "stream",
                 [ATTR.NL_STREAM_MODE]: true,
             },
-        }, async () => this.executeStreamInner(options));
+        }, async () => this.executeStreamInner(options), (r) => r.stream, (r, wrapped) => ({ ...r, stream: wrapped }));
     }
     async executeStreamInner(options) {
         this.validateStreamOptions(options);
@@ -243,7 +211,7 @@ export class LlamaCppProvider extends BaseProvider {
     }
     formatProviderError(error) {
         if (error instanceof TimeoutError) {
-            return new Error(`llama.cpp request timed out: ${error.message}`);
+            return new NetworkError(`Request timed out: ${error.message}`, "llamacpp");
         }
         const errorRecord = error;
         const message = typeof errorRecord?.message === "string"
@@ -255,13 +223,13 @@ export class LlamaCppProvider extends BaseProvider {
             message.includes("ECONNREFUSED") ||
             message.includes("Failed to fetch") ||
             message.includes("fetch failed")) {
-            return new Error(`llama.cpp server not reachable at ${this.baseURL}. ` +
-                "Start it with: ./llama-server -m model.gguf --port 8080");
+            return new NetworkError(`llama.cpp server not reachable at ${this.baseURL}. ` +
+                "Start it with: ./llama-server -m model.gguf --port 8080", "llamacpp");
         }
         if (message.includes("400")) {
-            return new Error("llama.cpp rejected the request. Common cause: model doesn't support tools (start llama-server with --jinja for tool support).");
+            return new ProviderError("llama.cpp rejected the request. Common cause: model doesn't support tools (start llama-server with --jinja for tool support).", "llamacpp");
         }
-        return new Error(`llama.cpp error: ${message}`);
+        return new ProviderError(`llama.cpp error: ${message}`, "llamacpp");
     }
     async validateConfiguration() {
         // Retry up to 3x with 500ms backoff. llama-server can be briefly unresponsive

package/dist/providers/lmStudio.js

@@ -3,47 +3,16 @@ import { stepCountIs, streamText } from "ai";
 import { BaseProvider } from "../core/baseProvider.js";
 import { DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
-import { createProxyFetch, maskProxyUrl } from "../proxy/proxyFetch.js";
-import { tracers, ATTR, withClientSpan } from "../telemetry/index.js";
+import { isNeuroLink } from "../neurolink.js";
+import { createProxyFetch } from "../proxy/proxyFetch.js";
+import { createLoggingFetch } from "../utils/loggingFetch.js";
+import { tracers, ATTR, withClientStreamSpan } from "../telemetry/index.js";
+import { InvalidModelError, NetworkError, ProviderError, } from "../types/index.js";
 import { logger } from "../utils/logger.js";
 import { composeAbortSignals, createTimeoutController, TimeoutError, } from "../utils/timeout.js";
 import { emitToolEndFromStepFinish } from "../utils/toolEndEmitter.js";
 import { resolveToolChoice } from "../utils/toolChoice.js";
 import { toAnalyticsStreamResult } from "./providerTypeUtils.js";
-const makeLoggingFetch = (provider) => {
-    const base = createProxyFetch();
-    return (async (input, init) => {
-        const url = typeof input === "string"
-            ? input
-            : input instanceof URL
-                ? input.toString()
-                : input.url;
-        const reqSize = init?.body && typeof init.body === "string" ? init.body.length : 0;
-        const response = await base(input, init);
-        if (!response.ok) {
-            // Mask any embedded credentials / signed query params before logging.
-            // Fall back to "<redacted>" rather than the raw URL on a masking miss —
-            // logging the unsanitized form would defeat the redaction.
-            const safeUrl = maskProxyUrl(url) ?? "<redacted>";
-            // Don't log the raw upstream body or request payload — they can contain
-            // user prompts, tool arguments, and other sensitive data. Log size +
-            // status + URL only. Set NEUROLINK_DEBUG_HTTP=1 to opt into raw bodies.
-            if (process.env.NEUROLINK_DEBUG_HTTP === "1") {
-                const clone = response.clone();
-                const body = await clone.text().catch(() => "<unreadable>");
-                logger.warn(`[${provider}] upstream ${response.status}`, {
-                    url: safeUrl,
-                    body: body.slice(0, 400),
-                    reqSize,
-                });
-            }
-            else {
-                logger.warn(`[${provider}] upstream ${response.status} url=${safeUrl} reqSize=${reqSize}`);
-            }
-        }
-        return response;
-    });
-};
 const LM_STUDIO_DEFAULT_BASE_URL = "http://localhost:1234/v1";
 const LM_STUDIO_PLACEHOLDER_KEY = "lm-studio";
 const FALLBACK_MODEL = "local-model";
@@ -67,9 +36,7 @@ export class LMStudioProvider extends BaseProvider {
     discoveredModel;
     lmstudioClient;
     constructor(modelName, sdk, _region, credentials) {
-        const validatedNeurolink = sdk && typeof sdk === "object" && "getInMemoryServers" in sdk
-            ? sdk
-            : undefined;
+        const validatedNeurolink = isNeuroLink(sdk) ? sdk : undefined;
         super(modelName, "lm-studio", validatedNeurolink);
         this.requestedModelName = modelName;
         this.baseURL = credentials?.baseURL ?? getLmStudioBaseURL();
@@ -83,7 +50,7 @@ export class LMStudioProvider extends BaseProvider {
         this.lmstudioClient = createOpenAI({
             baseURL: this.baseURL,
             apiKey: this.apiKey,
-            fetch: makeLoggingFetch("lm-studio"),
+            fetch: createLoggingFetch("lm-studio"),
         });
         logger.debug("LM Studio Provider initialized", {
             modelName: this.modelName,
@@ -173,7 +140,7 @@ export class LMStudioProvider extends BaseProvider {
         // Pass the caller's abort signal so user cancellation / per-request
         // timeouts are honored during the discovery probe (not just after it).
         await this.getAISDKModel(options.abortSignal);
-        return withClientSpan({
+        return withClientStreamSpan({
             name: "neurolink.provider.stream",
             tracer: tracers.provider,
             attributes: {
@@ -182,7 +149,7 @@ export class LMStudioProvider extends BaseProvider {
                 [ATTR.GEN_AI_OPERATION]: "stream",
                 [ATTR.NL_STREAM_MODE]: true,
             },
-        }, async () => this.executeStreamInner(options));
+        }, async () => this.executeStreamInner(options), (r) => r.stream, (r, wrapped) => ({ ...r, stream: wrapped }));
     }
     async executeStreamInner(options) {
         this.validateStreamOptions(options);
@@ -249,7 +216,7 @@ export class LMStudioProvider extends BaseProvider {
     }
     formatProviderError(error) {
         if (error instanceof TimeoutError) {
-            return new Error(`LM Studio request timed out: ${error.message}`);
+            return new NetworkError(`Request timed out: ${error.message}`, "lm-studio");
         }
         const errorRecord = error;
         const message = typeof errorRecord?.message === "string"
@@ -261,13 +228,13 @@ export class LMStudioProvider extends BaseProvider {
             message.includes("ECONNREFUSED") ||
             message.includes("Failed to fetch") ||
             message.includes("fetch failed")) {
-            return new Error(`LM Studio server not reachable at ${this.baseURL}. ` +
-                `Open the LM Studio app, load a model, and click "Start Server".`);
+            return new NetworkError(`LM Studio server not reachable at ${this.baseURL}. ` +
+                `Open the LM Studio app, load a model, and click "Start Server".`, "lm-studio");
         }
         if (message.includes("model_not_found") || message.includes("404")) {
-            return new Error(`LM Studio model '${this.modelName}' is not loaded. Load it in the LM Studio app first.`);
+            return new InvalidModelError(`LM Studio model '${this.modelName}' is not loaded. Load it in the LM Studio app first.`, "lm-studio");
         }
-        return new Error(`LM Studio error: ${message}`);
+        return new ProviderError(`LM Studio error: ${message}`, "lm-studio");
     }
     async validateConfiguration() {
         try {

package/dist/providers/mistral.js

@@ -3,7 +3,9 @@ import { stepCountIs, streamText } from "ai";
 import { BaseProvider } from "../core/baseProvider.js";
 import { DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
+import { isNeuroLink } from "../neurolink.js";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
+import { AuthenticationError, NetworkError, ProviderError, RateLimitError, } from "../types/index.js";
 import { emitToolEndFromStepFinish } from "../utils/toolEndEmitter.js";
 import { logger } from "../utils/logger.js";
 import { createMistralConfig, getProviderModel, validateApiKey, } from "../utils/providerConfig.js";
@@ -26,9 +28,7 @@ export class MistralProvider extends BaseProvider {
     model;
     constructor(modelName, sdk, _region, credentials) {
         // Type guard for NeuroLink parameter validation
-        const validatedNeurolink = sdk && typeof sdk === "object" && "getInMemoryServers" in sdk
-            ? sdk
-            : undefined;
+        const validatedNeurolink = isNeuroLink(sdk) ? sdk : undefined;
         super(modelName, "mistral", validatedNeurolink);
         // Initialize Mistral model with API key validation and proxy support
         const apiKey = credentials?.apiKey ?? getMistralApiKey();
@@ -131,7 +131,7 @@ export class MistralProvider extends BaseProvider {
     }
     formatProviderError(error) {
         if (error instanceof TimeoutError) {
-            return new Error(`Mistral request timed out: ${error.message}`);
+            return new NetworkError(`Request timed out: ${error.message}`, "mistral");
         }
         const errorRecord = error;
         const message = typeof errorRecord?.message === "string"
@@ -139,12 +139,12 @@ export class MistralProvider extends BaseProvider {
             : "Unknown error";
         if (message.includes("API_KEY_INVALID") ||
             message.includes("Invalid API key")) {
-            return new Error("Invalid Mistral API key. Please check your MISTRAL_API_KEY environment variable.");
+            return new AuthenticationError("Invalid Mistral API key. Please check your MISTRAL_API_KEY environment variable.", "mistral");
         }
         if (message.includes("Rate limit exceeded")) {
-            return new Error("Mistral rate limit exceeded");
+            return new RateLimitError("Mistral rate limit exceeded", "mistral");
         }
-        return new Error(`Mistral error: ${message}`);
+        return new ProviderError(`Mistral error: ${message}`, "mistral");
     }
     /**
      * Validate provider configuration