@nemesis-oss/ollama-sdk 1.14.0 → 1.16.0

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { T as ThinkingMetadata, M as ModelResponse, R as RequestCancellationOptions, S as ShowRequestOptions, a as ShowResponse, P as PullRequestOptions, b as ProgressResponse, c as PushRequestOptions, C as CreateRequestOptions, D as DeleteRequestOptions, d as StatusResponse, e as CopyRequestOptions, f as PsResponse, V as VersionResponse, g as ToolParameters, h as ThinkValue, i as ToolCall, j as ChatRequestOptions, k as ModelOptions, l as ToolDefinition, F as FormatOption, m as ChatResponse, n as Message, G as GenerateRequestOptions, o as GenerateResponse, E as EmbedRequestOptions, p as EmbedResponse, q as EmbeddingsRequestOptions, r as EmbeddingsResponse, W as WebSearchRequestOptions, s as WebSearchResponse, t as WebFetchRequestOptions, u as WebFetchResponse, U as UsageRequestOptions, B as BalanceRequestOptions, v as PingResult, w as VisionInput } from './types-DbPnfVh-.js';
 export { L as ListResponse, x as Logprob, y as LogprobToken, z as ModelDetails, A as Role, H as ToolCallFunction, I as ToolFunctionDefinition, J as ToolProperty, K as UsageRange, N as UsageScope, O as WebSearchResult, Q as imageStringNeedsResolution, X as resolveImageInput } from './types-DbPnfVh-.js';
-import { H as HttpClient, F as FetchLike, M as Middleware, L as Logger, R as RequestLifecycleHook, c as OllamaStreamEvent, A as AbortableAsyncIterable, d as OllamaStreamEventType, P as ProgressStreamResult, B as BinaryBody, O as OllamaRuntime, C as ChatStreamResult, G as GenerateStreamResult, e as RawUsageSource, T as TokenUsage } from './runtime-BIjr5ME4.js';
-export { D as DoneEvent, E as ErrorEvent, f as HttpBody, g as HttpClientOptions, h as HttpRequestOptions, i as LifecycleErrorEvent, j as LifecycleRetryEvent, k as LifecycleStartEvent, l as LifecycleSuccessEvent, m as LogFn, n as MessageEvent, o as MiddlewareContext, N as NANOS_PER_MS, p as NANOS_PER_SECOND, q as NOOP_LOGGER, r as NextFunction, s as OllamaAbortError, t as OllamaAgentMaxIterationsError, u as OllamaAgentMaxToolCallsError, v as OllamaAgentToolLoopError, w as OllamaAuthError, x as OllamaBadGatewayError, y as OllamaClientError, z as OllamaClientErrorOptions, J as OllamaErrorRequestContext, K as OllamaErrorResponseContext, Q as OllamaGenericClientError, U as OllamaIncompatibleModelError, V as OllamaMcpError, W as OllamaModelRoutingError, X as OllamaNetworkError, Y as OllamaNotFoundError, Z as OllamaOverloadedError, _ as OllamaQuotaExceededError, $ as OllamaRateLimitError, a0 as OllamaRequestTooLargeError, a1 as OllamaRequestValidationError, a2 as OllamaResponseValidationError, a3 as OllamaServerError, a4 as OllamaServerVersionUnknownError, a5 as OllamaSkillInvalidError, a6 as OllamaSkillNotFoundError, a7 as OllamaStreamError, a8 as OllamaTimeoutError, a9 as OllamaToolTimeoutError, aa as OllamaToolValidationError, ab as OllamaUnsupportedCapabilityError, ac as RequestContext, ad as RequestLifecycleEvent, ae as ResponseContext, af as SseEvent, ag as ThinkingEvent, ah as TokenEvent, ai as ToolCallEvent, aj as composeMiddleware, ak as createConsoleLogger, al as extractUsage, am as mapError, an as parseSseStream } from './runtime-BIjr5ME4.js';
+import { H as HttpClient, F as FetchLike, M as Middleware, L as Logger, R as RequestLifecycleHook, c as OllamaStreamEvent, A as AbortableAsyncIterable, d as OllamaStreamEventType, P as ProgressStreamResult, B as BinaryBody, O as OllamaRuntime, C as ChatStreamResult, G as GenerateStreamResult, e as RawUsageSource, T as TokenUsage } from './runtime-CFuv7Ifh.js';
+export { D as DoneEvent, E as ErrorEvent, f as HttpBody, g as HttpClientOptions, h as HttpRequestOptions, i as LifecycleErrorEvent, j as LifecycleRetryEvent, k as LifecycleStartEvent, l as LifecycleSuccessEvent, m as LogFn, n as MessageEvent, o as MiddlewareContext, N as NANOS_PER_MS, p as NANOS_PER_SECOND, q as NETWORK_ERROR_CODES, r as NOOP_LOGGER, s as NextFunction, t as OllamaAbortError, u as OllamaAgentMaxIterationsError, v as OllamaAgentMaxToolCallsError, w as OllamaAgentToolLoopError, x as OllamaAuthError, y as OllamaBadGatewayError, z as OllamaClientError, J as OllamaClientErrorOptions, K as OllamaErrorRequestContext, Q as OllamaErrorResponseContext, U as OllamaGenericClientError, V as OllamaIncompatibleModelError, W as OllamaMcpError, X as OllamaModelRoutingError, Y as OllamaNetworkError, Z as OllamaNotFoundError, _ as OllamaOverloadedError, $ as OllamaQuotaExceededError, a0 as OllamaRateLimitError, a1 as OllamaRequestTooLargeError, a2 as OllamaRequestValidationError, a3 as OllamaResponseValidationError, a4 as OllamaServerError, a5 as OllamaServerVersionUnknownError, a6 as OllamaSkillInvalidError, a7 as OllamaSkillNotFoundError, a8 as OllamaStreamError, a9 as OllamaTimeoutError, aa as OllamaToolTimeoutError, ab as OllamaToolValidationError, ac as OllamaUnsupportedCapabilityError, ad as RequestContext, ae as RequestLifecycleEvent, af as ResponseContext, ag as SseEvent, ah as ThinkingEvent, ai as TokenEvent, aj as ToolCallEvent, ak as composeMiddleware, al as createConsoleLogger, am as extractUsage, an as isNetworkLevelError, ao as mapError, ap as parseSseStream } from './runtime-CFuv7Ifh.js';
 import { z } from 'zod';
-import { R as RequestRunner, S as SystemOneChoiceAnswer, o as SystemOneNoulAnswer, p as SystemOneScoreAnswer, q as SystemOneChoiceQuestion, r as SystemOneNoulQuestion, s as SystemOneScoreQuestion, t as SystemOneRequest$1, u as SystemOneResponse$1, v as SystemOneContent, N as NativeApi, w as OpenAICompatClient, x as AnthropicCompatClient } from './anthropic-DrDUfbfQ.js';
-export { y as AnthropicCacheControl, z as AnthropicContentBlock, B as AnthropicImageContentBlock, C as AnthropicMessage, n as AnthropicMessageStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, D as AnthropicMessagesStream, E as AnthropicMetadata, F as AnthropicOutputConfig, G as AnthropicRedactedThinkingContentBlock, H as AnthropicSystem, I as AnthropicSystemTextBlock, J as AnthropicTextContentBlock, K as AnthropicThinkingConfig, L as AnthropicThinkingContentBlock, M as AnthropicTool, P as AnthropicToolChoice, Q as AnthropicToolResultContentBlock, T as AnthropicToolUseContentBlock, U as AnthropicUnknownStreamEvent, V as OllamaAnthropicContentBlock, W as OllamaAnthropicMessage, X as OllamaAnthropicMessagesRequest, Y as OllamaAnthropicSystem, Z as OllamaAnthropicSystemTextBlock, _ as OllamaAnthropicTextContentBlock, $ as OllamaAnthropicThinkingConfig, a0 as OllamaAnthropicTool, a1 as OllamaAnthropicToolResultContentBlock, a2 as OllamaOpenAIChatCompletionRequest, a3 as OllamaOpenAIChatContentPart, a4 as OllamaOpenAIChatMessage, a5 as OllamaOpenAICompletionRequest, a6 as OllamaOpenAIEmbeddingRequest, a7 as OllamaOpenAIImageDataUrl, a8 as OllamaOpenAIReasoningEffort, a9 as OllamaOpenAIResponsesRequest, aa as OpenAIChatCompletionChoice, b as OpenAIChatCompletionChunk, ab as OpenAIChatCompletionChunkChoice, ac as OpenAIChatCompletionDelta, O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, ad as OpenAIChatCompletionStream, ae as OpenAICompletionChoice, e as OpenAICompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, af as OpenAICompletionStream, ag as OpenAIContentPart, ah as OpenAIEmbeddingInput, ai as OpenAIEmbeddingItem, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, aj as OpenAIFunctionDefinition, ak as OpenAIImageUrlContentPart, h as OpenAIListModelsResponse, al as OpenAIMessage, i as OpenAIModelItem, am as OpenAIReasoningEffort, an as OpenAIResponseFormat, ao as OpenAIResponsesCompletedEvent, ap as OpenAIResponsesContentPartAddedEvent, aq as OpenAIResponsesContentPartDoneEvent, ar as OpenAIResponsesCreatedEvent, as as OpenAIResponsesError, at as OpenAIResponsesEventBase, au as OpenAIResponsesFailedEvent, av as OpenAIResponsesFunctionCallArgumentsDeltaEvent, aw as OpenAIResponsesFunctionCallArgumentsDoneEvent, ax as OpenAIResponsesInProgressEvent, ay as OpenAIResponsesIncompleteDetails, az as OpenAIResponsesIncompleteEvent, aA as OpenAIResponsesOutputContent, aB as OpenAIResponsesOutputFunctionCall, aC as OpenAIResponsesOutputItem, aD as OpenAIResponsesOutputItemAddedEvent, aE as OpenAIResponsesOutputItemDoneEvent, aF as OpenAIResponsesOutputMessage, aG as OpenAIResponsesOutputReasoning, aH as OpenAIResponsesOutputRefusal, aI as OpenAIResponsesOutputTextContent, aJ as OpenAIResponsesOutputTextDeltaEvent, aK as OpenAIResponsesOutputTextDoneEvent, aL as OpenAIResponsesQueuedEvent, aM as OpenAIResponsesReasoningSummaryPartAddedEvent, aN as OpenAIResponsesReasoningSummaryPartDoneEvent, aO as OpenAIResponsesReasoningSummaryTextDeltaEvent, aP as OpenAIResponsesReasoningSummaryTextDoneEvent, aQ as OpenAIResponsesReasoningTextDeltaEvent, aR as OpenAIResponsesReasoningTextDoneEvent, aS as OpenAIResponsesRefusalDeltaEvent, aT as OpenAIResponsesRefusalDoneEvent, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, aU as OpenAIResponsesStatus, aV as OpenAIResponsesStream, aW as OpenAIResponsesStreamError, l as OpenAIResponsesStreamEvent, aX as OpenAIResponsesUsage, aY as OpenAIStreamOptions, aZ as OpenAITextContentPart, a_ as OpenAITool, a$ as OpenAIToolCall, b0 as OpenAIToolCallDelta, b1 as OpenAIUsage, b2 as SystemOneConfidence, b3 as SystemOneProbabilities } from './anthropic-DrDUfbfQ.js';
+import { R as RequestRunner, S as SystemOneChoiceAnswer, o as SystemOneNoulAnswer, p as SystemOneScoreAnswer, q as SystemOneChoiceQuestion, r as SystemOneNoulQuestion, s as SystemOneScoreQuestion, t as SystemOneRequest$1, u as SystemOneResponse$1, v as SystemOneContent, N as NativeApi, w as OpenAICompatClient, x as AnthropicCompatClient } from './anthropic-CTv2acbj.js';
+export { y as AnthropicCacheControl, z as AnthropicContentBlock, B as AnthropicImageContentBlock, C as AnthropicMessage, n as AnthropicMessageStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, D as AnthropicMessagesStream, E as AnthropicMetadata, F as AnthropicOutputConfig, G as AnthropicRedactedThinkingContentBlock, H as AnthropicSystem, I as AnthropicSystemTextBlock, J as AnthropicTextContentBlock, K as AnthropicThinkingConfig, L as AnthropicThinkingContentBlock, M as AnthropicTool, P as AnthropicToolChoice, Q as AnthropicToolResultContentBlock, T as AnthropicToolUseContentBlock, U as AnthropicUnknownStreamEvent, V as OllamaAnthropicContentBlock, W as OllamaAnthropicMessage, X as OllamaAnthropicMessagesRequest, Y as OllamaAnthropicSystem, Z as OllamaAnthropicSystemTextBlock, _ as OllamaAnthropicTextContentBlock, $ as OllamaAnthropicThinkingConfig, a0 as OllamaAnthropicTool, a1 as OllamaAnthropicToolResultContentBlock, a2 as OllamaOpenAIChatCompletionRequest, a3 as OllamaOpenAIChatContentPart, a4 as OllamaOpenAIChatMessage, a5 as OllamaOpenAICompletionRequest, a6 as OllamaOpenAIEmbeddingRequest, a7 as OllamaOpenAIImageDataUrl, a8 as OllamaOpenAIReasoningEffort, a9 as OllamaOpenAIResponsesRequest, aa as OpenAIChatCompletionChoice, b as OpenAIChatCompletionChunk, ab as OpenAIChatCompletionChunkChoice, ac as OpenAIChatCompletionDelta, O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, ad as OpenAIChatCompletionStream, ae as OpenAICompletionChoice, e as OpenAICompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, af as OpenAICompletionStream, ag as OpenAIContentPart, ah as OpenAIEmbeddingInput, ai as OpenAIEmbeddingItem, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, aj as OpenAIFunctionDefinition, ak as OpenAIImageUrlContentPart, h as OpenAIListModelsResponse, al as OpenAIMessage, i as OpenAIModelItem, am as OpenAIReasoningEffort, an as OpenAIResponseFormat, ao as OpenAIResponsesCompletedEvent, ap as OpenAIResponsesContentPartAddedEvent, aq as OpenAIResponsesContentPartDoneEvent, ar as OpenAIResponsesCreatedEvent, as as OpenAIResponsesError, at as OpenAIResponsesEventBase, au as OpenAIResponsesFailedEvent, av as OpenAIResponsesFunctionCallArgumentsDeltaEvent, aw as OpenAIResponsesFunctionCallArgumentsDoneEvent, ax as OpenAIResponsesInProgressEvent, ay as OpenAIResponsesIncompleteDetails, az as OpenAIResponsesIncompleteEvent, aA as OpenAIResponsesOutputContent, aB as OpenAIResponsesOutputFunctionCall, aC as OpenAIResponsesOutputItem, aD as OpenAIResponsesOutputItemAddedEvent, aE as OpenAIResponsesOutputItemDoneEvent, aF as OpenAIResponsesOutputMessage, aG as OpenAIResponsesOutputReasoning, aH as OpenAIResponsesOutputRefusal, aI as OpenAIResponsesOutputTextContent, aJ as OpenAIResponsesOutputTextDeltaEvent, aK as OpenAIResponsesOutputTextDoneEvent, aL as OpenAIResponsesQueuedEvent, aM as OpenAIResponsesReasoningSummaryPartAddedEvent, aN as OpenAIResponsesReasoningSummaryPartDoneEvent, aO as OpenAIResponsesReasoningSummaryTextDeltaEvent, aP as OpenAIResponsesReasoningSummaryTextDoneEvent, aQ as OpenAIResponsesReasoningTextDeltaEvent, aR as OpenAIResponsesReasoningTextDoneEvent, aS as OpenAIResponsesRefusalDeltaEvent, aT as OpenAIResponsesRefusalDoneEvent, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, aU as OpenAIResponsesStatus, aV as OpenAIResponsesStream, aW as OpenAIResponsesStreamError, l as OpenAIResponsesStreamEvent, aX as OpenAIResponsesUsage, aY as OpenAIStreamOptions, aZ as OpenAITextContentPart, a_ as OpenAITool, a$ as OpenAIToolCall, b0 as OpenAIToolCallDelta, b1 as OpenAIUsage, b2 as SystemOneConfidence, b3 as SystemOneProbabilities } from './anthropic-CTv2acbj.js';
 import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-CeFbHJeO.js';
 export { d as AppliedSkillResult, e as ApplySkillOptions, P as ParsedFrontmatter, S as Skill, f as SkillFrontmatter, g as SkillSummary, h as ToolExecutionContext, i as ToolExecutionFailure, j as ToolExecutionSuccess, k as ToolRegistryOptions, l as applySkill, p as parseFrontmatter } from './compose-CeFbHJeO.js';
 import { M as McpClientLike, a as McpToolDescriptor, b as McpTask, c as McpCallToolResult } from './types-CI-gM2u5.js';
@@ -2780,6 +2780,140 @@ declare function toDataStream<TChunk, TFinal>(stream: OllamaStream<TChunk, TFina
  */
 declare function toResponse<TChunk, TFinal>(stream: OllamaStream<TChunk, TFinal>, init?: ResponseInit): Response;
 
+/**
+ * Zero-copy stream observation — the safe alternative to `ReadableStream.tee()`
+ * for multi-sink consumption (audit logging, token counting, telemetry taps).
+ *
+ * ## The `tee()` hazard this exists for
+ *
+ * Developers streaming to a UI while also feeding a logger (or a token
+ * counter, or an OpenTelemetry exporter) typically reach for:
+ *
+ * ```ts
+ * // VULNERABLE PATTERN — do not do this
+ * const [forUi, forLogger] = response.body.tee();
+ * ```
+ *
+ * WHATWG `tee()` branches share a single upstream pull mechanism: a branch
+ * that reads slower than its sibling forces every intermediate chunk to be
+ * retained in that branch's internal queue until it catches up. If the slow
+ * consumer is a logger waiting on a database write — or never drains at all —
+ * the queue grows without bound, and because both branches apply shared
+ * backpressure, the *fast* consumer is throttled by the slowest one. In a
+ * long-lived streaming server this is a slow, silent heap leak.
+ *
+ * ## What `observeStream` does instead
+ *
+ * A single-pass wrapper: chunks flow from the source through the observer
+ * callbacks to the primary consumer with **no second queue and no forked
+ * stream**. The contract is deliberately one-sided in favor of the primary
+ * consumer:
+ *
+ *   - **Never blocks.** Observer callbacks run on a serialized microtask
+ *     chain, not on the hot path. A slow async observer (a logger waiting on
+ *     I/O) delays only its own tail — the primary consumer keeps receiving
+ *     chunks at source speed.
+ *   - **Never fails.** An observer that throws (sync) or rejects (async) is
+ *     routed to `onListenerError` and otherwise discarded. Observer failures
+ *     can never poison the primary pipeline.
+ *   - **Never leaks via the wrapper.** There is no second branch to
+ *     backpressure. The only retained state is one closure per backlogged
+ *     observer callback; if your observer can stall *forever*, bound it on
+ *     your side (queue, drop policy) — the wrapper will keep enqueueing
+ *     otherwise, exactly like any fire-and-forget log sink.
+ *   - **Ordered.** Observer callbacks run strictly FIFO, one at a time —
+ *     async sinks see chunks in stream order, and `onDone` is enqueued only
+ *     after the last chunk's callback settles. (This is intentionally
+ *     stricter than a naive `void onChunk(chunk)` fire-and-forget, which
+ *     runs concurrent, out-of-order observers and turns a rejected async
+ *     callback into an unhandled rejection.)
+ *
+ * ## Lifecycle
+ *
+ *   - Source completes naturally → `onDone` (enqueued after the last chunk
+ *     callback settles, so a logger has flushed everything it saw).
+ *   - Source throws → `onError(err)` immediately, then the error re-throws to
+ *     the primary consumer (the observer is transparent, not a circuit
+ *     breaker).
+ *   - Primary consumer stops early (`break` / `return` / `throw` inside the
+ *     `for await` loop) → `onAbandon()` immediately. This is distinct from
+ *     completion: the source's iterator-`return()` has already closed the
+ *     underlying transport by the time `onAbandon` fires.
+ *
+ * Works over any `AsyncIterable<T>` — the SDK's `OllamaStream` (streaming
+ * `chat`/`generate`), the raw NDJSON chunk iterables, or your own sources.
+ * Note that `OllamaStream` itself is dual-mode but mode-exclusive (`.on()`
+ * listeners cannot be combined with `for await`); `observeStream` is the
+ * supported way to tap a stream you are already iterating.
+ */
+/**
+ * Lifecycle phase an observer failure came from. `'chunk'` and `'done'`
+ * failures arrive from the serialized callback chain; `'error'` and
+ * `'abandon'` failures come from those terminal hooks themselves.
+ */
+type StreamObserverPhase = 'chunk' | 'done' | 'error' | 'abandoned';
+/** Passive, best-effort observer hooks — see the module docs for semantics. */
+interface StreamObserverCallbacks<T> {
+    /**
+     * Called once per chunk, in stream order, FIFO, never overlapping with a
+     * previous still-running call. May be sync (`void`) or async
+     * (`Promise<void>`); async return values are awaited *on the observer
+     * chain only* — they never delay the primary consumer. Rejections (and
+     * sync throws) route to {@link StreamObserverCallbacks.onListenerError}.
+     */
+    onChunk?: ((chunk: T) => void | Promise<void>) | undefined;
+    /**
+     * Called with the source's error immediately before that error is re-thrown
+     * to the primary consumer. A throwing `onError` hook cannot mask the
+     * original error — it is reported via {@link StreamObserverCallbacks.onListenerError}
+     * and the original error still propagates.
+     */
+    onError?: ((error: unknown) => void) | undefined;
+    /**
+     * Called when the source completes naturally — enqueued after the last
+     * chunk's observer callback settles, so a flushed logger has seen every
+     * chunk before its "done" marker.
+     */
+    onDone?: (() => void | Promise<void>) | undefined;
+    /**
+     * Called when the primary consumer stops early (`break`/`return`/`throw` in
+     * the consuming loop). The source has already been closed via the
+     * iterator-`return()` protocol when this fires. `onDone` does not fire in
+     * this case.
+     */
+    onAbandon?: (() => void) | undefined;
+    /**
+     * The observation failure channel: any observer hook that throws or rejects
+     * is reported here together with the phase it came from, and then
+     * discarded. If this hook itself throws, the failure is swallowed — an
+     * error reporter must never become the next unhandled rejection.
+     */
+    onListenerError?: ((error: unknown, phase: StreamObserverPhase) => void) | undefined;
+}
+/**
+ * Wraps an `AsyncIterable` with passive observer hooks without creating a
+ * secondary buffered stream queue — avoiding the memory retention and shared
+ * backpressure penalties of `ReadableStream.tee()`.
+ *
+ * @example
+ * ```ts
+ * const stream = await client.chat({ model: 'llama4', messages, stream: true });
+ * let tokens = 0;
+ * const observed = observeStream(stream, {
+ *   onChunk: (event) => {
+ *     if (event.type === 'token') tokens += 1;
+ *     auditLog.write(event); // slow async sink — never delays the consumer
+ *   },
+ *   onDone: () => auditLog.flush(),
+ *   onListenerError: (err) => telemetry.count('audit_log_failure', err),
+ * });
+ * for await (const event of observed) {
+ *   ui.render(event); // primary consumer — full speed, full order
+ * }
+ * ```
+ */
+declare function observeStream<T>(source: AsyncIterable<T>, callbacks?: StreamObserverCallbacks<T>): AsyncGenerator<T, void, unknown>;
+
 /**
  * Client-side usage budgeting.
  *
@@ -3443,6 +3577,151 @@ interface FormattedTelemetry {
  */
 declare function formatTelemetry(raw: RawOllamaMetrics): FormattedTelemetry;
 
+/**
+ * Speculative-decoding draft benchmark — measures whether the runtime
+ * `draft_num_predict` option provides a net throughput gain for a specific
+ * prompt (October 13 digest; see ADR 0030).
+ *
+ * Upstream Ollama does not emit a dedicated draft-token acceptance counter —
+ * speculative efficiency is only observable as effective throughput
+ * (`eval_count` / `eval_duration`). And the signal is noisy: rejected draft
+ * predictions *add* compute (high-temperature, creative, non-deterministic
+ * prompts), while accepted drafts dramatically cut `eval_duration` on
+ * predictable workloads (structured code generation, JSON extraction). A
+ * single run therefore proves nothing — this helper implements the
+ * deterministic profiling protocol the upstream observations call for:
+ *
+ *   - **Deterministic sampling** — `temperature: 0` is forced and a fixed
+ *     `seed` (default 42) is stamped on every measured run, so both sides
+ *     generate comparable token streams.
+ *   - **Warm-up discard** — one throwaway `num_predict: 1` generation per
+ *     setting pays the model load (`load_duration`) before any sample is
+ *     taken.
+ *   - **Identical prompt, both sides** — baseline (`draft_num_predict: 0`,
+ *     drafting disabled) vs. speculative (`draft_num_predict: N`), several
+ *     samples each, **median** compared (single samples mislead).
+ *   - Throughput comes from `formatTelemetry` — the official Usage-doc
+ *     tokens/second math, never hand-rolled nanosecond division.
+ *
+ * `effectiveGain` is true when the reported `speedupMultiplier` exceeds
+ * `gainThreshold` (default 1.05 — five percent, past run-to-run noise). A
+ * speedup of about 1.0 usually means the model has **no draft network** (and
+ * no embedded MTP tensors): the server silently ignores the option and both
+ * sides measure the same — see `lab/15-speculative-draft` for a per-setting
+ * table over 0/4/8/16.
+ *
+ * ```ts
+ * import { OllamaClient, compareDraftPerformance } from '@nemesis-oss/ollama-sdk';
+ *
+ * const comparison = await compareDraftPerformance(new OllamaClient(), {
+ *   model: 'llama3.1',
+ *   prompt: 'Extract the sender, subject, and date from this email as JSON: ...',
+ * });
+ * if (comparison.effectiveGain) {
+ *   // drafting pays off for this prompt
+ * }
+ * ```
+ */
+
+/**
+ * Structural dependency of {@link compareDraftPerformance}: anything that can
+ * run a non-streaming `/api/generate` call. `OllamaClient` satisfies it
+ * without being named (same discipline as the model-affinity router's
+ * structural client), so tests and alternative transports can substitute a
+ * minimal object.
+ */
+interface DraftBenchmarkClient {
+    generate(req: GenerateRequestOptions & {
+        stream?: false | undefined;
+    }): Promise<GenerateResponse>;
+}
+/** Options for {@link compareDraftPerformance}. */
+interface CompareDraftPerformanceOptions {
+    /** Model to benchmark — must be a name the target server can load. */
+    readonly model: string;
+    /**
+     * The prompt both sides generate. The comparison is only meaningful with a
+     * fixed prompt: draft acceptance — and thus speedup — is workload-dependent
+     * (structured/predictable prompts gain the most; creative ones can lose).
+     */
+    readonly prompt: string;
+    /**
+     * Draft tokens per step for the speculative side. Default `4` (Ollama's
+     * default for separate draft models). Must be >= 1 — the baseline side
+     * always measures with drafting disabled (`0`).
+     */
+    readonly draftNumPredict?: number | undefined;
+    /**
+     * Measured runs per setting; the median is reported. Default `5`. Single
+     * samples mislead — noisy small-model runs swing tens of percent.
+     */
+    readonly samples?: number | undefined;
+    /** `num_predict` cap per measured run. Default `256`. */
+    readonly numPredict?: number | undefined;
+    /** Fixed sampling seed stamped on every run (with `temperature: 0`). Default `42`. */
+    readonly seed?: number | undefined;
+    /**
+     * Run one throwaway `num_predict: 1` generation per setting before sampling
+     * (pays the model load). Default `true`.
+     */
+    readonly warmup?: boolean | undefined;
+    /**
+     * `speedupMultiplier` above this reports `effectiveGain: true`. Default
+     * `1.05` — five percent, past typical run-to-run noise.
+     */
+    readonly gainThreshold?: number | undefined;
+    /** Abort signal — checked before every run and forwarded to each generate call. */
+    readonly signal?: AbortSignal | undefined;
+}
+/** One side's measurement detail (see {@link DraftPerformanceComparison}). */
+interface DraftRunStats {
+    /** The `draft_num_predict` value this side ran with (`0` = baseline). */
+    readonly draftNumPredict: number;
+    /** Median tokens/second across the valid samples (unrounded). */
+    readonly medianTokensPerSecond: number;
+    /** Every valid sample's tokens/second, in run order. */
+    readonly sampleTokensPerSecond: readonly number[];
+    /** Median generation-phase duration (`eval_duration`) in milliseconds. */
+    readonly medianEvalDurationMs: number;
+}
+/** Result of {@link compareDraftPerformance}. */
+interface DraftPerformanceComparison {
+    /** The model that was benchmarked. */
+    readonly model: string;
+    /** The prompt both sides generated. */
+    readonly prompt: string;
+    /** The speculative side's `draft_num_predict` (the baseline always ran `0`). */
+    readonly draftNumPredict: number;
+    /** Baseline median tokens/second, rounded to 1 decimal. */
+    readonly baselineTokensPerSec: number;
+    /** Speculative median tokens/second, rounded to 1 decimal. */
+    readonly speculativeTokensPerSec: number;
+    /** `speculativeTokensPerSec / baselineTokensPerSec`, rounded to 2 decimals. */
+    readonly speedupMultiplier: number;
+    /** `true` when the reported `speedupMultiplier` exceeds `gainThreshold`. */
+    readonly effectiveGain: boolean;
+    /** The threshold `effectiveGain` was evaluated against. */
+    readonly gainThreshold: number;
+    /** Full baseline detail (samples, medians). */
+    readonly baseline: DraftRunStats;
+    /** Full speculative detail (samples, medians). */
+    readonly speculative: DraftRunStats;
+}
+/**
+ * Measure whether speculative drafting pays off for a specific prompt:
+ * identical prompt, deterministic sampling (`temperature: 0` + fixed `seed`),
+ * warm-up discard, several samples per setting, median baseline
+ * (`draft_num_predict: 0`) vs. median speculative (`draft_num_predict: N`)
+ * compared as `speedupMultiplier`.
+ *
+ * Both sides run through the client's non-streaming `generate` — the raw
+ * counters come back on the response and throughput is derived by
+ * `formatTelemetry`. Non-positive/unusable samples are skipped; if a side
+ * ends up with none, an `OllamaClientError` explains why (wrong model name /
+ * empty generations) rather than reporting a fabricated zero.
+ */
+declare function compareDraftPerformance(client: DraftBenchmarkClient, options: CompareDraftPerformanceOptions): Promise<DraftPerformanceComparison>;
+
 /**
  * Cross-runtime helpers with no Node.js API dependency, so they stay safe to import from
  * the core client bundle (see ADR 0006 — Edge Runtime CI).
@@ -3550,7 +3829,33 @@ interface ContextCheck {
     readonly windowSource: ContextWindowSource;
     /** True when the estimate crossed the warning threshold of the effective window. */
     readonly exceedsThreshold: boolean;
+    /**
+     * Present only when `exceedsThreshold` is `true`: the smallest power-of-two
+     * window with ~30% generation headroom above the estimate (see
+     * {@link recommendContextWindow}). A starting point, not a verdict — check
+     * the model's native ceiling with `client.models.getContextLength()` before
+     * adopting it; a prompt that outgrows the native maximum needs compaction
+     * or history truncation, not a bigger `num_ctx`.
+     */
+    readonly recommendedNumCtx?: number | undefined;
 }
+/**
+ * Smallest power-of-two context window that comfortably fits
+ * `estimatedTokens` — ~30% headroom for the response, floored at 4096 (the
+ * common modern server default when `num_ctx` is unset).
+ *
+ * Uses an exact doubling loop rather than
+ * `Math.pow(2, Math.ceil(Math.log2(x)))`: floating-point `log2` of exact
+ * powers of two can land marginally above the integer (e.g.
+ * `Math.log2(8) > 3` on some platforms), which rounds a perfect fit *up* a
+ * whole power of two. The loop has no such boundary bugs.
+ *
+ * Non-finite / non-positive inputs return the 4096 floor rather than throwing:
+ * callers use this to *suggest* a window after their own estimate already
+ * flagged a problem, so garbage-in should degrade to a conservative
+ * suggestion, not a second error path.
+ */
+declare function recommendContextWindow(estimatedTokens: number): number;
 interface ContextCheckOptions {
     /** Client `defaultContextLength`, applied when the request doesn't set `num_ctx`. */
     readonly defaultContextLength?: number | undefined;
@@ -3717,4 +4022,4 @@ declare class ModelAffinityScheduler {
 /** Convenience factory — `createModelAffinityScheduler(client, opts)` reads better in setups. */
 declare function createModelAffinityScheduler(client: ModelAffinityClient | OllamaClient, options?: ModelAffinitySchedulerOptions): ModelAffinityScheduler;
 
-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, AbortableAsyncIterable, type AffinityRunningModel, Agent, type AgentChatClient, type AgentConfig, type AgentHooks, type AgentResult, type AgentRunInput, type AgentTurn, type AnswerFor, AnthropicCompatClient, AnyTool, type BackoffOptions, BalanceRequestOptions, type BalanceResponse, type BlobUploadResult, ChatRequestOptions, ChatResponse, ChatStreamResult, type ChoiceDecision, type CompactionOptions, type ContextCheck, type ContextCheckOptions, type ContextDiscoveryRequestOptions, type ContextLengthSignals, type ContextLengthSource, type ContextWindowSource, type ConversationSendOptions, ConversationSession, type ConversationSessionOptions, CopyRequestOptions, type CreateModelFromGgufOptions, CreateRequestOptions, type CumulativeCacheStats, 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, type Decision, type DefineToolOptions, DeleteRequestOptions, type DiscoveredContextLength, type EmbedBatchOptions, type EmbedBatchResult, EmbedRequestOptions, EmbedResponse, EmbeddingsRequestOptions, EmbeddingsResponse, type EndpointHealth, type EndpointHealthCheckResult, EndpointRegistry, type EndpointRegistryOptions, FetchLike, type FetchWithBackoffConfig, FormatOption, type FormattedTelemetry, GEN_AI_SYSTEM_OLLAMA, GenerateRequestOptions, GenerateResponse, GenerateStreamResult, type HistorySanitizeOptions, HttpClient, IMAGE_TOKEN_ESTIMATE, type IncludedBalance, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, type KeepAlive, type KnownDoneReason, type LegacyBalanceLimit, type LegacyIncludedBalance, type LoadMcpToolsOptions, Logger, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, MESSAGE_OVERHEAD_TOKENS, McpBridge, type McpBridgeOptions, McpCallToolResult, McpClientLike, McpTask, McpToolDescriptor, Message, Middleware, type ModelAffinityClient, ModelAffinityRouter, type ModelAffinityRoutingOptions, ModelAffinityScheduler, type ModelAffinitySchedulerOptions, type ModelAffinitySnapshot, type ModelAffinityStats, type ModelCapabilities, ModelOptions, ModelResponse, ModelsClient, type NoulDecision, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaClient, type OllamaClientConfig, type OllamaCloudFreeTierQuotaBudgets, type OllamaCredentialConfig, type OllamaEndpoint, OllamaStream, OllamaStreamEvent, OllamaStreamEventType, OpenAICompatClient, type OversizedEmbedInput, type ParallelToolCallBehavior, PingResult, ProgressResponse, ProgressStreamResult, PsResponse, PullRequestOptions, PushRequestOptions, QuotaManager, type QuotaManagerOptions, type QuotaWindowConfig, type QuotaWindowStatus, RETRYABLE_STATUS_CODES, type RankResult, type RawOllamaMetrics, RawUsageSource, RequestCancellationOptions, RequestLifecycleHook, RequestRunner, type ResponsesCreateRequest, type ResponsesCreateResponse, ResponsesModule, type ResponsesReasoningEffort, type ResponsesStreamEvent, type ResponsesToolDefinition, type ResponsesUsage, type RetryConfig, type RuntimeMode, type ScoreDecision, type SessionCompactionOptions, type SessionCompactionResult, type SessionTurn, ShowRequestOptions, ShowResponse, type SpanAttributeValue, type SpanAttributes, StatusResponse, type SupportedSchema, type SystemOneAnswer, type SystemOneAnswers, SystemOneChoiceAnswer, SystemOneChoiceQuestion, SystemOneContent, SystemOneNoulAnswer, SystemOneNoulQuestion, type SystemOneQuestion, type SystemOneQuestions, type SystemOneRequest, type SystemOneResponse, SystemOneScoreAnswer, SystemOneScoreQuestion, type SystemOneUsage, ThinkValue, ThinkingMetadata, type TimeoutSignal, TokenUsage, Tool, ToolCall, ToolCallAccumulator, ToolDefinition, ToolExecutionResult, ToolHandler, ToolParameters, ToolRegistry, type TurnCacheStats, type UsageBucket, type UsageMetrics, UsageRequestOptions, type UsageResponse, VersionResponse, VisionInput, WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME, WebFetchRequestOptions, WebFetchResponse, type WebFetchToolParams, WebSearchRequestOptions, WebSearchResponse, type WebSearchToolParams, type WebToolsClient, type WebToolsOptions, addSpanEvent, batchEmbed, calculateBackoff, canonicalToolCallSignature, checkChatContext, checkEndpointHealth, checkGenerateContext, compactConversationHistory, contextWarningMessage, createDecision, createModelAffinityScheduler, createOllamaCloudFreeTierQuota, createTimeoutSignal, createWebFetchTool, createWebSearchTool, createWebTools, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateMessageTokens, estimateSystemOneRequestBytes, estimateTokens, extractContextLength as extractNativeContextLength, extractParameterNumCtx, fetchWithBackoff, findOversizedEmbedInputs, findRunningModelContextLength, formatTelemetry, formatWebFetchResult, formatWebSearchResult, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isModelResident, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseNdjsonStream, parseStructuredOutput, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, sanitizeHistoryForNextTurn, 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, AbortableAsyncIterable, type AffinityRunningModel, Agent, type AgentChatClient, type AgentConfig, type AgentHooks, type AgentResult, type AgentRunInput, type AgentTurn, type AnswerFor, AnthropicCompatClient, AnyTool, type BackoffOptions, BalanceRequestOptions, type BalanceResponse, type BlobUploadResult, ChatRequestOptions, ChatResponse, ChatStreamResult, type ChoiceDecision, type CompactionOptions, type CompareDraftPerformanceOptions, type ContextCheck, type ContextCheckOptions, type ContextDiscoveryRequestOptions, type ContextLengthSignals, type ContextLengthSource, type ContextWindowSource, type ConversationSendOptions, ConversationSession, type ConversationSessionOptions, CopyRequestOptions, type CreateModelFromGgufOptions, CreateRequestOptions, type CumulativeCacheStats, 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, type Decision, type DefineToolOptions, DeleteRequestOptions, type DiscoveredContextLength, type DraftBenchmarkClient, type DraftPerformanceComparison, type DraftRunStats, type EmbedBatchOptions, type EmbedBatchResult, EmbedRequestOptions, EmbedResponse, EmbeddingsRequestOptions, EmbeddingsResponse, type EndpointHealth, type EndpointHealthCheckResult, EndpointRegistry, type EndpointRegistryOptions, FetchLike, type FetchWithBackoffConfig, FormatOption, type FormattedTelemetry, GEN_AI_SYSTEM_OLLAMA, GenerateRequestOptions, GenerateResponse, GenerateStreamResult, type HistorySanitizeOptions, HttpClient, IMAGE_TOKEN_ESTIMATE, type IncludedBalance, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, type KeepAlive, type KnownDoneReason, type LegacyBalanceLimit, type LegacyIncludedBalance, type LoadMcpToolsOptions, Logger, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, MESSAGE_OVERHEAD_TOKENS, McpBridge, type McpBridgeOptions, McpCallToolResult, McpClientLike, McpTask, McpToolDescriptor, Message, Middleware, type ModelAffinityClient, ModelAffinityRouter, type ModelAffinityRoutingOptions, ModelAffinityScheduler, type ModelAffinitySchedulerOptions, type ModelAffinitySnapshot, type ModelAffinityStats, type ModelCapabilities, ModelOptions, ModelResponse, ModelsClient, type NoulDecision, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaClient, type OllamaClientConfig, type OllamaCloudFreeTierQuotaBudgets, type OllamaCredentialConfig, type OllamaEndpoint, OllamaStream, OllamaStreamEvent, OllamaStreamEventType, OpenAICompatClient, type OversizedEmbedInput, type ParallelToolCallBehavior, PingResult, ProgressResponse, ProgressStreamResult, PsResponse, PullRequestOptions, PushRequestOptions, QuotaManager, type QuotaManagerOptions, type QuotaWindowConfig, type QuotaWindowStatus, RETRYABLE_STATUS_CODES, type RankResult, type RawOllamaMetrics, RawUsageSource, RequestCancellationOptions, RequestLifecycleHook, RequestRunner, type ResponsesCreateRequest, type ResponsesCreateResponse, ResponsesModule, type ResponsesReasoningEffort, type ResponsesStreamEvent, type ResponsesToolDefinition, type ResponsesUsage, type RetryConfig, type RuntimeMode, type ScoreDecision, type SessionCompactionOptions, type SessionCompactionResult, type SessionTurn, ShowRequestOptions, ShowResponse, type SpanAttributeValue, type SpanAttributes, StatusResponse, type StreamObserverCallbacks, type StreamObserverPhase, type SupportedSchema, type SystemOneAnswer, type SystemOneAnswers, SystemOneChoiceAnswer, SystemOneChoiceQuestion, SystemOneContent, SystemOneNoulAnswer, SystemOneNoulQuestion, type SystemOneQuestion, type SystemOneQuestions, type SystemOneRequest, type SystemOneResponse, SystemOneScoreAnswer, SystemOneScoreQuestion, type SystemOneUsage, ThinkValue, ThinkingMetadata, type TimeoutSignal, TokenUsage, Tool, ToolCall, ToolCallAccumulator, ToolDefinition, ToolExecutionResult, ToolHandler, ToolParameters, ToolRegistry, type TurnCacheStats, type UsageBucket, type UsageMetrics, UsageRequestOptions, type UsageResponse, VersionResponse, VisionInput, WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME, WebFetchRequestOptions, WebFetchResponse, type WebFetchToolParams, WebSearchRequestOptions, WebSearchResponse, type WebSearchToolParams, type WebToolsClient, type WebToolsOptions, addSpanEvent, batchEmbed, calculateBackoff, canonicalToolCallSignature, checkChatContext, checkEndpointHealth, checkGenerateContext, compactConversationHistory, compareDraftPerformance, contextWarningMessage, createDecision, createModelAffinityScheduler, createOllamaCloudFreeTierQuota, createTimeoutSignal, createWebFetchTool, createWebSearchTool, createWebTools, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateMessageTokens, estimateSystemOneRequestBytes, estimateTokens, extractContextLength as extractNativeContextLength, extractParameterNumCtx, fetchWithBackoff, findOversizedEmbedInputs, findRunningModelContextLength, formatTelemetry, formatWebFetchResult, formatWebSearchResult, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isModelResident, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, observeStream, parseNdjsonStream, parseStructuredOutput, recommendContextWindow, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, sanitizeHistoryForNextTurn, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };