@nemesis-oss/ollama-sdk 1.9.0 → 1.10.0

package/dist/index.js

@@ -4472,6 +4472,130 @@ function contextWarningMessage(check2, kind) {
   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\`.`;
 }
 
+// src/embed-batch.ts
+var DEFAULT_EMBED_BATCH_SIZE = 32;
+var DEFAULT_EMBED_CONCURRENCY = 3;
+function findOversizedEmbedInputs(input, contextLength) {
+  const oversized = [];
+  for (let index = 0; index < input.length; index++) {
+    const text = input[index];
+    if (text === void 0) continue;
+    const estimate = estimateTokens(text);
+    if (estimate > contextLength) {
+      oversized.push({ index, estimate });
+    }
+  }
+  return oversized;
+}
+function embedBatchOverflowMessage(oversized, totalInputs, contextLength, truncateFalse) {
+  const shown = oversized.slice(0, 5).map((entry) => `#${entry.index} (~${entry.estimate} tokens)`);
+  const elided = oversized.length > 5 ? `, +${oversized.length - 5} more` : "";
+  const outcome = truncateFalse ? "the server will reject them (`truncate: false`)" : "Ollama will silently truncate them, producing degraded vectors";
+  return `embedBatch: ${oversized.length} of ${totalInputs} input strings exceed the ${contextLength}-token context window (${shown.join(", ")}${elided}). ${outcome}. Raise \`options.num_ctx\`, pre-split long inputs, or set \`truncate: true\` explicitly to acknowledge truncation.`;
+}
+function assertPositiveInteger(value, field) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new OllamaClientError(
+      `embedBatch: \`${field}\` must be a positive integer (got ${value}).`,
+      { code: "invalid_request" }
+    );
+  }
+}
+async function batchEmbed(client, options) {
+  const { model, input } = options;
+  const batchSize = options.batchSize ?? DEFAULT_EMBED_BATCH_SIZE;
+  const concurrency = options.concurrency ?? DEFAULT_EMBED_CONCURRENCY;
+  assertPositiveInteger(batchSize, "batchSize");
+  assertPositiveInteger(concurrency, "concurrency");
+  if (input.length === 0) {
+    return { model, embeddings: [], batchCount: 0 };
+  }
+  const batches = [];
+  for (let start = 0; start < input.length; start += batchSize) {
+    batches.push(input.slice(start, start + batchSize));
+  }
+  const embeddings = new Array(input.length);
+  const controller = new AbortController();
+  const propagateExternalAbort = () => {
+    controller.abort(options.signal?.reason);
+  };
+  if (options.signal) {
+    if (options.signal.aborted) {
+      propagateExternalAbort();
+    } else {
+      options.signal.addEventListener("abort", propagateExternalAbort, { once: true });
+    }
+  }
+  let nextBatch = 0;
+  let completedBatches = 0;
+  let failure;
+  const worker = async () => {
+    for (; ; ) {
+      if (controller.signal.aborted) {
+        throw failure?.error ?? new OllamaAbortError("Embed batch aborted");
+      }
+      const batchIndex = nextBatch;
+      nextBatch++;
+      if (batchIndex >= batches.length) return;
+      const batch = batches[batchIndex];
+      if (!batch) return;
+      try {
+        const request = {
+          model,
+          input: batch,
+          ...options.truncate !== void 0 ? { truncate: options.truncate } : {},
+          ...options.dimensions !== void 0 ? { dimensions: options.dimensions } : {},
+          ...options.keep_alive !== void 0 ? { keep_alive: options.keep_alive } : {},
+          ...options.options !== void 0 ? { options: options.options } : {},
+          ...options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {},
+          signal: controller.signal
+        };
+        const response = await client.embed(request);
+        if (response.embeddings.length !== batch.length) {
+          throw new OllamaClientError(
+            `embedBatch: server returned ${response.embeddings.length} embeddings for a batch of ${batch.length} inputs (batch ${batchIndex}).`,
+            { code: "invalid_response" }
+          );
+        }
+        const offset = batchIndex * batchSize;
+        for (let j = 0; j < batch.length; j++) {
+          embeddings[offset + j] = response.embeddings[j];
+        }
+        completedBatches++;
+        options.onBatchComplete?.(completedBatches, batches.length);
+      } catch (error) {
+        if (!failure) {
+          failure = { error };
+          controller.abort(error);
+          throw error;
+        }
+        throw failure.error;
+      }
+    }
+  };
+  try {
+    const workerCount = Math.min(concurrency, batches.length);
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+  } finally {
+    if (options.signal) {
+      options.signal.removeEventListener("abort", propagateExternalAbort);
+    }
+  }
+  for (let i = 0; i < embeddings.length; i++) {
+    if (embeddings[i] === void 0) {
+      throw new OllamaClientError(
+        `embedBatch: internal invariant violated \u2014 no embedding produced for input #${i}.`,
+        { code: "invalid_response" }
+      );
+    }
+  }
+  return {
+    model,
+    embeddings,
+    batchCount: batches.length
+  };
+}
+
 // src/generated/api/operations.ts
 var blobsOp = {
   operationId: "blobs",
@@ -4996,6 +5120,14 @@ var OllamaClient = class {
   contextWarningThreshold;
   /** Configured overflow policy — `'warn'` (default) or `'throw'`. */
   onContextOverflow;
+  /**
+   * Controllers for every in-flight request and active stream managed by this
+   * client — see {@link OllamaClient.destroy} and {@link createRequestScope}.
+   * Entries live for exactly as long as the underlying work does: until the
+   * response settles (requests) or the stream's `finalResult` settles
+   * (streams, via `executeWithFailover`'s `holdUntil` release path).
+   */
+  activeRequests = /* @__PURE__ */ new Set();
   constructor(config = {}) {
     this.cloudApiKey = resolveApiKey(config.apiKey);
     const defaultBaseUrl = resolveBaseUrl(config.baseUrl);
@@ -5160,6 +5292,39 @@ var OllamaClient = class {
     }
     return { ...options, num_ctx: this.defaultContextLength };
   }
+  /**
+   * Creates the per-request abort scope registered with {@link destroy}:
+   * a controller that fires when the caller's `signal` aborts OR when
+   * `destroy()` runs, whichever comes first. `dispose()` removes the
+   * registration when the work it guards settles — for plain requests when
+   * the response settles, for streams when `finalResult` settles (the same
+   * moment `executeWithFailover`'s `holdUntil` releases the endpoint slot),
+   * so a destroy() can tear down a stream mid-consumption but never outlives
+   * one that already finished.
+   */
+  createRequestScope(userSignal) {
+    const controller = new AbortController();
+    const propagateUserAbort = () => {
+      controller.abort(userSignal?.reason);
+    };
+    let detach;
+    if (userSignal) {
+      if (userSignal.aborted) {
+        propagateUserAbort();
+      } else {
+        userSignal.addEventListener("abort", propagateUserAbort, { once: true });
+        detach = () => userSignal.removeEventListener("abort", propagateUserAbort);
+      }
+    }
+    this.activeRequests.add(controller);
+    return {
+      signal: controller.signal,
+      dispose: () => {
+        detach?.();
+        this.activeRequests.delete(controller);
+      }
+    };
+  }
   /**
    * Fail-fast guard for `format` (structured output) requests: throws before any network
    * call if the candidate endpoint is inferred as Ollama Cloud, which does not currently
@@ -5176,7 +5341,8 @@ var OllamaClient = class {
     }
   }
   async executeWithFailover(operation, options) {
-    const timeout = createTimeoutSignal(options?.timeoutMs ?? this.timeoutMs, options?.signal);
+    const scope = this.createRequestScope(options?.signal);
+    const timeout = createTimeoutSignal(options?.timeoutMs ?? this.timeoutMs, scope.signal);
     const requestId = createLogicalRequestId();
     let deferTimeoutCancel = false;
     try {
@@ -5255,6 +5421,7 @@ var OllamaClient = class {
             if (holdPromise) {
               void holdPromise.catch(() => void 0).finally(() => {
                 timeout.cancel();
+                scope.dispose();
                 this.registry.release(endpoint.name);
               });
             } else {
@@ -5265,7 +5432,10 @@ var OllamaClient = class {
         throw lastError ?? new Error("No healthy Ollama endpoints available");
       }
     } finally {
-      if (!deferTimeoutCancel) timeout.cancel();
+      if (!deferTimeoutCancel) {
+        timeout.cancel();
+        scope.dispose();
+      }
     }
   }
   async chat(req) {
@@ -5425,6 +5595,58 @@ var OllamaClient = class {
     const res = await this.embed({ model, input });
     return res.embeddings;
   }
+  /**
+   * Batch-constrained, order-preserving embedding generation for large
+   * corpora — the safe building block for RAG/vector-index ingestion at
+   * scale. Splits `input` into `batchSize` slices and embeds them through
+   * {@link embed} with at most `concurrency` batches in flight (defaults:
+   * 32 × 3), so `Promise.all`-style floods that OOM local daemons and
+   * saturate `OLLAMA_MAX_QUEUE` can't happen by accident. Fail-fast: the
+   * first batch error aborts every sibling in-flight batch and rejects the
+   * whole operation with the original error.
+   *
+   * Before any request is sent, `defaultContextLength` is injected as
+   * `num_ctx` (same as chat/generate) and each input string's token estimate
+   * is checked against the resolved window: Ollama silently truncates
+   * oversized embedding inputs by default, so the client warns (or throws,
+   * under `onContextOverflow: 'throw'`) with the offending indexes — see
+   * `src/embed-batch.ts` for the exact trip point (no margin: an embedding
+   * prompt IS the whole input).
+   *
+   * ```ts
+   * const { embeddings, batchCount } = await client.embedBatch({
+   *   model: 'nomic-embed-text:latest',
+   *   input: corpus,                 // e.g. 50k chunks
+   *   batchSize: 32,                 // inputs per /api/embed request
+   *   concurrency: 3,                // batches in flight
+   *   onBatchComplete: (done, total) => progress.log(`${done}/${total}`),
+   * });
+   * // embeddings[i] always corresponds to corpus[i]
+   * ```
+   */
+  async embedBatch(options) {
+    const resolvedOptions = this.injectDefaultContextLength(options.options);
+    const contextLength = resolvedOptions?.num_ctx;
+    if (contextLength !== void 0) {
+      const oversized = findOversizedEmbedInputs(options.input, contextLength);
+      if (oversized.length > 0) {
+        const message = embedBatchOverflowMessage(
+          oversized,
+          options.input.length,
+          contextLength,
+          options.truncate === false
+        );
+        if (this.onContextOverflow === "throw") {
+          throw new OllamaClientError(message, { code: "context_overflow" });
+        }
+        this.logger.warn(message);
+      }
+    }
+    return batchEmbed(
+      this,
+      resolvedOptions === options.options ? options : { ...options, options: resolvedOptions }
+    );
+  }
   /**
    * @deprecated Ollama's `/api/embeddings` endpoint has been superseded by `/api/embed`
    * (exposed here as {@link OllamaClient.embed}), which additionally supports batch
@@ -5594,10 +5816,12 @@ var OllamaClient = class {
   async executeCloudRequest(operation, options) {
     var _stack = [];
     try {
-      const timeout = createTimeoutSignal(options.timeoutMs ?? this.timeoutMs, options.signal);
+      const scope = this.createRequestScope(options.signal);
+      const timeout = createTimeoutSignal(options.timeoutMs ?? this.timeoutMs, scope.signal);
       const _timeout = __using(_stack, {
         [Symbol.dispose]() {
           timeout.cancel();
+          scope.dispose();
         }
       });
       const requestId = createLogicalRequestId();
@@ -5658,6 +5882,34 @@ var OllamaClient = class {
   endpointStatus() {
     return this.registry.status();
   }
+  /**
+   * Immediately aborts every in-flight request and active stream managed by
+   * this client — the clean teardown path for short-lived processes, CLI
+   * runners, and `node:worker_threads` tasks where dangling fetch bodies,
+   * unconsumed stream readers, or queued capacity waiters would otherwise
+   * keep the event loop (and thus the thread/process) alive.
+   *
+   * Every aborted operation rejects with an {@link OllamaAbortError}
+   * (`code: 'aborted'`) carrying `reason` as its message — including requests
+   * still queued behind `maxConcurrentPerEndpoint`, not just dispatched ones.
+   * Streams reject their `finalResult` and release their endpoint slots.
+   *
+   * Idempotent: calling it again (or on a client with nothing in flight)
+   * is a no-op that returns `0`. The client remains usable afterward —
+   * `destroy()` is a drain, not a permanent disable; callers that want a
+   * permanently-dead client should discard the instance.
+   *
+   * @returns the number of in-flight operations that were aborted.
+   */
+  destroy(reason = "Ollama client destroyed") {
+    const controllers = [...this.activeRequests];
+    const cause = new OllamaAbortError(reason);
+    for (const controller of controllers) {
+      controller.abort(cause);
+    }
+    this.activeRequests.clear();
+    return controllers.length;
+  }
   // --- Compatibility Adapters ---
   get openai() {
     const ep = this.registry.candidates()[0];
@@ -6795,6 +7047,6 @@ function estimateSystemOneRequestBytes(request) {
   return new TextEncoder().encode(JSON.stringify(request)).byteLength;
 }
 
-export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, Agent, AnthropicCompatClient, AnthropicMessagesStream, ConversationSession, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, EndpointRegistry, GEN_AI_SYSTEM_OLLAMA, HttpClient, IMAGE_TOKEN_ESTIMATE, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, McpBridge, ModelsClient, NANOS_PER_MS, NANOS_PER_SECOND, NOOP_LOGGER, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaAbortError, OllamaAgentMaxIterationsError, OllamaAgentMaxToolCallsError, OllamaAuthError, OllamaBadGatewayError, OllamaClient, OllamaClientError, OllamaGenericClientError, OllamaIncompatibleModelError, OllamaMcpError, OllamaModelRoutingError, OllamaNetworkError, OllamaNotFoundError, OllamaOverloadedError, OllamaQuotaExceededError, OllamaRateLimitError, OllamaRequestTooLargeError, OllamaRequestValidationError, OllamaResponseValidationError, OllamaServerError, OllamaServerVersionUnknownError, OllamaSkillInvalidError, OllamaSkillNotFoundError, OllamaStream, OllamaStreamError, OllamaTimeoutError, OllamaToolTimeoutError, OllamaToolValidationError, OllamaUnsupportedCapabilityError, OpenAIChatCompletionStream, OpenAICompatClient, OpenAICompletionStream, OpenAIResponsesStream, OpenAIResponsesStreamError, QuotaManager, RETRYABLE_STATUS_CODES, ResponsesModule, ToolCallAccumulator, ToolRegistry, addSpanEvent, applySkill, calculateBackoff, checkChatContext, checkEndpointHealth, checkGenerateContext, composeMiddleware, contextWarningMessage, createConsoleLogger, createDecision, createOllamaCloudFreeTierQuota, createTimeoutSignal, defineTool, detectModelCapabilities, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateSystemOneRequestBytes, estimateTokens, extractUsage, fetchWithBackoff, imageStringNeedsResolution, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mapError, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseFrontmatter, parseNdjsonStream, parseSseStream, parseStructuredOutput, registerMcpTools, resolveCredentialEndpoints, resolveImageInput, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };
+export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, Agent, AnthropicCompatClient, AnthropicMessagesStream, ConversationSession, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_EMBED_BATCH_SIZE, DEFAULT_EMBED_CONCURRENCY, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, EndpointRegistry, GEN_AI_SYSTEM_OLLAMA, HttpClient, IMAGE_TOKEN_ESTIMATE, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, McpBridge, ModelsClient, NANOS_PER_MS, NANOS_PER_SECOND, NOOP_LOGGER, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaAbortError, OllamaAgentMaxIterationsError, OllamaAgentMaxToolCallsError, OllamaAuthError, OllamaBadGatewayError, OllamaClient, OllamaClientError, OllamaGenericClientError, OllamaIncompatibleModelError, OllamaMcpError, OllamaModelRoutingError, OllamaNetworkError, OllamaNotFoundError, OllamaOverloadedError, OllamaQuotaExceededError, OllamaRateLimitError, OllamaRequestTooLargeError, OllamaRequestValidationError, OllamaResponseValidationError, OllamaServerError, OllamaServerVersionUnknownError, OllamaSkillInvalidError, OllamaSkillNotFoundError, OllamaStream, OllamaStreamError, OllamaTimeoutError, OllamaToolTimeoutError, OllamaToolValidationError, OllamaUnsupportedCapabilityError, OpenAIChatCompletionStream, OpenAICompatClient, OpenAICompletionStream, OpenAIResponsesStream, OpenAIResponsesStreamError, QuotaManager, RETRYABLE_STATUS_CODES, ResponsesModule, ToolCallAccumulator, ToolRegistry, addSpanEvent, applySkill, batchEmbed, calculateBackoff, checkChatContext, checkEndpointHealth, checkGenerateContext, composeMiddleware, contextWarningMessage, createConsoleLogger, createDecision, createOllamaCloudFreeTierQuota, createTimeoutSignal, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateSystemOneRequestBytes, estimateTokens, extractUsage, fetchWithBackoff, findOversizedEmbedInputs, imageStringNeedsResolution, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mapError, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseFrontmatter, parseNdjsonStream, parseSseStream, parseStructuredOutput, registerMcpTools, resolveCredentialEndpoints, resolveImageInput, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map