@nemesis-oss/ollama-sdk 1.13.0 → 1.15.0

package/dist/index.d.cts

@@ -1,12 +1,12 @@
-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-B57ZZfp3.cjs';
-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-B57ZZfp3.cjs';
-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-DmI1cOEq.cjs';
-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-DmI1cOEq.cjs';
+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-.cjs';
+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-.cjs';
+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-C4RRHqOs.cjs';
+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-C4RRHqOs.cjs';
 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-CYy_ECam.cjs';
-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-CYy_ECam.cjs';
-import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-DhvoUrWa.cjs';
-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-DhvoUrWa.cjs';
+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-UeaVjLeP.cjs';
+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-UeaVjLeP.cjs';
+import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-DFkmtUOP.cjs';
+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-DFkmtUOP.cjs';
 import { M as McpClientLike, a as McpToolDescriptor, b as McpTask, c as McpCallToolResult } from './types-CI-gM2u5.cjs';
 export { d as McpContentBlock, e as McpCreateTaskResult, f as McpElicitationFormRequest, g as McpElicitationHandlers, h as McpElicitationRequest, i as McpElicitationResult, j as McpElicitationUrlRequest, k as McpIcon, l as McpInputRequiredResult, m as McpListToolsParams, n as McpListToolsResult, o as McpRequestOptions, p as McpServerCapabilities, q as McpTaskMethod, r as McpTaskRequest, s as McpTaskStatus, t as McpToolAnnotations, u as McpToolCallResult, v as McpToolExecution } from './types-CI-gM2u5.cjs';
 import * as Otel from '@opentelemetry/api';
@@ -844,6 +844,18 @@ interface BlobUploadResult {
  * `withRetry` still applies), so a multi-endpoint setup never silently lists/mutates the
  * wrong server just because the intended one had a transient failure. See ADR 0008.
  */
+/** Options for {@link ModelsClient.createModelFromGguf}: every `/api/create` field except identity/source ones, plus the draft-shard path convenience. */
+interface CreateModelFromGgufOptions extends Omit<CreateRequestOptions, 'model' | 'files' | 'from' | 'stream'> {
+    /**
+     * Local path(s) to the draft-model GGUF shard(s) for speculative decoding —
+     * each is uploaded as a blob and assembled into `draft_files` under its
+     * basename, the same protocol as the primary shards. Composes with an
+     * explicit `draft_files` digest map (path uploads win on basename
+     * collision). Pair with `parameters.draft_num_predict` and, optionally,
+     * `draft_quantize` to compress the draft weights during ingestion.
+     */
+    readonly draftGguf?: string | readonly string[] | undefined;
+}
 declare class ModelsClient {
     private readonly runner;
     constructor(runner: RequestRunner);
@@ -1003,14 +1015,31 @@ declare class ModelsClient {
      * await client.models.createModelFromGguf('my-model', '/path/to/model.gguf', {
      *   template: '{{ .Prompt }}',
      * });
+     *
+     * // Speculative decoding: primary + draft shards + tuning:
+     * await client.models.createModelFromGguf('my-model', '/path/to/model.gguf', {
+     *   draftGguf: '/path/to/draft.gguf',
+     *   draftQuantize: 'q8_0',
+     *   parameters: { draft_num_predict: 8 },
+     * });
      * ```
      *
+     * Speculative-decoding models assemble the same way: pass the draft
+     * network's GGUF(s) as `draftGguf` (uploaded into `draft_files`), optionally
+     * set `draft_quantize` to compress the draft weights independently of the
+     * primary model, and set `parameters.draft_num_predict` to tune how many
+     * tokens the draft network predicts per step (Ollama defaults separate
+     * draft models to 4; `0` disables drafting; models with embedded MTP
+     * tensors require setting it explicitly).
+     *
      * @param model Name for the new model (e.g. `'my-model:latest'`).
      * @param gguf Path(s) to GGUF file(s) on the local filesystem.
      * @param opts Everything else `/api/create` accepts (`template`, `system`,
-     *   `parameters`, `license`, `quantize`, …) except `files` and `from`.
+     *   `parameters`, `license`, `quantize`, `draftGguf`, …) except `files`,
+     *   `draft_files` (use `draftGguf` for path-based drafts; an explicit digest
+     *   map is still accepted and merged), `from`, and `stream`.
      */
-    createModelFromGguf(model: string, gguf: string | readonly string[], opts?: Omit<CreateRequestOptions, 'model' | 'files' | 'from' | 'stream'>): Promise<ProgressResponse>;
+    createModelFromGguf(model: string, gguf: string | readonly string[], opts?: CreateModelFromGgufOptions): Promise<ProgressResponse>;
 }
 
 /**
@@ -3414,6 +3443,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).
@@ -3688,4 +3862,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, 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 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, parseNdjsonStream, parseStructuredOutput, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, sanitizeHistoryForNextTurn, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-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-B57ZZfp3.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-B57ZZfp3.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-CIQYCRL3.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-CIQYCRL3.js';
+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 { 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-B9AFyzXI.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-B9AFyzXI.js';
-import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-6UOPEknN.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-6UOPEknN.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-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 { 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';
 export { d as McpContentBlock, e as McpCreateTaskResult, f as McpElicitationFormRequest, g as McpElicitationHandlers, h as McpElicitationRequest, i as McpElicitationResult, j as McpElicitationUrlRequest, k as McpIcon, l as McpInputRequiredResult, m as McpListToolsParams, n as McpListToolsResult, o as McpRequestOptions, p as McpServerCapabilities, q as McpTaskMethod, r as McpTaskRequest, s as McpTaskStatus, t as McpToolAnnotations, u as McpToolCallResult, v as McpToolExecution } from './types-CI-gM2u5.js';
 import * as Otel from '@opentelemetry/api';
@@ -844,6 +844,18 @@ interface BlobUploadResult {
  * `withRetry` still applies), so a multi-endpoint setup never silently lists/mutates the
  * wrong server just because the intended one had a transient failure. See ADR 0008.
  */
+/** Options for {@link ModelsClient.createModelFromGguf}: every `/api/create` field except identity/source ones, plus the draft-shard path convenience. */
+interface CreateModelFromGgufOptions extends Omit<CreateRequestOptions, 'model' | 'files' | 'from' | 'stream'> {
+    /**
+     * Local path(s) to the draft-model GGUF shard(s) for speculative decoding —
+     * each is uploaded as a blob and assembled into `draft_files` under its
+     * basename, the same protocol as the primary shards. Composes with an
+     * explicit `draft_files` digest map (path uploads win on basename
+     * collision). Pair with `parameters.draft_num_predict` and, optionally,
+     * `draft_quantize` to compress the draft weights during ingestion.
+     */
+    readonly draftGguf?: string | readonly string[] | undefined;
+}
 declare class ModelsClient {
     private readonly runner;
     constructor(runner: RequestRunner);
@@ -1003,14 +1015,31 @@ declare class ModelsClient {
      * await client.models.createModelFromGguf('my-model', '/path/to/model.gguf', {
      *   template: '{{ .Prompt }}',
      * });
+     *
+     * // Speculative decoding: primary + draft shards + tuning:
+     * await client.models.createModelFromGguf('my-model', '/path/to/model.gguf', {
+     *   draftGguf: '/path/to/draft.gguf',
+     *   draftQuantize: 'q8_0',
+     *   parameters: { draft_num_predict: 8 },
+     * });
      * ```
      *
+     * Speculative-decoding models assemble the same way: pass the draft
+     * network's GGUF(s) as `draftGguf` (uploaded into `draft_files`), optionally
+     * set `draft_quantize` to compress the draft weights independently of the
+     * primary model, and set `parameters.draft_num_predict` to tune how many
+     * tokens the draft network predicts per step (Ollama defaults separate
+     * draft models to 4; `0` disables drafting; models with embedded MTP
+     * tensors require setting it explicitly).
+     *
      * @param model Name for the new model (e.g. `'my-model:latest'`).
      * @param gguf Path(s) to GGUF file(s) on the local filesystem.
      * @param opts Everything else `/api/create` accepts (`template`, `system`,
-     *   `parameters`, `license`, `quantize`, …) except `files` and `from`.
+     *   `parameters`, `license`, `quantize`, `draftGguf`, …) except `files`,
+     *   `draft_files` (use `draftGguf` for path-based drafts; an explicit digest
+     *   map is still accepted and merged), `from`, and `stream`.
      */
-    createModelFromGguf(model: string, gguf: string | readonly string[], opts?: Omit<CreateRequestOptions, 'model' | 'files' | 'from' | 'stream'>): Promise<ProgressResponse>;
+    createModelFromGguf(model: string, gguf: string | readonly string[], opts?: CreateModelFromGgufOptions): Promise<ProgressResponse>;
 }
 
 /**
@@ -3414,6 +3443,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).
@@ -3688,4 +3862,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, 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 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, parseNdjsonStream, parseStructuredOutput, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, sanitizeHistoryForNextTurn, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };