@molecule/api-ai-deepseek 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-ai-deepseek` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-ai-deepseek is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * DeepSeek AI provider for molecule.dev.
+ *
+ * @remarks
+ * Config: `DEEPSEEK_API_KEY` (SERVER-side only) plus an optional default model id/base URL.
+ *
+ * **Missing `DEEPSEEK_API_KEY` fails fast**: the provider throws naming the exact env var on
+ * first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
+ * not at bond/module-load time) — it never silently sends an empty key.
+ *
+ * **Error message disambiguation**: a plain 400 that ISN'T a context-length error (bad param,
+ * malformed tool schema) gets its own non-retryable message distinct from the generic
+ * "AI service error. Please try again." used for retryable failures.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+import type { AIProvider } from '@molecule/api-ai';
+/**
+ * The provider implementation.
+ */
+export declare const provider: AIProvider;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAMlD;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,UAUrB,CAAA"}

package/dist/index.js

@@ -0,0 +1,39 @@
+/**
+ * DeepSeek AI provider for molecule.dev.
+ *
+ * @remarks
+ * Config: `DEEPSEEK_API_KEY` (SERVER-side only) plus an optional default model id/base URL.
+ *
+ * **Missing `DEEPSEEK_API_KEY` fails fast**: the provider throws naming the exact env var on
+ * first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
+ * not at bond/module-load time) — it never silently sends an empty key.
+ *
+ * **Error message disambiguation**: a plain 400 that ISN'T a context-length error (bad param,
+ * malformed tool schema) gets its own non-retryable message distinct from the generic
+ * "AI service error. Please try again." used for retryable failures.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+import { createProvider } from './provider.js';
+/** Lazily-initialized provider singleton. Defers creation until first use so that env vars / secrets are resolved. */
+let _provider = null;
+/**
+ * The provider implementation.
+ */
+export const provider = new Proxy({}, {
+    get(_, prop, receiver) {
+        if (!_provider)
+            _provider = createProvider();
+        return Reflect.get(_provider, prop, receiver);
+    },
+    // set trap: methods run with `this` bound to the proxy — without it, instance-state writes land on the dummy target and are lost (see api-push-notifications-web-push)
+    set(_, prop, value) {
+        if (!_provider)
+            _provider = createProvider();
+        return Reflect.set(_provider, prop, value);
+    },
+});

package/dist/provider.d.ts

@@ -0,0 +1,90 @@
+/**
+ * DeepSeek implementation of AIProvider.
+ *
+ * Uses the DeepSeek API (OpenAI-compatible) for streaming chat completions with
+ * tool use and reasoning. DeepSeek's Chat Completions endpoint mirrors OpenAI's
+ * wire format (tool_calls, reasoning_content, prompt_tokens_details.cached_tokens),
+ * so this provider shares its shape with the xAI provider.
+ *
+ * @module
+ */
+import type { AIProvider, ChatEvent, ChatParams } from '@molecule/api-ai';
+import './secrets.js';
+import type { DeepseekConfig } from './types.js';
+/**
+ * DeepSeek AI provider that implements the `AIProvider` interface using
+ * DeepSeek's OpenAI-compatible Chat Completions API with support for streaming,
+ * tool use, and reasoning.
+ */
+declare class DeepseekAIProviderImpl implements AIProvider {
+    readonly name = "deepseek";
+    private apiKey;
+    private defaultModel;
+    private maxTokens;
+    private baseUrl;
+    private completionsPath;
+    private modelMap;
+    private onRateLimit?;
+    constructor(config?: DeepseekConfig);
+    /**
+     * Sends a chat request and yields streamed events (text chunks, tool use, done/error).
+     *
+     * @param params - Chat parameters including messages, model, system prompt, and tools.
+     * @yields {ChatEvent} Chat events including text chunks, tool use requests, done signals, and errors.
+     */
+    chat(params: ChatParams): AsyncIterable<ChatEvent>;
+    /**
+     * Converts internal `ChatMessage` objects to the OpenAI-compatible message format.
+     * System prompt is prepended as a system role message.
+     *
+     * @param messages - The chat messages to format.
+     * @param system - Optional system prompt to prepend.
+     * @returns The formatted messages array for the DeepSeek API.
+     */
+    private formatMessages;
+    /**
+     * Converts internal `AITool` definitions to the OpenAI function calling format.
+     *
+     * @param tools - The AI tool definitions to format.
+     * @returns The formatted tools array for the DeepSeek API.
+     */
+    private formatTools;
+    /**
+     * Parses a non-streaming OpenAI-compatible response into `ChatEvent` objects.
+     *
+     * @param data - The raw API response data to parse.
+     * @yields {ChatEvent} Chat events parsed from the response.
+     */
+    private parseNonStreamingResponse;
+    /**
+     * Parses a streaming SSE response from the DeepSeek API (OpenAI-compatible
+     * format), yielding `ChatEvent` objects as they arrive.
+     *
+     * @param response - The fetch Response with an SSE body stream.
+     * @yields {ChatEvent} Chat events as they arrive from the SSE stream.
+     */
+    private parseStreamingResponse;
+    /**
+     * Processes an array of SSE lines from the DeepSeek streaming response, yielding
+     * ChatEvent objects for text, thinking, tool use, and tool completion.
+     *
+     * @param lines - Raw SSE lines to process.
+     * @param pendingTools - Mutable map tracking tool call deltas accumulated across chunks.
+     * @param state - Mutable token usage counters.
+     * @yields {ChatEvent} Chat events extracted from the SSE lines.
+     */
+    private processSSELines;
+}
+/**
+ * Back-compat alias for the provider class (the scaffold exported this name).
+ */
+export declare const DeepseekAIProvider: typeof DeepseekAIProviderImpl;
+/**
+ * Creates a DeepSeek AI provider instance.
+ *
+ * @param config - DeepSeek-specific configuration (API key, model, max tokens, base URL).
+ * @returns An `AIProvider` backed by the DeepSeek Chat Completions API.
+ */
+export declare function createProvider(config?: DeepseekConfig): AIProvider;
+export {};
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,UAAU,EAGV,SAAS,EAET,UAAU,EAEX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAuBhD;;;;GAIG;AACH,cAAM,sBAAuB,YAAW,UAAU;IAChD,QAAQ,CAAC,IAAI,cAAa;IAC1B,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,WAAW,CAAC,CAAqB;gBAE7B,MAAM,GAAE,cAAmB;IAqBvC;;;;;OAKG;IACI,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC;IAoKzD;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IA4EtB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAE,yBAAyB;IAuDlC;;;;;;OAMG;YACY,sBAAsB;IAoFrC;;;;;;;;OAQG;IACH,OAAO,CAAE,eAAe;CAkIzB;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,+BAAyB,CAAA;AAExD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,UAAU,CAElE"}

package/dist/provider.js

@@ -0,0 +1,590 @@
+/**
+ * DeepSeek implementation of AIProvider.
+ *
+ * Uses the DeepSeek API (OpenAI-compatible) for streaming chat completions with
+ * tool use and reasoning. DeepSeek's Chat Completions endpoint mirrors OpenAI's
+ * wire format (tool_calls, reasoning_content, prompt_tokens_details.cached_tokens),
+ * so this provider shares its shape with the xAI provider.
+ *
+ * @module
+ */
+import { getLogger } from '@molecule/api-bond';
+import { t } from '@molecule/api-i18n';
+const logger = getLogger();
+// Side-effect import: registers this bond's secret definitions so the
+// runtime registry is populated even when provider.js is imported directly
+// (not through the package barrel).
+import './secrets.js';
+/**
+ * Map thinking budget tokens to a DeepSeek reasoning_effort level. DeepSeek V4
+ * accepts only `'high'` or `'max'` for `reasoning_effort`, so larger budgets map
+ * to `'max'` and everything else to `'high'`.
+ *
+ * @param budgetTokens - Requested thinking budget in tokens.
+ * @returns `'high'` or `'max'` for the upstream effort hint.
+ */
+function budgetToEffort(budgetTokens) {
+    return budgetTokens >= 12_000 ? 'max' : 'high';
+}
+/**
+ * DeepSeek AI provider that implements the `AIProvider` interface using
+ * DeepSeek's OpenAI-compatible Chat Completions API with support for streaming,
+ * tool use, and reasoning.
+ */
+class DeepseekAIProviderImpl {
+    name = 'deepseek';
+    apiKey;
+    defaultModel;
+    maxTokens;
+    baseUrl;
+    completionsPath;
+    modelMap;
+    onRateLimit;
+    constructor(config = {}) {
+        this.apiKey = config.apiKey ?? process.env.DEEPSEEK_API_KEY ?? '';
+        this.defaultModel = config.defaultModel ?? 'deepseek-v4-flash';
+        this.maxTokens = config.maxTokens ?? 4096;
+        this.baseUrl = config.baseUrl ?? process.env.DEEPSEEK_BASE_URL ?? 'https://api.deepseek.com';
+        this.completionsPath =
+            config.completionsPath ?? process.env.DEEPSEEK_COMPLETIONS_PATH ?? '/v1/chat/completions';
+        this.modelMap = config.modelMap ?? {};
+        this.onRateLimit = config.onRateLimit;
+        // Fail fast with an actionable local error rather than a cryptic 401 on the
+        // first request. The default `provider` export constructs lazily on first
+        // use (see index.ts), so this surfaces the moment the provider is actually
+        // used, not at bond/module-load time.
+        if (!this.apiKey) {
+            throw new Error('DEEPSEEK_API_KEY is not set. Add it to your environment to use the DeepSeek AI provider.');
+        }
+    }
+    /**
+     * Sends a chat request and yields streamed events (text chunks, tool use, done/error).
+     *
+     * @param params - Chat parameters including messages, model, system prompt, and tools.
+     * @yields {ChatEvent} Chat events including text chunks, tool use requests, done signals, and errors.
+     */
+    async *chat(params) {
+        // Canonical catalog id (used everywhere else); translate to the upstream's
+        // id only for the outbound request body via `modelMap`.
+        const canonicalModel = params.model ?? this.defaultModel;
+        const model = this.modelMap[canonicalModel] ?? canonicalModel;
+        const maxTokens = params.maxTokens ?? this.maxTokens;
+        const messages = this.formatMessages(params.messages, params.system);
+        const body = {
+            // Abuse attribution (see ChatParams.endUserId): OpenAI-compatible APIs
+            // scope enforcement by `user`, so an abusive tenant can be actioned
+            // individually instead of the org key that serves everyone. The value is
+            // the caller's opaque hash — never derived or logged here.
+            ...(params.endUserId ? { user: params.endUserId } : {}),
+            model,
+            // DeepSeek uses `max_tokens` (not OpenAI's newer `max_completion_tokens`,
+            // which it silently ignores).
+            max_tokens: maxTokens,
+            messages,
+            stream: params.stream !== false,
+            ...(params.stream !== false ? { stream_options: { include_usage: true } } : {}),
+        };
+        // Tools: merge custom tools (function format) and server tools
+        const functions = params.tools?.length ? this.formatTools(params.tools) : [];
+        const serverTools = (params.serverTools ?? []).map((st) => ({ ...st }));
+        const allTools = [...functions, ...serverTools];
+        if (allTools.length > 0) {
+            body.tools = allTools;
+            if (params.toolChoice === 'required') {
+                body.tool_choice = 'required';
+            }
+            else if (typeof params.toolChoice === 'object' && params.toolChoice?.type === 'tool') {
+                body.tool_choice = { type: 'function', function: { name: params.toolChoice.name } };
+            }
+        }
+        // DeepSeek V4 defaults `thinking` to ENABLED. Thinking mode requires the
+        // assistant's reasoning_content to be echoed back on every subsequent turn
+        // (a 400 otherwise) and is awkward to combine with the tool-calling loop, so
+        // we run non-thinking unless a thinking budget is explicitly requested. The
+        // chat handler gates that on the model's `supportsThinking` flag.
+        if (params.thinking) {
+            body.thinking = { type: 'enabled' };
+            // Prefer a caller-resolved native value ('high' | 'max') from the model
+            // catalog; fall back to the budget threshold.
+            body.reasoning_effort = params.thinking.effort ?? budgetToEffort(params.thinking.budgetTokens);
+        }
+        else {
+            body.thinking = { type: 'disabled' };
+            if (params.temperature !== undefined) {
+                body.temperature = params.temperature;
+            }
+        }
+        const headers = {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+        const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+        const signal = params.signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
+        // Retry with exponential backoff for rate limits (429) and overloaded (503)
+        const MAX_RETRIES = 3;
+        let response = null;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            response = await fetch(`${this.baseUrl}${this.completionsPath}`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+                signal,
+            });
+            if (response.status === 429 || response.status === 503) {
+                const willRetry = attempt < MAX_RETRIES;
+                // Retry-After is equally-valid as delta-seconds or an HTTP-date;
+                // parseInt on the date form yields NaN, degrading the backoff to a
+                // ~0ms retry against an already rate-limiting API. Guard it.
+                const retryAfter = response.headers.get('retry-after');
+                const parsedRetryAfterSeconds = retryAfter ? parseInt(retryAfter, 10) : NaN;
+                const hasRetryAfter = Number.isFinite(parsedRetryAfterSeconds) && parsedRetryAfterSeconds >= 0;
+                // Additive jitter (<500ms): concurrent callers rejected together must
+                // not sleep identical delays and re-arrive as the same burst.
+                const delayMs = willRetry
+                    ? (hasRetryAfter
+                        ? Math.min(parsedRetryAfterSeconds * 1000, 60_000)
+                        : Math.min(1000 * 2 ** attempt, 30_000)) + Math.floor(Math.random() * 500)
+                    : 0;
+                try {
+                    this.onRateLimit?.({
+                        provider: this.name,
+                        model,
+                        status: response.status,
+                        attempt: attempt + 1,
+                        willRetry,
+                        retryInMs: delayMs,
+                        ...(hasRetryAfter ? { retryAfterSeconds: parsedRetryAfterSeconds } : {}),
+                    });
+                }
+                catch (error) {
+                    // Host-app telemetry; its failure must never break the request.
+                    logger.warn('onRateLimit callback threw', { error });
+                }
+                if (willRetry) {
+                    logger.warn('DeepSeek API rate limited, retrying', {
+                        status: response.status,
+                        attempt: attempt + 1,
+                        delayMs,
+                    });
+                    await new Promise((resolve) => {
+                        const timer = setTimeout(resolve, delayMs);
+                        signal.addEventListener('abort', () => {
+                            clearTimeout(timer);
+                            resolve();
+                        }, { once: true });
+                    });
+                    if (signal.aborted)
+                        break;
+                    continue;
+                }
+            }
+            break;
+        }
+        if (!response.ok) {
+            const errorBody = await response.text();
+            let detail = `HTTP ${response.status}`;
+            try {
+                const parsed = JSON.parse(errorBody);
+                if (parsed.error?.message)
+                    detail = parsed.error.message;
+            }
+            catch (_error) {
+                // JSON.parse failed — raw text is already in `errorBody`; use it as-is.
+                if (errorBody.length > 0 && errorBody.length < 200)
+                    detail = errorBody;
+            }
+            logger.error('DeepSeek API error', { status: response.status, detail, errorBody });
+            const clientMessage = response.status === 429
+                ? 'AI rate limit exceeded. Please try again shortly.'
+                : response.status === 401
+                    ? 'AI service configuration error.'
+                    : response.status === 400 &&
+                        /prompt is too long|too many tokens|token.*limit|context.*length/i.test(detail)
+                        ? "Conversation too long for the model's context window. Use /compact to free space, or start a new conversation."
+                        : response.status === 400
+                            ? 'AI request was invalid — check the model and request parameters.'
+                            : response.status === 503
+                                ? 'AI service is temporarily overloaded. Please try again in a moment.'
+                                : 'AI service error. Please try again.';
+            yield { type: 'error', message: clientMessage, errorKey: 'ai.error.apiError' };
+            return;
+        }
+        if (params.stream === false) {
+            const data = (await response.json());
+            yield* this.parseNonStreamingResponse(data);
+            return;
+        }
+        yield* this.parseStreamingResponse(response);
+    }
+    /**
+     * Converts internal `ChatMessage` objects to the OpenAI-compatible message format.
+     * System prompt is prepended as a system role message.
+     *
+     * @param messages - The chat messages to format.
+     * @param system - Optional system prompt to prepend.
+     * @returns The formatted messages array for the DeepSeek API.
+     */
+    formatMessages(messages, system) {
+        const formatted = [];
+        if (system) {
+            formatted.push({ role: 'system', content: system });
+        }
+        for (const m of messages) {
+            if (m.role === 'system')
+                continue; // handled above
+            if (typeof m.content === 'string') {
+                formatted.push({ role: m.role, content: m.content });
+                continue;
+            }
+            // Content blocks — convert to OpenAI format
+            const blocks = m.content;
+            const parts = [];
+            const toolCalls = [];
+            const toolResults = [];
+            for (const block of blocks) {
+                switch (block.type) {
+                    case 'text':
+                        parts.push({ type: 'text', text: block.text });
+                        break;
+                    case 'image':
+                        parts.push({
+                            type: 'image_url',
+                            image_url: { url: `data:${block.mediaType};base64,${block.data}` },
+                        });
+                        break;
+                    case 'tool_use':
+                        toolCalls.push({
+                            id: block.id,
+                            type: 'function',
+                            function: { name: block.name, arguments: JSON.stringify(block.input) },
+                        });
+                        break;
+                    case 'tool_result':
+                        toolResults.push({
+                            role: 'tool',
+                            tool_call_id: block.tool_use_id,
+                            content: typeof block.content === 'string' ? block.content : JSON.stringify(block.content),
+                        });
+                        break;
+                    default:
+                        // document, audio, video — unsupported, skip
+                        break;
+                }
+            }
+            if (toolResults.length > 0) {
+                // Tool results are separate messages in OpenAI format
+                for (const tr of toolResults) {
+                    formatted.push(tr);
+                }
+            }
+            else if (toolCalls.length > 0) {
+                // Assistant message with tool calls
+                formatted.push({
+                    role: 'assistant',
+                    content: parts.length > 0 ? parts : null,
+                    tool_calls: toolCalls,
+                });
+            }
+            else {
+                formatted.push({
+                    role: m.role,
+                    content: parts.length === 1 && parts[0].type === 'text' ? parts[0].text : parts,
+                });
+            }
+        }
+        return formatted;
+    }
+    /**
+     * Converts internal `AITool` definitions to the OpenAI function calling format.
+     *
+     * @param tools - The AI tool definitions to format.
+     * @returns The formatted tools array for the DeepSeek API.
+     */
+    formatTools(tools) {
+        return tools.map((tool) => ({
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.parameters,
+            },
+        }));
+    }
+    /**
+     * Parses a non-streaming OpenAI-compatible response into `ChatEvent` objects.
+     *
+     * @param data - The raw API response data to parse.
+     * @yields {ChatEvent} Chat events parsed from the response.
+     */
+    *parseNonStreamingResponse(data) {
+        const choices = data.choices;
+        if (choices?.length) {
+            const message = choices[0].message;
+            if (message) {
+                // Reasoning/thinking content
+                if (message.reasoning_content && typeof message.reasoning_content === 'string') {
+                    yield { type: 'thinking', content: message.reasoning_content };
+                }
+                if (message.content && typeof message.content === 'string') {
+                    yield { type: 'text', content: message.content };
+                }
+                const toolCalls = message.tool_calls;
+                if (toolCalls) {
+                    for (const tc of toolCalls) {
+                        const fn = tc.function;
+                        let input = {};
+                        try {
+                            input = JSON.parse(fn.arguments);
+                        }
+                        catch (_error) {
+                            // JSON.parse failed — fall back to empty object; malformed args are non-fatal.
+                        }
+                        yield {
+                            type: 'tool_use',
+                            id: tc.id,
+                            name: fn.name,
+                            input,
+                        };
+                    }
+                }
+            }
+        }
+        const usage = data.usage;
+        const cached = usage?.prompt_tokens_details?.cached_tokens ?? 0;
+        yield {
+            type: 'done',
+            usage: {
+                // Report uncached input + cached separately (Anthropic semantics) so the
+                // consumer's context/cost math doesn't double-count the cached subset.
+                inputTokens: Math.max(0, (usage?.prompt_tokens ?? 0) - cached),
+                outputTokens: usage?.completion_tokens ?? 0,
+                cacheReadInputTokens: cached,
+            },
+        };
+    }
+    /**
+     * Parses a streaming SSE response from the DeepSeek API (OpenAI-compatible
+     * format), yielding `ChatEvent` objects as they arrive.
+     *
+     * @param response - The fetch Response with an SSE body stream.
+     * @yields {ChatEvent} Chat events as they arrive from the SSE stream.
+     */
+    async *parseStreamingResponse(response) {
+        const reader = response.body?.getReader();
+        if (!reader) {
+            yield {
+                type: 'error',
+                message: t('ai.error.noResponseBody'),
+                errorKey: 'ai.error.noResponseBody',
+            };
+            return;
+        }
+        const decoder = new TextDecoder();
+        let buffer = '';
+        const state = { inputTokens: 0, outputTokens: 0, cachedTokens: 0 };
+        // Track pending tool calls (accumulated across deltas). `started` guards the
+        // one-shot tool_use_start emission once the id + name are first known.
+        const pendingTools = new Map();
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? '';
+                let yieldedContent = false;
+                for (const event of this.processSSELines(lines, pendingTools, state)) {
+                    yieldedContent = true;
+                    yield event;
+                    // A mid-stream error (rate-limit/overload during high load, sent as a
+                    // `data: {"error": {...}}` chunk) means the turn was truncated. Stop
+                    // here and do NOT fall through to the trailing `done`, which would
+                    // report the truncated turn as a successful completion and skip the
+                    // consumer's overload/retry recovery.
+                    if (event.type === 'error')
+                        return;
+                }
+                // Signal liveness when the API sends data but no content events were produced
+                // (e.g., during extended reasoning with empty chunks or keepalive comments).
+                // This resets the consumer's stream timeout without forwarding to the client.
+                if (!yieldedContent) {
+                    yield { type: 'keep_alive' };
+                }
+            }
+            // Flush any remaining data in the buffer after EOF
+            if (buffer.trim()) {
+                for (const event of this.processSSELines(buffer.split('\n'), pendingTools, state)) {
+                    yield event;
+                    if (event.type === 'error')
+                        return;
+                }
+            }
+            // Emit any tool calls still pending after stream ends (safety net for missing finish_reason)
+            if (pendingTools.size > 0) {
+                for (const [, pending] of pendingTools) {
+                    let input = {};
+                    try {
+                        input = JSON.parse(pending.args);
+                    }
+                    catch (_error) {
+                        // JSON.parse failed — fall back to empty object; malformed args are non-fatal.
+                    }
+                    yield { type: 'tool_use', id: pending.id, name: pending.name, input };
+                }
+                pendingTools.clear();
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        yield {
+            type: 'done',
+            usage: {
+                inputTokens: Math.max(0, state.inputTokens - state.cachedTokens),
+                outputTokens: state.outputTokens,
+                cacheReadInputTokens: state.cachedTokens,
+            },
+        };
+    }
+    /**
+     * Processes an array of SSE lines from the DeepSeek streaming response, yielding
+     * ChatEvent objects for text, thinking, tool use, and tool completion.
+     *
+     * @param lines - Raw SSE lines to process.
+     * @param pendingTools - Mutable map tracking tool call deltas accumulated across chunks.
+     * @param state - Mutable token usage counters.
+     * @yields {ChatEvent} Chat events extracted from the SSE lines.
+     */
+    *processSSELines(lines, pendingTools, state) {
+        for (const line of lines) {
+            if (!line.startsWith('data: '))
+                continue;
+            const json = line.slice(6).trim();
+            if (json === '[DONE]')
+                continue;
+            try {
+                const event = JSON.parse(json);
+                // A mid-stream error arrives as a `data: {"error": {...}}` chunk (no
+                // `choices`) — most importantly rate-limit/overload during high load.
+                // Without this it matches no branch below and is silently dropped, so the
+                // stream falls through to a misleading `done` and the truncated turn reads
+                // as a successful completion. Surface it as a real error event (also
+                // satisfies the no-silent-swallow rule).
+                const streamError = event.error;
+                if (streamError) {
+                    const detail = `${streamError.code ?? streamError.type ?? ''} ${streamError.message ?? ''}`;
+                    logger.error('DeepSeek streaming error event', {
+                        type: streamError.type,
+                        code: streamError.code,
+                        message: streamError.message,
+                    });
+                    const clientMessage = /overload|capacity|503|529/i.test(detail)
+                        ? 'AI service is temporarily overloaded. Please try again in a moment.'
+                        : /rate.?limit|429|quota/i.test(detail)
+                            ? 'AI rate limit exceeded. Please try again shortly.'
+                            : 'AI service error. Please try again.';
+                    yield { type: 'error', message: clientMessage, errorKey: 'ai.error.apiError' };
+                    continue;
+                }
+                // Usage info (may appear in the final chunk)
+                const usage = event.usage;
+                if (usage) {
+                    if (usage.prompt_tokens)
+                        state.inputTokens = usage.prompt_tokens;
+                    if (usage.completion_tokens)
+                        state.outputTokens = usage.completion_tokens;
+                    if (usage.prompt_tokens_details?.cached_tokens)
+                        state.cachedTokens = usage.prompt_tokens_details.cached_tokens;
+                }
+                const choices = event.choices;
+                if (!choices?.length)
+                    continue;
+                const choice = choices[0];
+                const delta = choice.delta;
+                if (!delta)
+                    continue;
+                // Reasoning/thinking content
+                if (delta.reasoning_content && typeof delta.reasoning_content === 'string') {
+                    yield { type: 'thinking', content: delta.reasoning_content };
+                }
+                // Text content
+                if (delta.content && typeof delta.content === 'string') {
+                    yield { type: 'text', content: delta.content };
+                }
+                // Tool calls (accumulated across deltas)
+                const toolCalls = delta.tool_calls;
+                if (toolCalls) {
+                    for (const tc of toolCalls) {
+                        const idx = tc.index;
+                        const fn = tc.function;
+                        if (!pendingTools.has(idx)) {
+                            pendingTools.set(idx, {
+                                id: tc.id ?? '',
+                                name: fn?.name ? fn.name : '',
+                                args: '',
+                                started: false,
+                            });
+                        }
+                        const pending = pendingTools.get(idx);
+                        if (tc.id)
+                            pending.id = tc.id;
+                        if (fn?.name)
+                            pending.name = fn.name;
+                        // Surface the tool start once id + name are known, before the
+                        // arguments finish streaming, so the client shows activity immediately.
+                        if (!pending.started && pending.id && pending.name) {
+                            pending.started = true;
+                            yield { type: 'tool_use_start', id: pending.id, name: pending.name };
+                        }
+                        if (fn?.arguments) {
+                            const chunk = fn.arguments;
+                            pending.args += chunk;
+                            // Emit the chunk's char count as real progress (drives the live
+                            // token counter; re-arms the stream timeout) rather than a silent
+                            // keep_alive — just the count, not the content.
+                            yield { type: 'tool_input_delta', id: pending.id, chars: chunk.length, text: chunk };
+                        }
+                    }
+                }
+                // finish_reason signals completion
+                const finishReason = choice.finish_reason;
+                if (finishReason === 'tool_calls' || finishReason === 'stop') {
+                    // Emit any accumulated tool calls
+                    for (const [, pending] of pendingTools) {
+                        let input = {};
+                        try {
+                            input = JSON.parse(pending.args);
+                        }
+                        catch (_error) {
+                            // JSON.parse failed — fall back to empty object; malformed args are non-fatal.
+                        }
+                        yield {
+                            type: 'tool_use',
+                            id: pending.id,
+                            name: pending.name,
+                            input,
+                        };
+                    }
+                    pendingTools.clear();
+                }
+            }
+            catch (error) {
+                logger.debug('Skipping malformed SSE JSON line', { json, error });
+            }
+        }
+    }
+}
+/**
+ * Back-compat alias for the provider class (the scaffold exported this name).
+ */
+export const DeepseekAIProvider = DeepseekAIProviderImpl;
+/**
+ * Creates a DeepSeek AI provider instance.
+ *
+ * @param config - DeepSeek-specific configuration (API key, model, max tokens, base URL).
+ * @returns An `AIProvider` backed by the DeepSeek Chat Completions API.
+ */
+export function createProvider(config) {
+    return new DeepseekAIProviderImpl(config);
+}

package/dist/secrets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DeepSeek secret definitions — self-registered at import time so the
+ * runtime secrets registry (`@molecule/api-secrets`) can drive boot-time
+ * configuration reports and actionable "not configured" errors.
+ *
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
+ * packages sharing a key register byte-identical definitions and
+ * registration order never matters.
+ *
+ * @module
+ */
+import type { SecretDefinition } from '@molecule/api-secrets';
+/** Secret definitions required by the DeepSeek AI bond. */
+export declare const aiDeepseekSecretDefinitions: SecretDefinition[];
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAG7D,2DAA2D;AAC3D,eAAO,MAAM,2BAA2B,EAAE,gBAAgB,EAQzD,CAAA"}

package/dist/secrets.js

@@ -0,0 +1,24 @@
+/**
+ * DeepSeek secret definitions — self-registered at import time so the
+ * runtime secrets registry (`@molecule/api-secrets`) can drive boot-time
+ * configuration reports and actionable "not configured" errors.
+ *
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
+ * packages sharing a key register byte-identical definitions and
+ * registration order never matters.
+ *
+ * @module
+ */
+import { registerSecrets } from '@molecule/api-secrets';
+/** Secret definitions required by the DeepSeek AI bond. */
+export const aiDeepseekSecretDefinitions = [
+    {
+        key: 'DEEPSEEK_API_KEY',
+        description: 'DeepSeek API key — Create an API key on the DeepSeek open platform.',
+        helpUrl: 'https://platform.deepseek.com/api_keys',
+        required: true,
+        example: 'sk-...',
+    },
+];
+registerSecrets(aiDeepseekSecretDefinitions);

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * DeepSeek AI provider configuration.
+ *
+ * @module
+ */
+import type { AiRateLimitCallback } from '@molecule/api-ai';
+/**
+ * Configuration for DeepSeek.
+ */
+export interface DeepseekConfig {
+    /** API key. Defaults to DEEPSEEK_API_KEY env var. */
+    apiKey?: string;
+    /** Default model. Defaults to 'deepseek-v4-flash'. */
+    defaultModel?: string;
+    /** Maximum tokens for completions. */
+    maxTokens?: number;
+    /** Base URL override (for proxies). Defaults to 'https://api.deepseek.com'. */
+    baseUrl?: string;
+    /**
+     * Chat-completions path appended to {@link baseUrl}. Defaults to
+     * `/v1/chat/completions` (DeepSeek-direct puts the version in the path). Set
+     * this when the same open-weight model is served by a US OpenAI-compatible
+     * host whose version prefix lives in the base URL instead — e.g. DeepInfra:
+     * `baseUrl='https://api.deepinfra.com/v1/openai'` + `completionsPath='/chat/completions'`.
+     */
+    completionsPath?: string;
+    /**
+     * Optional catalog-id → upstream-model-id map, applied to the outbound request
+     * ONLY. Lets a US OpenAI-compatible host (DeepInfra) receive its namespaced id
+     * (`deepseek-ai/DeepSeek-V4-Flash`) while the rest of the platform — pricing,
+     * cost ceilings, display — keeps using the canonical catalog id
+     * (`deepseek-v4-flash`). An id not in the map passes through unchanged.
+     */
+    modelMap?: Record<string, string>;
+    /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
+    onRateLimit?: AiRateLimitCallback;
+}
+/**
+ * Process Env interface.
+ */
+export interface ProcessEnv {
+    DEEPSEEK_API_KEY: string;
+    /** Base URL override (for credential brokers / gateways / US OpenAI-compatible hosts). */
+    DEEPSEEK_BASE_URL?: string;
+    /** Chat-completions path override (see {@link DeepseekConfig.completionsPath}). */
+    DEEPSEEK_COMPLETIONS_PATH?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,wFAAwF;IACxF,WAAW,CAAC,EAAE,mBAAmB,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,gBAAgB,EAAE,MAAM,CAAA;IACxB,0FAA0F;IAC1F,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,mFAAmF;IACnF,yBAAyB,CAAC,EAAE,MAAM,CAAA;CACnC"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * DeepSeek AI provider configuration.
+ *
+ * @module
+ */
+export {};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@molecule/api-ai-deepseek",
+  "version": "1.0.0",
+  "description": "DeepSeek AI provider for molecule.dev",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "ai",
+    "deepseek"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@molecule/api-ai": "1.0.0",
+    "@molecule/api-bond": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "peerDependencies": {
+    "@molecule/api-ai": "^1.0.0",
+    "@molecule/api-bond": "^1.0.0",
+    "@molecule/api-i18n": "^1.0.0",
+    "@molecule/api-secrets": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@molecule/api-ai": {
+      "optional": true
+    }
+  }
+}