@molecule/api-ai-deepseek 1.0.14 → 1.1.0

package/dist/provider.d.ts

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import type { AIProvider, ChatEvent, ChatParams } from '@molecule/api-ai';
+import type { AIProvider, ChatEvent, ChatParams, ImageInputSize, ImageInputTokenEstimate } from '@molecule/api-ai';
 import './secrets.js';
 import type { DeepseekConfig } from './types.js';
 /** How long a stream may wait for its first content event. */
@@ -38,6 +38,26 @@ declare class DeepseekAIProviderImpl implements AIProvider {
      * @yields {ChatEvent} Chat events including text chunks, tool use requests, done signals, and errors.
      */
     chat(params: ChatParams): AsyncIterable<ChatEvent>;
+    /**
+     * DeepSeek's own documented price for one image, in input tokens.
+     *
+     * Priced only when BOTH conditions hold: the request is going to DeepSeek's
+     * own documented endpoint ({@link isNativeDeepseekEndpoint}), and the model
+     * the wire will carry is a documented DeepSeek vision id. The alias is
+     * resolved exactly the way {@link chat} resolves it — the bond's `modelMap`
+     * first, a miss passing through unchanged — so a host that renames the model
+     * on the wire (a US re-host) is priced under the id it actually serves, and a
+     * custom endpoint that keeps the native names is still unknown because
+     * another backend does the billing. Anything else — another model, another
+     * format, another endpoint — is an explicit unknown rather than DeepSeek's
+     * ceiling.
+     *
+     * @param image - The selected catalog model id and the image's media type.
+     * @returns 1024 tokens per image for a documented vision model and a
+     *   supported format on DeepSeek's own endpoint, otherwise an explicit
+     *   unknown.
+     */
+    estimateImageInputTokens(image: ImageInputSize): ImageInputTokenEstimate;
     /**
      * POST the chat body, retrying with exponential backoff on a rate-limited
      * (429) or overloaded (503) status. Extracted from {@link chat} so the

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EACV,UAAU,EAIV,SAAS,EAET,UAAU,EAIX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAgHhD,8DAA8D;AAC9D,eAAO,MAAM,8BAA8B,QAAS,CAAA;AAgGpD;;;;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;IACzC,OAAO,CAAC,aAAa,CAAC,CAAuB;IAC7C,OAAO,CAAC,mBAAmB,CAAQ;IACnC,OAAO,CAAC,sBAAsB,CAAQ;gBAE1B,MAAM,GAAE,cAAmB;IAwBvC;;;;;OAKG;IACI,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC;IAoRzD;;;;;;;;;OASG;YACW,2BAA2B;IA0EzC;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,cAAc;IA8FtB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAE,yBAAyB;IA+ElC;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;IAUlB;;;;;;;;;;;;OAYG;YACY,sBAAsB;IA2GrC;;;;;;;;;;OAUG;IACH,OAAO,CAAE,eAAe;CAwOzB;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,+BAAyB,CAAA;AAExD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,UAAU,CAElE"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EACV,UAAU,EAIV,SAAS,EAET,UAAU,EAEV,cAAc,EACd,uBAAuB,EAGxB,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAgHhD,8DAA8D;AAC9D,eAAO,MAAM,8BAA8B,QAAS,CAAA;AA+LpD;;;;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;IACzC,OAAO,CAAC,aAAa,CAAC,CAAuB;IAC7C,OAAO,CAAC,mBAAmB,CAAQ;IACnC,OAAO,CAAC,sBAAsB,CAAQ;gBAE1B,MAAM,GAAE,cAAmB;IAwBvC;;;;;OAKG;IACI,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC;IAoRzD;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,uBAAuB;IAQxE;;;;;;;;;OASG;YACW,2BAA2B;IA0EzC;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,cAAc;IA8FtB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAE,yBAAyB;IA+ElC;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;IAUlB;;;;;;;;;;;;OAYG;YACY,sBAAsB;IA2GrC;;;;;;;;;;OAUG;IACH,OAAO,CAAE,eAAe;CAwOzB;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

@@ -9,6 +9,7 @@
  * @module
  */
 import { randomUUID } from 'node:crypto';
+import { URL } from 'node:url';
 import { getLogger } from '@molecule/api-bond';
 import { t } from '@molecule/api-i18n';
 const logger = getLogger();
@@ -41,6 +42,101 @@ const MAX_TIMER_MS = 2_147_483_647;
  * A longer list is sent truncated rather than refused by the API.
  */
 const MAX_STOP_SEQUENCES = 16;
+/**
+ * Model ids DeepSeek documents as accepting image input (vision guide, read
+ * 2026-10-25): `deepseek-flash` takes images alongside text, and the retired
+ * `deepseek-v4-flash-vision-exp` id is still accepted and served by the latest
+ * Flash model. Any other id — including one this bond's own `modelMap` sends to
+ * a different host — has no documented image rule, so it answers unknown.
+ *
+ * A documented id is necessary but not sufficient: the ceiling is a fact about
+ * DeepSeek's OWN backend, so it is applied only when the request is going to
+ * DeepSeek's own documented endpoint (see {@link isNativeDeepseekEndpoint}).
+ */
+const VISION_MODEL_IDS = ['deepseek-flash', 'deepseek-v4-flash-vision-exp'];
+/**
+ * The image formats the vision guide lists as supported: JPEG, PNG, GIF and
+ * WebP. A payload of any other type is not covered by the token rule.
+ */
+const VISION_MEDIA_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
+/**
+ * DeepSeek's documented ceiling for ONE image, in input tokens: the guide states
+ * "there is an upper bound of 1024 tokens per image", each image "counted
+ * independently under the same rule" with no separate multi-image calculation.
+ * Images below roughly 544×544 are scaled up and larger ones down to roughly
+ * 1300×1300, so the bound holds whatever the source dimensions are — including
+ * `detail: 'low'` (downscaled to 512×512) and `'original'`/`'auto'`.
+ *
+ * The request-level limits around it (32 MiB per base64 image, 8192 px per side,
+ * images in `user` messages only) reject an unusable request rather than change
+ * the price, so this bond prices the image alone and leaves message placement to
+ * the caller that knows it.
+ */
+const VISION_TOKENS_PER_IMAGE_UPPER_BOUND = 1024;
+/**
+ * The host DeepSeek documents as its own API endpoint. The per-image ceiling is
+ * a fact about THIS backend's accounting; the same model ids served by a
+ * gateway, a proxy or another OpenAI-compatible host are billed by that host's
+ * rule, which this bond cannot point at documentation for.
+ */
+const NATIVE_ENDPOINT_HOST = 'api.deepseek.com';
+/**
+ * The chat-completions path DeepSeek documents, in both of its published base
+ * URL forms: `https://api.deepseek.com` + `/chat/completions`, and
+ * `https://api.deepseek.com/v1` + `/chat/completions` (this bond's default is
+ * the root base with `/v1/chat/completions`).
+ */
+const NATIVE_COMPLETIONS_PATHS = ['/v1/chat/completions', '/chat/completions'];
+/**
+ * Whether the endpoint this bond will actually POST to is DeepSeek's own
+ * documented HTTPS endpoint.
+ *
+ * The documented per-image ceiling belongs to DeepSeek's backend, and a
+ * `baseUrl`, `DEEPSEEK_BASE_URL` or `completionsPath` can point this bond at a
+ * gateway, a proxy or another provider's OpenAI-compatible host. Model alias
+ * resolution alone cannot catch that: a custom endpoint may keep the native
+ * model names, so the wire still says `deepseek-flash` while another backend
+ * does the billing. Only the RESOLVED endpoint can say which backend it is.
+ *
+ * Parsed with the WHATWG URL parser, so the answer is about the endpoint as the
+ * request will be sent: https only, the exact hostname, no explicit
+ * non-default port (an explicit `:443` normalizes away, being the same
+ * endpoint), no credentials, no query or fragment, and a pathname equal to one
+ * of the two documented completions paths. Neither the parser nor the request
+ * normalizes duplicate or trailing slashes, so a base URL carrying one composes
+ * to a different path — `/v1/chat/completions/` or `//v1/chat/completions` —
+ * which is not native; anything else (another host, a port, a query, a
+ * fragment, an unparsable or relative URL) is not native either.
+ *
+ * Returns a boolean only: no part of the URL is logged, and nothing here reads,
+ * echoes or reports a credential.
+ *
+ * @param endpoint - The resolved request URL, `baseUrl + completionsPath`.
+ * @returns True only for DeepSeek's own documented endpoint.
+ */
+function isNativeDeepseekEndpoint(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch (_error) {
+        // Not a URL this bond can reason about, so the documented rule does not
+        // apply. The caller answers unknown, which needs neither a log line nor an
+        // echo of the value that failed to parse.
+        return false;
+    }
+    if (url.protocol !== 'https:')
+        return false;
+    if (url.hostname !== NATIVE_ENDPOINT_HOST)
+        return false;
+    if (url.port !== '')
+        return false;
+    if (url.username !== '' || url.password !== '')
+        return false;
+    if (url.search !== '' || url.hash !== '')
+        return false;
+    return NATIVE_COMPLETIONS_PATHS.includes(url.pathname);
+}
 /**
  * Resolve a stream bound from the config, then the environment, then the
  * default. A value that is not a positive finite number is IGNORED rather than
@@ -410,6 +506,35 @@ class DeepseekAIProviderImpl {
             }
         }
     }
+    /**
+     * DeepSeek's own documented price for one image, in input tokens.
+     *
+     * Priced only when BOTH conditions hold: the request is going to DeepSeek's
+     * own documented endpoint ({@link isNativeDeepseekEndpoint}), and the model
+     * the wire will carry is a documented DeepSeek vision id. The alias is
+     * resolved exactly the way {@link chat} resolves it — the bond's `modelMap`
+     * first, a miss passing through unchanged — so a host that renames the model
+     * on the wire (a US re-host) is priced under the id it actually serves, and a
+     * custom endpoint that keeps the native names is still unknown because
+     * another backend does the billing. Anything else — another model, another
+     * format, another endpoint — is an explicit unknown rather than DeepSeek's
+     * ceiling.
+     *
+     * @param image - The selected catalog model id and the image's media type.
+     * @returns 1024 tokens per image for a documented vision model and a
+     *   supported format on DeepSeek's own endpoint, otherwise an explicit
+     *   unknown.
+     */
+    estimateImageInputTokens(image) {
+        if (!isNativeDeepseekEndpoint(`${this.baseUrl}${this.completionsPath}`))
+            return { known: false };
+        const upstream = this.modelMap[image.model] ?? image.model;
+        if (!VISION_MODEL_IDS.includes(upstream))
+            return { known: false };
+        if (!VISION_MEDIA_TYPES.includes(image.mediaType.toLowerCase()))
+            return { known: false };
+        return { known: true, upperBoundTokens: VISION_TOKENS_PER_IMAGE_UPPER_BOUND };
+    }
     /**
      * POST the chat body, retrying with exponential backoff on a rate-limited
      * (429) or overloaded (503) status. Extracted from {@link chat} so the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-deepseek",
-  "version": "1.0.14",
+  "version": "1.1.0",
   "description": "DeepSeek AI provider for molecule.dev",
   "homepage": "https://www.molecule.dev/packages/api-ai-deepseek",
   "type": "module",
@@ -33,7 +33,7 @@
     "directory": "packages/api/bonds/ai/deepseek"
   },
   "devDependencies": {
-    "@molecule/api-ai": "1.3.5",
+    "@molecule/api-ai": "1.4.0",
     "@molecule/api-bond": "1.0.3",
     "@types/node": "26.6.5",
     "typescript": "6.0.3",