@nemesis-oss/ollama-sdk 1.15.0 → 1.17.0

package/dist/index.cjs

@@ -393,6 +393,36 @@ var OllamaGenericClientError = class extends OllamaClientError {
 function isDomAbortError(error) {
   return typeof DOMException !== "undefined" && error instanceof DOMException && error.name === "AbortError";
 }
+var NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "EPIPE",
+  "ETIMEDOUT",
+  "ECONNABORTED",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "UND_ERR_SOCKET",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_CLOSED"
+]);
+var MAX_CAUSE_DEPTH = 4;
+function isNetworkLevelError(error) {
+  let current = error;
+  for (let depth = 0; depth < MAX_CAUSE_DEPTH && current !== void 0 && current !== null; depth += 1) {
+    if (typeof current === "object" && "code" in current) {
+      const code = current.code;
+      if (typeof code === "string" && NETWORK_ERROR_CODES.has(code)) {
+        return true;
+      }
+    }
+    current = current.cause;
+  }
+  return false;
+}
 function statusToError(status, message, options) {
   if (status === 401 || status === 403) {
     return new OllamaAuthError(message, { ...options, status });
@@ -424,6 +454,13 @@ function mapError(error, context = {}) {
       request: context.request
     });
   }
+  if (isNetworkLevelError(error)) {
+    const message2 = error instanceof Error && error.message ? error.message : "Network request failed";
+    return new OllamaNetworkError(message2, {
+      cause: error,
+      request: context.request
+    });
+  }
   if (error instanceof TypeError) {
     return new OllamaNetworkError(error.message || "Network request failed", {
       cause: error,
@@ -1076,6 +1113,18 @@ function createRequestId() {
   requestSequence += 1;
   return `ollama-http-${requestSequence}`;
 }
+function isWebReadableStreamBody(body) {
+  return typeof body === "object" && body !== null && typeof body.getReader === "function";
+}
+function buildFetchInit(req) {
+  return {
+    method: req.method,
+    headers: req.headers,
+    ...req.body !== void 0 ? { body: req.body } : {},
+    ...req.signal !== void 0 ? { signal: req.signal } : {},
+    ...isWebReadableStreamBody(req.body) ? { duplex: "half" } : {}
+  };
+}
 function sameHeaders(actual, expected) {
   const actualEntries = Object.fromEntries(
     Object.entries(actual).map(([key, value]) => [key.toLowerCase(), value])
@@ -1125,13 +1174,7 @@ var HttpClient = class {
       timestamp: startedAt
     });
     const finalHandler = async (req) => {
-      const init = {
-        method: req.method,
-        headers: req.headers,
-        ...req.body !== void 0 ? { body: req.body } : {},
-        ...req.signal !== void 0 ? { signal: req.signal } : {}
-      };
-      const response = await this.fetchImpl(req.url, init);
+      const response = await this.fetchImpl(req.url, buildFetchInit(req));
       rawResponse = response;
       const responseHeaders = response.headers && typeof response.headers.entries === "function" ? Object.fromEntries(response.headers.entries()) : {};
       return {
@@ -1142,12 +1185,7 @@ var HttpClient = class {
     };
     try {
       if (this.middleware.length === 0) {
-        const response2 = await this.fetchImpl(request.url, {
-          method: request.method,
-          headers: request.headers,
-          ...request.body !== void 0 ? { body: request.body } : {},
-          ...request.signal !== void 0 ? { signal: request.signal } : {}
-        });
+        const response2 = await this.fetchImpl(request.url, buildFetchInit(request));
         if (response2.status >= 200 && response2.status < 300) {
           this.onLifecycleEvent?.({
             type: "success",
@@ -1649,6 +1687,13 @@ function estimateGenerateRequestTokens(req) {
   if (req.images !== void 0) total += req.images.length * IMAGE_TOKEN_ESTIMATE;
   return total;
 }
+function recommendContextWindow(estimatedTokens) {
+  if (!Number.isFinite(estimatedTokens) || estimatedTokens <= 0) return 4096;
+  const target = estimatedTokens * 1.3;
+  let window = 4096;
+  while (window < target) window *= 2;
+  return window;
+}
 function checkChatContext(req, options = {}) {
   return check(estimateChatRequestTokens(req), req.options?.num_ctx, options);
 }
@@ -1658,39 +1703,46 @@ function checkGenerateContext(req, options = {}) {
 function check(estimatedPromptTokens, requestNumCtx, options) {
   const threshold = options.threshold ?? DEFAULT_CONTEXT_WARNING_THRESHOLD;
   if (requestNumCtx !== void 0) {
+    const exceeds2 = estimatedPromptTokens > requestNumCtx * threshold;
     return {
       estimatedPromptTokens,
       effectiveContextLength: requestNumCtx,
       windowSource: "request",
-      exceedsThreshold: estimatedPromptTokens > requestNumCtx * threshold
+      exceedsThreshold: exceeds2,
+      ...exceeds2 ? { recommendedNumCtx: recommendContextWindow(estimatedPromptTokens) } : {}
     };
   }
   if (options.defaultContextLength !== void 0) {
+    const exceeds2 = estimatedPromptTokens > options.defaultContextLength * threshold;
     return {
       estimatedPromptTokens,
       effectiveContextLength: options.defaultContextLength,
       windowSource: "client-default",
-      exceedsThreshold: estimatedPromptTokens > options.defaultContextLength * threshold
+      exceedsThreshold: exceeds2,
+      ...exceeds2 ? { recommendedNumCtx: recommendContextWindow(estimatedPromptTokens) } : {}
     };
   }
+  const exceeds = estimatedPromptTokens > OLLAMA_FALLBACK_CONTEXT_LENGTH;
   return {
     estimatedPromptTokens,
     effectiveContextLength: OLLAMA_FALLBACK_CONTEXT_LENGTH,
     windowSource: "server-fallback",
-    exceedsThreshold: estimatedPromptTokens > OLLAMA_FALLBACK_CONTEXT_LENGTH
+    exceedsThreshold: exceeds,
+    ...exceeds ? { recommendedNumCtx: recommendContextWindow(estimatedPromptTokens) } : {}
   };
 }
 var OLLAMA_FALLBACK_CONTEXT_LENGTH = 2048;
 function contextWarningMessage(check2, kind) {
   const where = `OllamaClient.${kind}()`;
   const estimate = `~${check2.estimatedPromptTokens} tokens`;
+  const suggestion = check2.recommendedNumCtx !== void 0 ? ` A window of at least ${check2.recommendedNumCtx} tokens would fit this prompt with ~30% headroom (see \`recommendContextWindow\`) \u2014 verify the model's native maximum via \`client.models.getContextLength()\` before adopting it.` : "";
   if (check2.windowSource === "request") {
-    return `${where}: estimated prompt size ${estimate} is close to or beyond the request's context window (num_ctx=${check2.effectiveContextLength}). The server will likely silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Raise \`options.num_ctx\` or shorten the conversation. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
+    return `${where}: estimated prompt size ${estimate} is close to or beyond the request's context window (num_ctx=${check2.effectiveContextLength}). The server will likely silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Raise \`options.num_ctx\` or shorten the conversation.${suggestion} Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
   }
   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. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
+    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. 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\`.`;
 }
 
 // src/context-discovery.ts
@@ -2724,7 +2776,7 @@ var ModelsClient = class {
       { model, singleEndpoint: true }
     );
   }
-  async createBlob(digest, data) {
+  async createBlob(digest, data, request) {
     await this.runner(
       (http, signal) => http.request({
         path: `/api/blobs/${encodeURIComponent(digest)}`,
@@ -2732,10 +2784,10 @@ var ModelsClient = class {
         rawBody: data,
         signal
       }),
-      { singleEndpoint: true }
+      { ...request, singleEndpoint: true }
     );
   }
-  async checkBlob(digest) {
+  async checkBlob(digest, request) {
     try {
       await this.runner(
         (http, signal) => http.request({
@@ -2743,7 +2795,7 @@ var ModelsClient = class {
           method: "HEAD",
           signal
         }),
-        { singleEndpoint: true }
+        { ...request, singleEndpoint: true }
       );
       return true;
     } catch (err) {
@@ -2785,9 +2837,32 @@ var ModelsClient = class {
    */
   async createBlobFromData(data, opts) {
     const digest = opts?.digest ?? await this.computeBlobDigest(data);
-    const alreadyExisted = await this.checkBlob(digest);
+    const alreadyExisted = await this.checkBlob(digest, opts);
+    if (!alreadyExisted) {
+      await this.createBlob(digest, data, opts);
+    }
+    return { digest, alreadyExisted };
+  }
+  /**
+   * Streams a blob upload straight from a web `ReadableStream` — the
+   * multi-gigabyte-safe counterpart of {@link createBlobFromData}. The body
+   * is never materialized in memory: the transport hands the stream to
+   * `fetch` directly (setting `duplex: 'half'`, which Node 18+ requires for
+   * stream bodies), so peak heap usage is a transport-level chunk, not the
+   * blob size.
+   *
+   * The digest must be known up front — it *is* the upload URL
+   * (`/api/blobs/<digest>`), the same content-addressed protocol
+   * `curl -T` performs. Hash first when you don't have it: in-memory bytes
+   * via {@link computeBlobDigest}, files via {@link createBlobFromFile}
+   * (which hashes in a streaming pass). The server verifies the streamed
+   * bytes against the digest and rejects mismatches, so a corrupted or
+   * truncated stream fails the upload instead of poisoning the store.
+   */
+  async createBlobFromStream(digest, stream, request) {
+    const alreadyExisted = await this.checkBlob(digest, request);
     if (!alreadyExisted) {
-      await this.createBlob(digest, data);
+      await this.createBlob(digest, stream, request);
     }
     return { digest, alreadyExisted };
   }
@@ -2796,16 +2871,61 @@ var ModelsClient = class {
    * `node:fs` import, so browser bundles never pull it in). The file name
    * (basename) is what `/api/create`'s `files` map expects as the key, so
    * this returns it alongside the digest.
+   *
+   * Streams both passes in fixed-size chunks — peak heap is O(chunk), not
+   * O(file), so multi-gigabyte GGUFs never enter the Node heap:
+   *
+   *  1. **Hash pass** (skipped when `opts.digest` is provided): the file is
+   *     streamed through `node:crypto`'s incremental SHA-256.
+   *  2. **Upload pass**: `node:fs` createReadStream → web ReadableStream →
+   *     `fetch` body with `duplex: 'half'` (see {@link createBlobFromStream}).
+   *
+   * A pre-existing blob (HEAD 200) skips the upload pass entirely, same as
+   * {@link createBlobFromData}.
    */
   async createBlobFromFile(path, opts) {
     const nodeFsModule = "node:fs";
-    const { promises: fs } = await import(nodeFsModule);
-    const data = await fs.readFile(path);
-    const result = await this.createBlobFromData(new Uint8Array(data), {
-      ...opts
-    });
+    const { createReadStream } = await import(nodeFsModule);
+    const nodeCryptoModule = "node:crypto";
+    const { createHash } = await import(nodeCryptoModule);
+    const nodeStreamModule = "node:stream";
+    const { Readable } = await import(nodeStreamModule);
+    const CHUNK_BYTES = 256 * 1024;
+    let digest = opts?.digest;
+    if (digest === void 0) {
+      const hash = createHash("sha256");
+      const hashStream = createReadStream(path, { highWaterMark: CHUNK_BYTES });
+      try {
+        for await (const chunk of hashStream) {
+          if (opts?.signal?.aborted) {
+            throw new OllamaAbortError("createBlobFromFile: aborted while hashing", {});
+          }
+          hash.update(chunk);
+        }
+      } finally {
+        hashStream.destroy();
+      }
+      digest = `sha256:${hash.digest("hex")}`;
+    }
+    const alreadyExisted = await this.checkBlob(digest, opts);
+    if (!alreadyExisted) {
+      const uploadStream = createReadStream(path, { highWaterMark: CHUNK_BYTES });
+      const onAbort = () => {
+        uploadStream.destroy();
+      };
+      opts?.signal?.addEventListener("abort", onAbort, { once: true });
+      try {
+        await this.createBlob(
+          digest,
+          Readable.toWeb(uploadStream),
+          opts
+        );
+      } finally {
+        opts?.signal?.removeEventListener("abort", onAbort);
+      }
+    }
     const fileName = path.split(/[\\/]/).pop() ?? path;
-    return { ...result, fileName };
+    return { digest, alreadyExisted, fileName };
   }
   /**
    * One-shot custom-model publishing from raw GGUF weights, following the
@@ -6145,8 +6265,8 @@ var OllamaClient = class _OllamaClient {
    */
   getContextLength = (request) => this.models.getContextLength(request);
   version = () => this.models.version();
-  createBlob = (digest, data) => this.models.createBlob(digest, data);
-  checkBlob = (digest) => this.models.checkBlob(digest);
+  createBlob = (digest, data, request) => this.models.createBlob(digest, data, request);
+  checkBlob = (digest, request) => this.models.checkBlob(digest, request);
   /**
    * Immediately unloads `model` from VRAM. Convenience alias for
    * {@link ModelsClient.unload} — see that method for the full
@@ -6666,6 +6786,56 @@ function toResponse(stream, init = {}) {
   return new Response(body, { ...init, headers });
 }
 
+// src/streaming/observe.ts
+async function* observeStream(source, callbacks = {}) {
+  const { onChunk, onError, onDone, onAbandon, onListenerError } = callbacks;
+  const reportListenerFailure = (error, phase) => {
+    try {
+      onListenerError?.(error, phase);
+    } catch {
+    }
+  };
+  let observerChain = Promise.resolve();
+  const dispatch2 = (phase, task) => {
+    observerChain = observerChain.then(task).then(
+      () => void 0,
+      (error) => {
+        reportListenerFailure(error, phase);
+      }
+    );
+  };
+  let state = "running";
+  try {
+    for await (const chunk of source) {
+      if (onChunk !== void 0) {
+        dispatch2("chunk", () => onChunk(chunk));
+      }
+      yield chunk;
+    }
+    state = "done";
+    if (onDone !== void 0) {
+      dispatch2("done", () => onDone());
+    }
+  } catch (error) {
+    state = "error";
+    try {
+      onError?.(error);
+    } catch (listenerError) {
+      reportListenerFailure(listenerError, "error");
+    }
+    throw error;
+  } finally {
+    if (state === "running") {
+      state = "abandoned";
+      try {
+        onAbandon?.();
+      } catch (listenerError) {
+        reportListenerFailure(listenerError, "abandoned");
+      }
+    }
+  }
+}
+
 // src/quota.ts
 var QuotaManager = class {
   now;
@@ -8062,6 +8232,7 @@ exports.ModelAffinityScheduler = ModelAffinityScheduler;
 exports.ModelsClient = ModelsClient;
 exports.NANOS_PER_MS = NANOS_PER_MS;
 exports.NANOS_PER_SECOND = NANOS_PER_SECOND;
+exports.NETWORK_ERROR_CODES = NETWORK_ERROR_CODES;
 exports.NOOP_LOGGER = NOOP_LOGGER;
 exports.OLLAMA_CLOUD_BASE_URL = OLLAMA_CLOUD_BASE_URL;
 exports.OLLAMA_FALLBACK_CONTEXT_LENGTH = OLLAMA_FALLBACK_CONTEXT_LENGTH;
@@ -8150,6 +8321,7 @@ exports.inferRuntimeMode = inferRuntimeMode;
 exports.isKeepAliveSugar = isKeepAliveSugar;
 exports.isKnownDoneReason = isKnownDoneReason;
 exports.isModelResident = isModelResident;
+exports.isNetworkLevelError = isNetworkLevelError;
 exports.isSameToolCall = isSameToolCall;
 exports.listAllMcpTools = listAllMcpTools;
 exports.listAvailableModels = listAvailableModels;
@@ -8162,10 +8334,12 @@ exports.normalizeChatStream = normalizeChatStream;
 exports.normalizeGenerateStream = normalizeGenerateStream;
 exports.normalizeKeepAlive = normalizeKeepAlive;
 exports.normalizeProgressStream = normalizeProgressStream;
+exports.observeStream = observeStream;
 exports.parseFrontmatter = parseFrontmatter;
 exports.parseNdjsonStream = parseNdjsonStream;
 exports.parseSseStream = parseSseStream;
 exports.parseStructuredOutput = parseStructuredOutput;
+exports.recommendContextWindow = recommendContextWindow;
 exports.registerMcpTools = registerMcpTools;
 exports.resolveContextLength = resolveContextLength;
 exports.resolveCredentialEndpoints = resolveCredentialEndpoints;