@nemesis-oss/ollama-sdk 1.18.0 → 1.19.1

package/dist/index.cjs

@@ -193,6 +193,11 @@ var OllamaAuthError = class extends OllamaClientError {
     super(message, { ...options, code: "auth_error", retryable: false });
   }
 };
+var OllamaPaymentRequiredError = class extends OllamaClientError {
+  constructor(message, options) {
+    super(message, { ...options, code: "payment_required", retryable: false, status: 402 });
+  }
+};
 var OllamaNotFoundError = class extends OllamaClientError {
   constructor(message, options) {
     super(message, { ...options, code: "not_found", retryable: false });
@@ -423,15 +428,56 @@ function isNetworkLevelError(error) {
   }
   return false;
 }
+function lookupHeader(headers, name) {
+  if (headers === void 0) {
+    return void 0;
+  }
+  const needle = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === needle) {
+      return value;
+    }
+  }
+  return void 0;
+}
+var HTTP_DATE_PATTERN = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+function parseRetryAfterMs(headerValue, now = Date.now()) {
+  if (headerValue === void 0) {
+    return void 0;
+  }
+  const trimmed = headerValue.trim();
+  if (trimmed === "") {
+    return void 0;
+  }
+  if (/^\d+$/.test(trimmed)) {
+    const seconds = Number(trimmed);
+    if (!Number.isSafeInteger(seconds)) {
+      return void 0;
+    }
+    return seconds * 1e3;
+  }
+  if (!HTTP_DATE_PATTERN.test(trimmed)) {
+    return void 0;
+  }
+  const instant = Date.parse(trimmed);
+  if (Number.isNaN(instant)) {
+    return void 0;
+  }
+  return Math.max(0, instant - now);
+}
 function statusToError(status, message, options) {
   if (status === 401 || status === 403) {
     return new OllamaAuthError(message, { ...options, status });
   }
+  if (status === 402) {
+    return new OllamaPaymentRequiredError(message, options);
+  }
   if (status === 404) {
     return new OllamaNotFoundError(message, { ...options, status });
   }
   if (status === 429) {
-    return new OllamaRateLimitError(message, { ...options, status });
+    const retryAfterMs = parseRetryAfterMs(lookupHeader(options.response?.headers, "retry-after"));
+    return new OllamaRateLimitError(message, { ...options, status, retryAfterMs });
   }
   if (status === 502) {
     return new OllamaBadGatewayError(message, { ...options });
@@ -1134,6 +1180,21 @@ function sameHeaders(actual, expected) {
   const expectedKeys = Object.keys(expectedEntries);
   return actualKeys.length === expectedKeys.length && expectedKeys.every((key) => actualEntries[key] === expectedEntries[key]);
 }
+function retryAfterHeaderFrom(response) {
+  try {
+    const headers = response?.headers;
+    if (headers === null || headers === void 0 || typeof headers.get !== "function") {
+      return void 0;
+    }
+    const value = headers.get("retry-after");
+    if (value === null || value === "") {
+      return void 0;
+    }
+    return { "retry-after": value };
+  } catch {
+    return void 0;
+  }
+}
 var HttpClient = class {
   baseUrl;
   apiKey;
@@ -1201,7 +1262,12 @@ var HttpClient = class {
             durationMs: Date.now() - startedAt,
             error: mapError(new Error(`HTTP ${response2.status}`), {
               request: { method: request.method, url: request.url },
-              response: { status: response2.status }
+              // Mirrors the middleware path, which reports context.headers:
+              // a 429 lifecycle event carries the server's Retry-After.
+              response: {
+                status: response2.status,
+                headers: retryAfterHeaderFrom(response2)
+              }
             }),
             timestamp: Date.now()
           });
@@ -1307,7 +1373,11 @@ var HttpClient = class {
             const message = typeof errorBody === "object" && errorBody !== null && "error" in errorBody ? String(errorBody.error) : `HTTP ${response.status} ${response.statusText}`;
             throw mapError(new Error(message), {
               request: { method, url },
-              response: { status: response.status, body: errorBody }
+              response: {
+                status: response.status,
+                headers: retryAfterHeaderFrom(response),
+                body: errorBody
+              }
             });
           }
           if (options.method === "HEAD" || response.status === 204) {
@@ -1372,7 +1442,11 @@ var HttpClient = class {
             const errorText = await response.text();
             throw mapError(new Error(errorText || `HTTP ${response.status}`), {
               request: { method, url },
-              response: { status: response.status, body: errorText }
+              response: {
+                status: response.status,
+                headers: retryAfterHeaderFrom(response),
+                body: errorText
+              }
             });
           }
           if (!response.body) {
@@ -1436,7 +1510,11 @@ var HttpClient = class {
             const errorText = await response.text();
             throw mapError(new Error(errorText || `HTTP ${response.status}`), {
               request: { method, url },
-              response: { status: response.status, body: errorText }
+              response: {
+                status: response.status,
+                headers: retryAfterHeaderFrom(response),
+                body: errorText
+              }
             });
           }
           if (!response.body) {
@@ -1742,7 +1820,7 @@ function contextWarningMessage(check2, kind) {
   if (check2.windowSource === "client-default") {
     return `${where}: estimated prompt size ${estimate} is close to or beyond the client's \`defaultContextLength\` (${check2.effectiveContextLength}, injected as \`num_ctx\`). The server will likely silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Raise \`defaultContextLength\`, set \`options.num_ctx\` per request, or shorten the conversation.${suggestion} Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
   }
-  return `${where}: estimated prompt size ${estimate} outright exceeds Ollama's conservative server-default context window (${OLLAMA_FALLBACK_CONTEXT_LENGTH}\u20134096 tokens when \`num_ctx\` is unset \u2014 model-dependent). Unless the model's default is larger, the server will silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Set \`options.num_ctx\` (or the client's \`defaultContextLength\`) to an explicit window to make truncation visible and controllable.${suggestion} Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
+  return `${where}: estimated prompt size ${estimate} outright exceeds the worst-case floor for the unset-\`num_ctx\` window (${OLLAMA_FALLBACK_CONTEXT_LENGTH} tokens \u2014 current daemons default higher, tiered by VRAM: 4096 / 32768 / 262144; \`OLLAMA_CONTEXT_LENGTH\` can override either way). If your daemon's effective window is that small, the server will silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Set \`options.num_ctx\` (or the client's \`defaultContextLength\`) to an explicit window \u2014 or discover the real one via \`client.models.getContextLength()\` \u2014 to make truncation visible and controllable.${suggestion} Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
 }
 
 // src/context-discovery.ts
@@ -2470,6 +2548,12 @@ function sleep(ms, signal) {
     signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
+function retryDelayMs(error, attempt, backoff) {
+  if (error instanceof OllamaRateLimitError && error.retryAfterMs !== void 0) {
+    return error.retryAfterMs;
+  }
+  return calculateBackoff(attempt, backoff);
+}
 async function withRetry(operation, config = DEFAULT_RETRY_CONFIG, signal) {
   let attempt = 0;
   while (true) {
@@ -2481,7 +2565,7 @@ async function withRetry(operation, config = DEFAULT_RETRY_CONFIG, signal) {
       if (attempt >= config.maxRetries || !shouldRetry(error, attempt)) {
         throw error;
       }
-      const delayMs = calculateBackoff(attempt, config.backoff);
+      const delayMs = retryDelayMs(error, attempt, config.backoff);
       config.onRetry?.(error, attempt, delayMs);
       await sleep(delayMs, signal);
       attempt += 1;
@@ -2650,7 +2734,8 @@ var ModelsClient = class {
   }
   /**
    * Discovers the model's real context window from the server — no more
-   * 2048/4096 guesswork. Consults, in precedence order:
+   * default-window guesswork (current daemons tier the unset-`num_ctx`
+   * default by VRAM: 4k / 32k / 256k). Consults, in precedence order:
    *
    *   1. `GET /api/ps` — the window the **running instance actually
    *      allocated** (exact, reflects the Modelfile `num_ctx` default and
@@ -2662,7 +2747,7 @@ var ModelsClient = class {
    *   3. `POST /api/show` `model_info["<arch>.context_length"]` — the
    *      model's **native GGUF maximum** (a ceiling to raise `num_ctx`
    *      toward, not the allocated window).
-   *   4. Fallback — Ollama's conservative unset-`num_ctx` default (2048).
+   *   4. Fallback — the 2048 worst-case floor for the unset-`num_ctx` window.
    *
    * The result carries every signal it found, so `nativeContextLength:
    * 131072` vs `contextLength: 4096` (a 32× gap seen in the official API
@@ -4425,14 +4510,25 @@ var OllamaRuntime = class {
       const hasImages = bodyHasImages(body);
       const maxBytesWithImages = req.operation.constraints?.maxRequestBytesWithImages;
       const maxBytesBase = req.operation.constraints?.maxRequestBytes;
-      const applicableLimit = hasImages && maxBytesWithImages !== void 0 ? maxBytesWithImages : maxBytesBase;
-      if (applicableLimit !== void 0 && serialized.byteLength > applicableLimit) {
+      const textAndSchemaBytes = hasImages ? serializeWithoutImages(body).byteLength : serialized.byteLength;
+      if (maxBytesBase !== void 0 && textAndSchemaBytes > maxBytesBase) {
+        throw new OllamaRequestTooLargeError(
+          `Operation ${req.operation.operationId} (${req.operation.method} ${req.operation.path}) text and schema (images excluded) is ${textAndSchemaBytes} bytes, exceeding the contract limit of ${maxBytesBase} bytes.`,
+          {
+            operationId: req.operation.operationId,
+            actualBytes: textAndSchemaBytes,
+            maxBytes: maxBytesBase,
+            request: { method: req.operation.method, url: req.operation.path }
+          }
+        );
+      }
+      if (maxBytesWithImages !== void 0 && serialized.byteLength > maxBytesWithImages) {
         throw new OllamaRequestTooLargeError(
-          `Operation ${req.operation.operationId} (${req.operation.method} ${req.operation.path}) request body is ${serialized.byteLength} bytes, exceeding the contract limit of ${applicableLimit} bytes` + (hasImages ? " (images limit)." : "."),
+          `Operation ${req.operation.operationId} (${req.operation.method} ${req.operation.path}) request body is ${serialized.byteLength} bytes, exceeding the contract limit of ${maxBytesWithImages} bytes (whole request, images included).`,
           {
             operationId: req.operation.operationId,
             actualBytes: serialized.byteLength,
-            maxBytes: applicableLimit,
+            maxBytes: maxBytesWithImages,
             request: { method: req.operation.method, url: req.operation.path }
           }
         );
@@ -4574,6 +4670,13 @@ function bodyHasImages(body) {
   const images = obj.images;
   return Array.isArray(images) && images.length > 0;
 }
+function serializeWithoutImages(body) {
+  if (typeof body === "object" && body !== null && !Array.isArray(body)) {
+    const { images: _images, ...rest } = body;
+    return serializeForByteCount(rest);
+  }
+  return serializeForByteCount(body);
+}
 function resolvePathParams(pathTemplate, pathParams) {
   if (!pathTemplate.includes("{")) return pathTemplate;
   const params = pathParams ?? {};
@@ -5326,7 +5429,7 @@ var systemOneOp = {
   path: "/v1/systemone",
   request: { $ref: "#/schemas/SystemOneRequest" },
   response: { $ref: "#/schemas/SystemOneResponse" },
-  environment: { local: true, cloud: false },
+  environment: { local: true, cloud: true },
   transport: { mode: "json", streaming: false },
   capabilities: {
     thinking: "unsupported",
@@ -5344,8 +5447,10 @@ var systemOneOp = {
   status: { documented: true, experimental: true },
   domain: "native",
   notes: [
-    "Local-only; Ollama Cloud rejects /v1/systemone.",
-    "64 KiB request limit without images, 32 MiB with images (includes JSON/base64 overhead).",
+    "Local and cloud: model accepts cloud models (e.g. clef:cloud); cloud models require Ollama >= 0.40.5 or the hosted https://ollama.com endpoint.",
+    "Local dual cap: text and schema (excluding images) within 64 KiB AND the whole request within 32 MiB, including base64 and JSON overhead.",
+    "Cloud requests: paid plan or usage credits required; up to 64 questions named with up to 100 ASCII letters, digits, `_`, `.`, or `-`; up to 4 images of at most 4 MiB and 16 megapixels each (8 MiB total); requests within 13 MiB; input within the model's 65,536-token context window.",
+    "401 when a cloud model is requested without signing in or with an invalid API key (through a local server the response includes a signin_url); 402 when the cloud model is not included in the Free plan or a payment fails.",
     "No tools, no generation controls (temperature, top_p, etc.).",
     "Vision is model-dependent: images are accepted by vision-weighted models (Clef/Clef Flash) but not by text-only models.",
     "Experimental: behavioral surface may change between Ollama releases."
@@ -6301,11 +6406,15 @@ var OllamaClient = class _OllamaClient {
    * 1–64 typed questions (choice, noul, or score) against a provided state
    * and returns typed answers with probabilities and confidence.
    *
-   * Local-only; requires Ollama >= 0.35.0. The runtime enforces the
-   * version constraint automatically (lazily fetching `/api/version` when
-   * `enforceVersion` is `'auto'` or `'strict'`) and rejects cloud-mode
-   * calls. Request size is checked client-side: 64 KiB without images,
-   * 32 MiB with images.
+   * Local and cloud (since the 2026-10-16 upstream System One cloud
+   * launch): `model` also accepts cloud models such as `clef:cloud` —
+   * cloud models require Ollama >= 0.40.5 or the hosted
+   * `https://ollama.com` endpoint. Requires Ollama >= 0.35.0 locally.
+   * The runtime enforces the version constraint automatically (lazily
+   * fetching `/api/version` when `enforceVersion` is `'auto'` or
+   * `'strict'`). Request size is checked client-side as a dual cap:
+   * text and schema (images excluded) within 64 KiB AND the whole
+   * request within 32 MiB.
    *
    * The generic `Q` parameter captures the caller's question map at
    * compile time, giving key-safe answer access:
@@ -6339,7 +6448,9 @@ var OllamaClient = class _OllamaClient {
    * through a local server. Requires an Ollama account API key: pass `apiKey` to the
    * client constructor or set `OLLAMA_API_KEY`. Applies the same default `timeoutMs` and
    * retry policy as inference calls, but never cross-endpoint-fails-over — there is only
-   * ever the one cloud endpoint to call.
+   * ever the one cloud endpoint to call. If the service answers 429 with a `Retry-After`
+   * header, the transport parses it into `OllamaRateLimitError.retryAfterMs` and the
+   * retry loop sleeps exactly that long instead of jittered backoff (see ADR 0035).
    */
   async webSearch(req) {
     const { count, max_results, ...rest } = req;
@@ -6370,8 +6481,11 @@ var OllamaClient = class _OllamaClient {
    * web search, and web fetch, bucketed by hour (`range: '24h'`) or day (`'7d'`/`'30d'`).
    *
    * See {@link OllamaClient.webSearch} for the cloud-endpoint/auth/timeout/retry
-   * behavior, which applies identically here. Query parameters mirror the official
-   * endpoint: `range` (`'24h' | '7d' | '30d'`, server default `'7d'`) and `scope`
+   * behavior, which applies identically here. The pinned contract documents this
+   * endpoint's 429 with a `Retry-After` header ("Seconds to wait before retrying"),
+   * which the SDK parses into `OllamaRateLimitError.retryAfterMs` and honors verbatim
+   * when retrying. Query parameters mirror the official endpoint: `range`
+   * (`'24h' | '7d' | '30d'`, server default `'7d'`) and `scope`
    * (`'self' | 'team'`, server default `'self'`; team scope requires a team admin).
    * Omitted options are left unset so the server applies its own defaults.
    *
@@ -6404,7 +6518,9 @@ var OllamaClient = class _OllamaClient {
    * object (`balance_usd`/`allowance_usd`/`period`) or, on legacy plans, session/weekly
    * percentage limits; the shape is discriminated at runtime by the server response.
    * See {@link OllamaClient.webSearch} for the cloud-endpoint/auth/timeout/retry
-   * behavior, which applies identically here.
+   * behavior, which applies identically here. Like `/api/usage`, the pinned contract
+   * documents this endpoint's 429 with a `Retry-After` header, parsed into
+   * `OllamaRateLimitError.retryAfterMs` and honored verbatim when retrying (ADR 0035).
    *
    * ```ts
    * const balance = await client.balance();
@@ -6690,6 +6806,21 @@ function sleep2(ms, signal) {
     signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
+function retryAfterMsFromResponse(response) {
+  try {
+    const headers = response?.headers;
+    if (headers === null || headers === void 0 || typeof headers.get !== "function") {
+      return void 0;
+    }
+    const value = headers.get("retry-after");
+    if (value === null || value === "") {
+      return void 0;
+    }
+    return parseRetryAfterMs(value);
+  } catch {
+    return void 0;
+  }
+}
 async function fetchWithBackoff(input, init, config = {}) {
   const fetchImpl = config.fetch ?? globalThis.fetch;
   if (typeof fetchImpl !== "function") {
@@ -6711,7 +6842,8 @@ async function fetchWithBackoff(input, init, config = {}) {
         ...signal !== void 0 ? { signal } : {}
       });
       if (RETRYABLE_STATUS_CODES.has(response.status) && attempt < maxRetries) {
-        const delayMs = calculateBackoff(attempt, backoff);
+        const serverDelayMs = response.status === 429 ? retryAfterMsFromResponse(response) : void 0;
+        const delayMs = serverDelayMs ?? calculateBackoff(attempt, backoff);
         config.onRetry?.(attempt, response.status, delayMs);
         await sleep2(delayMs, signal);
         continue;
@@ -8256,8 +8388,9 @@ function createModelAffinityScheduler(client, options) {
 // src/system-one.ts
 var MAX_SYSTEM_ONE_IMAGES_BYTES = 32 * 1024 * 1024;
 var MAX_SYSTEM_ONE_REQUEST_BYTES = 64 * 1024;
-function estimateSystemOneRequestBytes(request) {
-  return new TextEncoder().encode(JSON.stringify(request)).byteLength;
+function estimateSystemOneRequestBytes(request, options) {
+  const body = options?.excludeImages && request.images !== void 0 ? { ...request, images: void 0 } : request;
+  return new TextEncoder().encode(JSON.stringify(body)).byteLength;
 }
 
 exports.ATTR_GEN_AI_OPERATION_NAME = ATTR_GEN_AI_OPERATION_NAME;
@@ -8325,6 +8458,7 @@ exports.OllamaModelRoutingError = OllamaModelRoutingError;
 exports.OllamaNetworkError = OllamaNetworkError;
 exports.OllamaNotFoundError = OllamaNotFoundError;
 exports.OllamaOverloadedError = OllamaOverloadedError;
+exports.OllamaPaymentRequiredError = OllamaPaymentRequiredError;
 exports.OllamaQuotaExceededError = OllamaQuotaExceededError;
 exports.OllamaRateLimitError = OllamaRateLimitError;
 exports.OllamaRequestTooLargeError = OllamaRequestTooLargeError;
@@ -8414,6 +8548,7 @@ exports.observeStream = observeStream;
 exports.onProgress = onProgress;
 exports.parseFrontmatter = parseFrontmatter;
 exports.parseNdjsonStream = parseNdjsonStream;
+exports.parseRetryAfterMs = parseRetryAfterMs;
 exports.parseSseStream = parseSseStream;
 exports.parseStructuredOutput = parseStructuredOutput;
 exports.recommendContextWindow = recommendContextWindow;