@nemesis-oss/ollama-sdk 1.14.0 → 1.16.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,
@@ -1649,6 +1686,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 +1702,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
@@ -6666,6 +6717,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;
@@ -7750,6 +7851,111 @@ var Agent = class {
   }
 };
 
+// src/draft-benchmark.ts
+var DEFAULT_DRAFT_TOKENS = 4;
+var DEFAULT_SAMPLES = 5;
+var DEFAULT_NUM_PREDICT = 256;
+var DEFAULT_SEED = 42;
+var DEFAULT_GAIN_THRESHOLD = 1.05;
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 1 ? sorted[mid] ?? 0 : ((sorted[mid - 1] ?? 0) + (sorted[mid] ?? 0)) / 2;
+}
+function roundTo(value, decimals) {
+  const factor = 10 ** decimals;
+  return Math.round(value * factor) / factor;
+}
+function requirePositiveInteger(name, value) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new RangeError(
+      `compareDraftPerformance: ${name} must be an integer >= 1 (got ${value}).`
+    );
+  }
+}
+async function runSide(client, options, draftNumPredict, samples, numPredict, seed) {
+  const samplingOptions = {
+    num_predict: numPredict,
+    temperature: 0,
+    seed,
+    draft_num_predict: draftNumPredict
+  };
+  if (options.warmup ?? true) {
+    await client.generate({
+      model: options.model,
+      prompt: options.prompt,
+      options: { ...samplingOptions, num_predict: 1 },
+      stream: false,
+      signal: options.signal
+    });
+  }
+  const tokensPerSecond = [];
+  const generationMs = [];
+  for (let i = 0; i < samples; i++) {
+    options.signal?.throwIfAborted();
+    const response = await client.generate({
+      model: options.model,
+      prompt: options.prompt,
+      options: samplingOptions,
+      stream: false,
+      signal: options.signal
+    });
+    const telemetry = formatTelemetry(response);
+    if (Number.isFinite(telemetry.tokensPerSecond) && telemetry.tokensPerSecond > 0) {
+      tokensPerSecond.push(telemetry.tokensPerSecond);
+      generationMs.push(telemetry.generationMs);
+    }
+  }
+  if (tokensPerSecond.length === 0) {
+    throw new OllamaClientError(
+      `compareDraftPerformance: every draft_num_predict=${draftNumPredict} sample returned a non-positive tokens/second. The model name is likely wrong, or the server returned empty generations.`,
+      { code: "draft_benchmark_no_valid_samples" }
+    );
+  }
+  return {
+    draftNumPredict,
+    medianTokensPerSecond: median(tokensPerSecond),
+    sampleTokensPerSecond: tokensPerSecond,
+    medianEvalDurationMs: median(generationMs)
+  };
+}
+async function compareDraftPerformance(client, options) {
+  const draftNumPredict = options.draftNumPredict ?? DEFAULT_DRAFT_TOKENS;
+  requirePositiveInteger("draftNumPredict", draftNumPredict);
+  const samples = options.samples ?? DEFAULT_SAMPLES;
+  requirePositiveInteger("samples", samples);
+  const numPredict = options.numPredict ?? DEFAULT_NUM_PREDICT;
+  requirePositiveInteger("numPredict", numPredict);
+  const seed = options.seed ?? DEFAULT_SEED;
+  if (!Number.isInteger(seed)) {
+    throw new RangeError(`compareDraftPerformance: seed must be an integer (got ${seed}).`);
+  }
+  const gainThreshold = options.gainThreshold ?? DEFAULT_GAIN_THRESHOLD;
+  if (!Number.isFinite(gainThreshold) || gainThreshold <= 0) {
+    throw new RangeError(
+      `compareDraftPerformance: gainThreshold must be a positive finite number (got ${gainThreshold}).`
+    );
+  }
+  options.signal?.throwIfAborted();
+  const baseline = await runSide(client, options, 0, samples, numPredict, seed);
+  const speculative = await runSide(client, options, draftNumPredict, samples, numPredict, seed);
+  const baselineTokensPerSec = roundTo(baseline.medianTokensPerSecond, 1);
+  const speculativeTokensPerSec = roundTo(speculative.medianTokensPerSecond, 1);
+  const speedupMultiplier = baselineTokensPerSec > 0 ? roundTo(speculativeTokensPerSec / baselineTokensPerSec, 2) : 0;
+  return {
+    model: options.model,
+    prompt: options.prompt,
+    draftNumPredict,
+    baselineTokensPerSec,
+    speculativeTokensPerSec,
+    speedupMultiplier,
+    effectiveGain: speedupMultiplier > gainThreshold,
+    gainThreshold,
+    baseline,
+    speculative
+  };
+}
+
 // src/affinity.ts
 var DEFAULT_CONCURRENT_MODELS = 1;
 var DEFAULT_PER_MODEL_CONCURRENCY = 1;
@@ -7957,6 +8163,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;
@@ -8011,6 +8218,7 @@ exports.checkChatContext = checkChatContext;
 exports.checkEndpointHealth = checkEndpointHealth;
 exports.checkGenerateContext = checkGenerateContext;
 exports.compactConversationHistory = compactConversationHistory;
+exports.compareDraftPerformance = compareDraftPerformance;
 exports.composeMiddleware = composeMiddleware;
 exports.contextWarningMessage = contextWarningMessage;
 exports.createConsoleLogger = createConsoleLogger;
@@ -8044,6 +8252,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;
@@ -8056,10 +8265,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;