@juspay/neurolink 9.64.0 → 9.65.0

package/dist/lib/providers/cloudflare.js

@@ -0,0 +1,174 @@
+import { createOpenAI } from "@ai-sdk/openai";
+import { stepCountIs, streamText } from "ai";
+import { CloudflareModels } from "../constants/enums.js";
+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 { createLoggingFetch } from "../utils/loggingFetch.js";
+import { tracers, ATTR, withClientStreamSpan } from "../telemetry/index.js";
+import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../types/index.js";
+import { logger } from "../utils/logger.js";
+import { createCloudflareConfig, getProviderModel, validateApiKey, } from "../utils/providerConfig.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";
+/**
+ * Cloudflare Workers AI exposes an OpenAI-compatible endpoint scoped per
+ * account: `https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/v1`.
+ * The account id is required — without it the URL would 404.
+ */
+const buildCloudflareBaseURL = (accountId) => `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1`;
+const getCloudflareApiKey = () => validateApiKey(createCloudflareConfig());
+const getDefaultCloudflareModel = () => getProviderModel("CLOUDFLARE_MODEL", CloudflareModels.LLAMA_3_3_70B_FAST);
+/**
+ * Cloudflare Workers AI Provider
+ *
+ * Edge-served open models (Llama / Mistral / Qwen / Gemma) at
+ * `https://api.cloudflare.com/client/v4/accounts/{accountId}/ai/v1`
+ * (OpenAI-compatible). Cheapest tier for high-volume usage.
+ *
+ * Required env: `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID`.
+ *
+ * @see https://developers.cloudflare.com/workers-ai/configuration/open-ai-compatibility/
+ */
+export class CloudflareProvider extends BaseProvider {
+    model;
+    apiKey;
+    baseURL;
+    constructor(modelName, sdk, _region, credentials) {
+        const validatedNeurolink = isNeuroLink(sdk) ? sdk : undefined;
+        super(modelName, "cloudflare", validatedNeurolink);
+        const overrideApiKey = credentials?.apiKey?.trim();
+        this.apiKey =
+            overrideApiKey && overrideApiKey.length > 0
+                ? overrideApiKey
+                : getCloudflareApiKey();
+        const accountId = (credentials?.accountId ??
+            process.env.CLOUDFLARE_ACCOUNT_ID ??
+            "").trim();
+        if (!accountId) {
+            throw new Error("CLOUDFLARE_ACCOUNT_ID is required (or pass credentials.cloudflare.accountId). Get the account id from https://dash.cloudflare.com/");
+        }
+        this.baseURL = credentials?.baseURL ?? buildCloudflareBaseURL(accountId);
+        const cloudflare = createOpenAI({
+            apiKey: this.apiKey,
+            baseURL: this.baseURL,
+            fetch: createLoggingFetch("cloudflare"),
+        });
+        this.model = cloudflare.chat(this.modelName);
+        logger.debug("Cloudflare Workers AI Provider initialized", {
+            modelName: this.modelName,
+            providerName: this.providerName,
+            baseURL: this.baseURL,
+        });
+    }
+    async executeStream(options, _analysisSchema) {
+        return withClientStreamSpan({
+            name: "neurolink.provider.stream",
+            tracer: tracers.provider,
+            attributes: {
+                [ATTR.GEN_AI_SYSTEM]: "cloudflare",
+                [ATTR.GEN_AI_MODEL]: this.modelName,
+                [ATTR.GEN_AI_OPERATION]: "stream",
+                [ATTR.NL_STREAM_MODE]: true,
+            },
+        }, async () => this.executeStreamInner(options), (r) => r.stream, (r, wrapped) => ({ ...r, stream: wrapped }));
+    }
+    async executeStreamInner(options) {
+        this.validateStreamOptions(options);
+        const startTime = Date.now();
+        const timeout = this.getTimeout(options);
+        const timeoutController = createTimeoutController(timeout, this.providerName, "stream");
+        try {
+            const shouldUseTools = !options.disableTools && this.supportsTools();
+            const tools = shouldUseTools
+                ? options.tools || (await this.getAllTools())
+                : {};
+            const messages = await this.buildMessagesForStream(options);
+            const model = await this.getAISDKModelWithMiddleware(options);
+            const result = await streamText({
+                model,
+                messages,
+                temperature: options.temperature,
+                maxOutputTokens: options.maxTokens,
+                tools,
+                stopWhen: stepCountIs(options.maxSteps || DEFAULT_MAX_STEPS),
+                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 }) => {
+                    emitToolEndFromStepFinish(this.neurolink?.getEventEmitter(), toolResults);
+                    this.handleToolExecutionStorage(toolCalls, toolResults, options, new Date()).catch((error) => {
+                        logger.warn("[CloudflareProvider] Failed to store tool executions", {
+                            provider: this.providerName,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    });
+                },
+            });
+            timeoutController?.cleanup();
+            const transformedStream = this.createTextStream(result);
+            const analyticsPromise = streamAnalyticsCollector.createAnalytics(this.providerName, this.modelName, toAnalyticsStreamResult(result), Date.now() - startTime, {
+                requestId: `cloudflare-stream-${Date.now()}`,
+                streamingMode: true,
+            });
+            return {
+                stream: transformedStream,
+                provider: this.providerName,
+                model: this.modelName,
+                analytics: analyticsPromise,
+                metadata: { startTime, streamId: `cloudflare-${Date.now()}` },
+            };
+        }
+        catch (error) {
+            timeoutController?.cleanup();
+            throw this.handleProviderError(error);
+        }
+    }
+    getProviderName() {
+        return this.providerName;
+    }
+    getDefaultModel() {
+        return getDefaultCloudflareModel();
+    }
+    getAISDKModel() {
+        return this.model;
+    }
+    formatProviderError(error) {
+        if (error instanceof TimeoutError) {
+            return new NetworkError(`Request timed out: ${error.message}`, "cloudflare");
+        }
+        const errorRecord = error;
+        const message = typeof errorRecord?.message === "string"
+            ? errorRecord.message
+            : "Unknown error";
+        if (message.includes("Invalid API key") ||
+            message.includes("Authentication") ||
+            message.includes("401")) {
+            return new AuthenticationError("Invalid Cloudflare API key. Use a token with Workers AI Read+Write scope. Get one at https://dash.cloudflare.com/profile/api-tokens", "cloudflare");
+        }
+        if (message.includes("rate limit") || message.includes("429")) {
+            return new RateLimitError("Cloudflare Workers AI rate limit exceeded. Free-tier neurons reset daily.", "cloudflare");
+        }
+        if (message.includes("model_not_found") || message.includes("404")) {
+            return new InvalidModelError(`Cloudflare model '${this.modelName}' not found. Browse https://developers.cloudflare.com/workers-ai/models/`, "cloudflare");
+        }
+        return new ProviderError(`Cloudflare Workers AI error: ${message}`, "cloudflare");
+    }
+    async validateConfiguration() {
+        return typeof this.apiKey === "string" && this.apiKey.trim().length > 0;
+    }
+    getConfiguration() {
+        return {
+            provider: this.providerName,
+            model: this.modelName,
+            defaultModel: getDefaultCloudflareModel(),
+            baseURL: this.baseURL,
+        };
+    }
+}
+export default CloudflareProvider;
+//# sourceMappingURL=cloudflare.js.map

package/dist/lib/providers/cohere.d.ts

@@ -0,0 +1,52 @@
+import { type LanguageModel } from "ai";
+import type { AIProviderName } from "../constants/enums.js";
+import { BaseProvider } from "../core/baseProvider.js";
+import type { NeurolinkCredentials, StreamOptions, StreamResult, ValidationSchema } from "../types/index.js";
+/**
+ * Cohere Provider
+ *
+ * Routes Command R / Command R+ chat completions through Cohere's OpenAI-
+ * compatible endpoint. Embed v3 and Rerank v3 are top-tier for RAG but are
+ * accessed via the Cohere native SDK / dedicated embedding routes (out of
+ * scope for the LLM provider).
+ *
+ * @see https://docs.cohere.com/docs/compatibility-api
+ */
+export declare class CohereProvider extends BaseProvider {
+    private model;
+    private apiKey;
+    private baseURL;
+    constructor(modelName?: string, sdk?: unknown, _region?: string, credentials?: NeurolinkCredentials["cohere"]);
+    protected executeStream(options: StreamOptions, _analysisSchema?: ValidationSchema): Promise<StreamResult>;
+    private executeStreamInner;
+    protected getProviderName(): AIProviderName;
+    protected getDefaultModel(): string;
+    protected getAISDKModel(): LanguageModel;
+    protected formatProviderError(error: unknown): Error;
+    validateConfiguration(): Promise<boolean>;
+    getConfiguration(): {
+        provider: AIProviderName;
+        model: string;
+        defaultModel: string;
+        baseURL: string;
+    };
+    /**
+     * Default embedding model for Cohere.
+     */
+    protected getDefaultEmbeddingModel(): string;
+    /**
+     * Generate an embedding for a single text via Cohere's native /v2/embed
+     * endpoint. Returns the float[] embedding vector.
+     *
+     * The shared OpenAI-compatible /compatibility/v1 path is chat-only; embed
+     * lives on the native API (POST /v2/embed). Documented at
+     * https://docs.cohere.com/reference/embed.
+     */
+    embed(text: string, modelName?: string): Promise<number[]>;
+    /**
+     * Batch embedding via Cohere's native /v2/embed endpoint. Cohere caps at
+     * 96 inputs per request; larger batches are chunked.
+     */
+    embedMany(texts: string[], modelName?: string): Promise<number[][]>;
+}
+export default CohereProvider;

package/dist/lib/providers/cohere.js

@@ -0,0 +1,253 @@
+import { createOpenAI } from "@ai-sdk/openai";
+import { stepCountIs, streamText } from "ai";
+import { CohereModels } from "../constants/enums.js";
+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 { createLoggingFetch } from "../utils/loggingFetch.js";
+import { tracers, ATTR, withClientStreamSpan } from "../telemetry/index.js";
+import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../types/index.js";
+import { logger } from "../utils/logger.js";
+import { createCohereConfig, getProviderModel, validateApiKey, } from "../utils/providerConfig.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";
+/**
+ * Cohere uses an OpenAI-compatible endpoint at /compatibility/v1 that
+ * accepts the same chat-completions shape. Embeddings + Rerank live on
+ * the native API and are not exposed through this LLM provider class
+ * (use the Cohere SDK directly or the embed/rerank routes when added).
+ */
+const COHERE_DEFAULT_BASE_URL = "https://api.cohere.com/compatibility/v1";
+const getCohereApiKey = () => validateApiKey(createCohereConfig());
+const getDefaultCohereModel = () => getProviderModel("COHERE_MODEL", CohereModels.COMMAND_R_PLUS);
+/**
+ * Cohere Provider
+ *
+ * Routes Command R / Command R+ chat completions through Cohere's OpenAI-
+ * compatible endpoint. Embed v3 and Rerank v3 are top-tier for RAG but are
+ * accessed via the Cohere native SDK / dedicated embedding routes (out of
+ * scope for the LLM provider).
+ *
+ * @see https://docs.cohere.com/docs/compatibility-api
+ */
+export class CohereProvider extends BaseProvider {
+    model;
+    apiKey;
+    baseURL;
+    constructor(modelName, sdk, _region, credentials) {
+        const validatedNeurolink = isNeuroLink(sdk) ? sdk : undefined;
+        super(modelName, "cohere", validatedNeurolink);
+        const overrideApiKey = credentials?.apiKey?.trim();
+        this.apiKey =
+            overrideApiKey && overrideApiKey.length > 0
+                ? overrideApiKey
+                : getCohereApiKey();
+        this.baseURL =
+            credentials?.baseURL ??
+                process.env.COHERE_BASE_URL ??
+                COHERE_DEFAULT_BASE_URL;
+        const cohere = createOpenAI({
+            apiKey: this.apiKey,
+            baseURL: this.baseURL,
+            fetch: createLoggingFetch("cohere"),
+        });
+        this.model = cohere.chat(this.modelName);
+        logger.debug("Cohere Provider initialized", {
+            modelName: this.modelName,
+            providerName: this.providerName,
+            baseURL: this.baseURL,
+        });
+    }
+    async executeStream(options, _analysisSchema) {
+        // withClientStreamSpan: keeps the span open until the consumer reaches
+        // end-of-stream / error, so the recorded duration reflects the actual
+        // stream lifetime instead of just setup.
+        return withClientStreamSpan({
+            name: "neurolink.provider.stream",
+            tracer: tracers.provider,
+            attributes: {
+                [ATTR.GEN_AI_SYSTEM]: "cohere",
+                [ATTR.GEN_AI_MODEL]: this.modelName,
+                [ATTR.GEN_AI_OPERATION]: "stream",
+                [ATTR.NL_STREAM_MODE]: true,
+            },
+        }, async () => this.executeStreamInner(options), (r) => r.stream, (r, wrapped) => ({ ...r, stream: wrapped }));
+    }
+    async executeStreamInner(options) {
+        this.validateStreamOptions(options);
+        // Resolve per-call credentials first, then fall back to instance-level.
+        const perCallCreds = options.credentials?.cohere;
+        const effectiveApiKey = perCallCreds?.apiKey?.trim() || this.apiKey;
+        const effectiveBaseURL = perCallCreds?.baseURL || this.baseURL;
+        const startTime = Date.now();
+        const timeout = this.getTimeout(options);
+        const timeoutController = createTimeoutController(timeout, this.providerName, "stream");
+        try {
+            const shouldUseTools = !options.disableTools && this.supportsTools();
+            const tools = shouldUseTools
+                ? options.tools || (await this.getAllTools())
+                : {};
+            const messages = await this.buildMessagesForStream(options);
+            // When per-call credentials differ from instance, build a fresh client.
+            const hasDifferentCreds = effectiveApiKey !== this.apiKey || effectiveBaseURL !== this.baseURL;
+            const model = hasDifferentCreds
+                ? createOpenAI({
+                    apiKey: effectiveApiKey,
+                    baseURL: effectiveBaseURL,
+                    fetch: createLoggingFetch("cohere"),
+                }).chat(this.modelName)
+                : await this.getAISDKModelWithMiddleware(options);
+            const result = await streamText({
+                model,
+                messages,
+                temperature: options.temperature,
+                maxOutputTokens: options.maxTokens,
+                tools,
+                stopWhen: stepCountIs(options.maxSteps || DEFAULT_MAX_STEPS),
+                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 }) => {
+                    emitToolEndFromStepFinish(this.neurolink?.getEventEmitter(), toolResults);
+                    this.handleToolExecutionStorage(toolCalls, toolResults, options, new Date()).catch((error) => {
+                        logger.warn("[CohereProvider] Failed to store tool executions", {
+                            provider: this.providerName,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    });
+                },
+            });
+            timeoutController?.cleanup();
+            const transformedStream = this.createTextStream(result);
+            const analyticsPromise = streamAnalyticsCollector.createAnalytics(this.providerName, this.modelName, toAnalyticsStreamResult(result), Date.now() - startTime, {
+                requestId: `cohere-stream-${Date.now()}`,
+                streamingMode: true,
+            });
+            return {
+                stream: transformedStream,
+                provider: this.providerName,
+                model: this.modelName,
+                analytics: analyticsPromise,
+                metadata: { startTime, streamId: `cohere-${Date.now()}` },
+            };
+        }
+        catch (error) {
+            timeoutController?.cleanup();
+            throw this.handleProviderError(error);
+        }
+    }
+    getProviderName() {
+        return this.providerName;
+    }
+    getDefaultModel() {
+        return getDefaultCohereModel();
+    }
+    getAISDKModel() {
+        return this.model;
+    }
+    formatProviderError(error) {
+        if (error instanceof TimeoutError) {
+            return new NetworkError(`Request timed out: ${error.message}`, "cohere");
+        }
+        const errorRecord = error;
+        const message = typeof errorRecord?.message === "string"
+            ? errorRecord.message
+            : "Unknown error";
+        if (message.includes("invalid api token") ||
+            message.includes("Authentication") ||
+            message.includes("401") ||
+            message.includes("invalid_api_token")) {
+            return new AuthenticationError("Invalid Cohere API key. Check COHERE_API_KEY. Get one at https://dashboard.cohere.com/api-keys", "cohere");
+        }
+        if (message.includes("rate limit") || message.includes("429")) {
+            return new RateLimitError("Cohere rate limit exceeded. Back off and retry.", "cohere");
+        }
+        if (message.includes("model_not_found") || message.includes("404")) {
+            return new InvalidModelError(`Cohere model '${this.modelName}' not found. Use command-r, command-r-plus, or command-r7b-12-2024.`, "cohere");
+        }
+        if (message.includes("trial limit") || message.includes("trial_limit")) {
+            return new ProviderError("Cohere trial usage limit exceeded. Upgrade at https://dashboard.cohere.com/billing.", "cohere");
+        }
+        return new ProviderError(`Cohere error: ${message}`, "cohere");
+    }
+    async validateConfiguration() {
+        return typeof this.apiKey === "string" && this.apiKey.trim().length > 0;
+    }
+    getConfiguration() {
+        return {
+            provider: this.providerName,
+            model: this.modelName,
+            defaultModel: getDefaultCohereModel(),
+            baseURL: this.baseURL,
+        };
+    }
+    /**
+     * Default embedding model for Cohere.
+     */
+    getDefaultEmbeddingModel() {
+        return CohereModels.EMBED_ENGLISH_V3;
+    }
+    /**
+     * Generate an embedding for a single text via Cohere's native /v2/embed
+     * endpoint. Returns the float[] embedding vector.
+     *
+     * The shared OpenAI-compatible /compatibility/v1 path is chat-only; embed
+     * lives on the native API (POST /v2/embed). Documented at
+     * https://docs.cohere.com/reference/embed.
+     */
+    async embed(text, modelName) {
+        const vectors = await this.embedMany([text], modelName);
+        if (!vectors[0]) {
+            throw new ProviderError("Cohere /v2/embed returned no embeddings.", "cohere");
+        }
+        return vectors[0];
+    }
+    /**
+     * Batch embedding via Cohere's native /v2/embed endpoint. Cohere caps at
+     * 96 inputs per request; larger batches are chunked.
+     */
+    async embedMany(texts, modelName) {
+        if (texts.length === 0) {
+            return [];
+        }
+        const model = modelName ?? this.getDefaultEmbeddingModel();
+        const baseUrl = this.baseURL.replace(/\/compatibility\/v\d+\/?$/, "");
+        const url = `${baseUrl}/v2/embed`;
+        const BATCH_SIZE = 96;
+        const results = [];
+        for (let i = 0; i < texts.length; i += BATCH_SIZE) {
+            const batch = texts.slice(i, i + BATCH_SIZE);
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    model,
+                    texts: batch,
+                    input_type: "search_document",
+                    embedding_types: ["float"],
+                }),
+            });
+            if (!response.ok) {
+                const body = await response.text();
+                throw this.formatProviderError(new Error(`Cohere /v2/embed failed: ${response.status} — ${body.slice(0, 500)}`));
+            }
+            const json = (await response.json());
+            const floatVecs = json.embeddings?.float ??
+                (Array.isArray(json.embeddings) ? json.embeddings : undefined);
+            if (!floatVecs || floatVecs.length !== batch.length) {
+                throw new ProviderError(`Cohere /v2/embed returned ${floatVecs?.length ?? 0} embeddings for ${batch.length} inputs.`, "cohere");
+            }
+            results.push(...floatVecs);
+        }
+        return results;
+    }
+}
+export default CohereProvider;
+//# sourceMappingURL=cohere.js.map

package/dist/lib/providers/deepseek.js

@@ -1,11 +1,13 @@
-import { createOpenAI } from "@ai-sdk/openai";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { stepCountIs, streamText } from "ai";
 import { DeepSeekModels } from "../constants/enums.js";
 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, maskProxyUrl } from "../proxy/proxyFetch.js";
-import { tracers, ATTR, withClientSpan } from "../telemetry/index.js";
+import { tracers, ATTR, withClientStreamSpan } from "../telemetry/index.js";
+import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../types/index.js";
 import { logger } from "../utils/logger.js";
 import { createDeepSeekConfig, getProviderModel, validateApiKey, } from "../utils/providerConfig.js";
 import { composeAbortSignals, createTimeoutController, TimeoutError, } from "../utils/timeout.js";
@@ -58,9 +60,7 @@ export class DeepSeekProvider extends BaseProvider {
     apiKey;
     baseURL;
     constructor(modelName, sdk, _region, credentials) {
-        const validatedNeurolink = sdk && typeof sdk === "object" && "getInMemoryServers" in sdk
-            ? sdk
-            : undefined;
+        const validatedNeurolink = isNeuroLink(sdk) ? sdk : undefined;
         super(modelName, "deepseek", validatedNeurolink);
         // Trim the override before applying precedence. A blank/whitespace
         // `credentials.apiKey` should NOT bypass `getDeepSeekApiKey()` — that
@@ -75,14 +75,69 @@ export class DeepSeekProvider extends BaseProvider {
             credentials?.baseURL ??
                 process.env.DEEPSEEK_BASE_URL ??
                 DEEPSEEK_DEFAULT_BASE_URL;
-        const deepseek = createOpenAI({
+        // We deliberately use `@ai-sdk/openai-compatible` rather than
+        // `@ai-sdk/openai`. Two upstream behaviors of `@ai-sdk/openai` break us:
+        //   1. It always sends `response_format: { type: "json_schema" }` when a
+        //      schema is provided. DeepSeek's API rejects that with the literal
+        //      message "This response_format type is unavailable now".
+        //   2. It does not parse the `reasoning_content` field that
+        //      `deepseek-reasoner` emits, so chain-of-thought is silently dropped.
+        // `@ai-sdk/openai-compatible` honors `supportsStructuredOutputs: false`
+        // (falls back to `{ type: "json_object" }` and injects the schema into
+        // the prompt) and parses both `choice.message.reasoning_content` and
+        // `delta.reasoning_content` into the SDK-standard `reasoning` part.
+        const deepseek = createOpenAICompatible({
+            name: "deepseek",
             apiKey: this.apiKey,
             baseURL: this.baseURL,
             fetch: makeLoggingFetch("deepseek"),
+            supportsStructuredOutputs: false,
+            includeUsage: true,
+            // DeepSeek's `response_format: { type: "json_object" }` requires the
+            // prompt to literally contain the word "json" — otherwise the API
+            // rejects with: "Prompt must contain the word 'json' in some form to
+            // use 'response_format' of type 'json_object'." The OpenAI-compatible
+            // SDK fallback path (used because supportsStructuredOutputs is false)
+            // does not inject this guidance itself, so we prepend a system
+            // message when it's missing. No-op for non-JSON requests.
+            transformRequestBody: (body) => {
+                const rf = body
+                    .response_format;
+                if (rf?.type !== "json_object") {
+                    return body;
+                }
+                const messages = body
+                    .messages;
+                if (!Array.isArray(messages)) {
+                    return body;
+                }
+                const containsJsonWord = messages.some((m) => {
+                    const c = m?.content;
+                    if (typeof c === "string") {
+                        return /\bjson\b/i.test(c);
+                    }
+                    if (Array.isArray(c)) {
+                        return c.some((part) => typeof part?.text === "string" &&
+                            /\bjson\b/i.test(part.text));
+                    }
+                    return false;
+                });
+                if (containsJsonWord) {
+                    return body;
+                }
+                return {
+                    ...body,
+                    messages: [
+                        {
+                            role: "system",
+                            content: "Respond with valid JSON that satisfies the requested schema. Output JSON only — no prose, no markdown fencing.",
+                        },
+                        ...messages,
+                    ],
+                };
+            },
         });
-        // .chat() returns a Chat Completions model. The default factory call
-        // returns a Responses API model which OpenAI-compat providers don't implement.
-        this.model = deepseek.chat(this.modelName);
+        this.model = deepseek.chatModel(this.modelName);
         logger.debug("DeepSeek Provider initialized", {
             modelName: this.modelName,
             providerName: this.providerName,
@@ -90,7 +145,7 @@ export class DeepSeekProvider extends BaseProvider {
         });
     }
     async executeStream(options, _analysisSchema) {
-        return withClientSpan({
+        return withClientStreamSpan({
             name: "neurolink.provider.stream",
             tracer: tracers.provider,
             attributes: {
@@ -99,7 +154,7 @@ export class DeepSeekProvider 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);
@@ -176,7 +231,7 @@ export class DeepSeekProvider extends BaseProvider {
     }
     formatProviderError(error) {
         if (error instanceof TimeoutError) {
-            return new Error(`DeepSeek request timed out: ${error.message}`);
+            return new NetworkError(`Request timed out: ${error.message}`, "deepseek");
         }
         const errorRecord = error;
         const message = typeof errorRecord?.message === "string"
@@ -185,20 +240,20 @@ export class DeepSeekProvider extends BaseProvider {
         if (message.includes("Invalid API key") ||
             message.includes("Authentication") ||
             message.includes("401")) {
-            return new Error("Invalid DeepSeek API key. Please check your DEEPSEEK_API_KEY environment variable.");
+            return new AuthenticationError("Invalid DeepSeek API key. Please check your DEEPSEEK_API_KEY environment variable.", "deepseek");
         }
         if (message.includes("rate limit") || message.includes("429")) {
-            return new Error("DeepSeek rate limit exceeded");
+            return new RateLimitError("DeepSeek rate limit exceeded", "deepseek");
         }
         if (message.includes("Insufficient Balance") ||
             message.includes("insufficient_balance") ||
             message.includes("402")) {
-            return new Error("DeepSeek account has insufficient balance. Top up at https://platform.deepseek.com/usage");
+            return new ProviderError("DeepSeek account has insufficient balance. Top up at https://platform.deepseek.com/usage", "deepseek");
         }
         if (message.includes("model_not_found") || message.includes("404")) {
-            return new Error(`DeepSeek model '${this.modelName}' not found. Use 'deepseek-chat' or 'deepseek-reasoner'.`);
+            return new InvalidModelError(`DeepSeek model '${this.modelName}' not found. Use 'deepseek-chat' or 'deepseek-reasoner'.`, "deepseek");
         }
-        return new Error(`DeepSeek error: ${message}`);
+        return new ProviderError(`DeepSeek error: ${message}`, "deepseek");
     }
     async validateConfiguration() {
         return typeof this.apiKey === "string" && this.apiKey.trim().length > 0;

package/dist/lib/providers/fireworks.d.ts

@@ -0,0 +1,33 @@
+import { type LanguageModel } from "ai";
+import type { AIProviderName } from "../constants/enums.js";
+import { BaseProvider } from "../core/baseProvider.js";
+import type { NeurolinkCredentials, StreamOptions, StreamResult, ValidationSchema } from "../types/index.js";
+/**
+ * Fireworks AI Provider
+ *
+ * Hosted open-model serving at api.fireworks.ai/inference/v1
+ * (OpenAI-compatible). Best for low-latency at scale on Llama / Mixtral /
+ * Qwen / DeepSeek.
+ *
+ * @see https://docs.fireworks.ai/api-reference/introduction
+ */
+export declare class FireworksProvider extends BaseProvider {
+    private model;
+    private apiKey;
+    private baseURL;
+    constructor(modelName?: string, sdk?: unknown, _region?: string, credentials?: NeurolinkCredentials["fireworks"]);
+    protected executeStream(options: StreamOptions, _analysisSchema?: ValidationSchema): Promise<StreamResult>;
+    private executeStreamInner;
+    protected getProviderName(): AIProviderName;
+    protected getDefaultModel(): string;
+    protected getAISDKModel(): LanguageModel;
+    protected formatProviderError(error: unknown): Error;
+    validateConfiguration(): Promise<boolean>;
+    getConfiguration(): {
+        provider: AIProviderName;
+        model: string;
+        defaultModel: string;
+        baseURL: string;
+    };
+}
+export default FireworksProvider;