@nemesis-oss/ollama-sdk 1.14.0 → 1.15.0

package/dist/index.d.cts

@@ -3443,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).
@@ -3717,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, 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 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

@@ -3443,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).
@@ -3717,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, 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 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.js

@@ -7748,6 +7748,111 @@ var Agent = class {
   }
 };
 
+// src/draft-benchmark.ts
+var DEFAULT_DRAFT_TOKENS = 4;
+var DEFAULT_SAMPLES = 5;
+var DEFAULT_NUM_PREDICT = 256;
+var DEFAULT_SEED = 42;
+var DEFAULT_GAIN_THRESHOLD = 1.05;
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 1 ? sorted[mid] ?? 0 : ((sorted[mid - 1] ?? 0) + (sorted[mid] ?? 0)) / 2;
+}
+function roundTo(value, decimals) {
+  const factor = 10 ** decimals;
+  return Math.round(value * factor) / factor;
+}
+function requirePositiveInteger(name, value) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new RangeError(
+      `compareDraftPerformance: ${name} must be an integer >= 1 (got ${value}).`
+    );
+  }
+}
+async function runSide(client, options, draftNumPredict, samples, numPredict, seed) {
+  const samplingOptions = {
+    num_predict: numPredict,
+    temperature: 0,
+    seed,
+    draft_num_predict: draftNumPredict
+  };
+  if (options.warmup ?? true) {
+    await client.generate({
+      model: options.model,
+      prompt: options.prompt,
+      options: { ...samplingOptions, num_predict: 1 },
+      stream: false,
+      signal: options.signal
+    });
+  }
+  const tokensPerSecond = [];
+  const generationMs = [];
+  for (let i = 0; i < samples; i++) {
+    options.signal?.throwIfAborted();
+    const response = await client.generate({
+      model: options.model,
+      prompt: options.prompt,
+      options: samplingOptions,
+      stream: false,
+      signal: options.signal
+    });
+    const telemetry = formatTelemetry(response);
+    if (Number.isFinite(telemetry.tokensPerSecond) && telemetry.tokensPerSecond > 0) {
+      tokensPerSecond.push(telemetry.tokensPerSecond);
+      generationMs.push(telemetry.generationMs);
+    }
+  }
+  if (tokensPerSecond.length === 0) {
+    throw new OllamaClientError(
+      `compareDraftPerformance: every draft_num_predict=${draftNumPredict} sample returned a non-positive tokens/second. The model name is likely wrong, or the server returned empty generations.`,
+      { code: "draft_benchmark_no_valid_samples" }
+    );
+  }
+  return {
+    draftNumPredict,
+    medianTokensPerSecond: median(tokensPerSecond),
+    sampleTokensPerSecond: tokensPerSecond,
+    medianEvalDurationMs: median(generationMs)
+  };
+}
+async function compareDraftPerformance(client, options) {
+  const draftNumPredict = options.draftNumPredict ?? DEFAULT_DRAFT_TOKENS;
+  requirePositiveInteger("draftNumPredict", draftNumPredict);
+  const samples = options.samples ?? DEFAULT_SAMPLES;
+  requirePositiveInteger("samples", samples);
+  const numPredict = options.numPredict ?? DEFAULT_NUM_PREDICT;
+  requirePositiveInteger("numPredict", numPredict);
+  const seed = options.seed ?? DEFAULT_SEED;
+  if (!Number.isInteger(seed)) {
+    throw new RangeError(`compareDraftPerformance: seed must be an integer (got ${seed}).`);
+  }
+  const gainThreshold = options.gainThreshold ?? DEFAULT_GAIN_THRESHOLD;
+  if (!Number.isFinite(gainThreshold) || gainThreshold <= 0) {
+    throw new RangeError(
+      `compareDraftPerformance: gainThreshold must be a positive finite number (got ${gainThreshold}).`
+    );
+  }
+  options.signal?.throwIfAborted();
+  const baseline = await runSide(client, options, 0, samples, numPredict, seed);
+  const speculative = await runSide(client, options, draftNumPredict, samples, numPredict, seed);
+  const baselineTokensPerSec = roundTo(baseline.medianTokensPerSecond, 1);
+  const speculativeTokensPerSec = roundTo(speculative.medianTokensPerSecond, 1);
+  const speedupMultiplier = baselineTokensPerSec > 0 ? roundTo(speculativeTokensPerSec / baselineTokensPerSec, 2) : 0;
+  return {
+    model: options.model,
+    prompt: options.prompt,
+    draftNumPredict,
+    baselineTokensPerSec,
+    speculativeTokensPerSec,
+    speedupMultiplier,
+    effectiveGain: speedupMultiplier > gainThreshold,
+    gainThreshold,
+    baseline,
+    speculative
+  };
+}
+
 // src/affinity.ts
 var DEFAULT_CONCURRENT_MODELS = 1;
 var DEFAULT_PER_MODEL_CONCURRENCY = 1;
@@ -7909,6 +8014,6 @@ function estimateSystemOneRequestBytes(request) {
   return new TextEncoder().encode(JSON.stringify(request)).byteLength;
 }
 
-export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, Agent, AnthropicCompatClient, AnthropicMessagesStream, ConversationSession, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_EMBED_BATCH_SIZE, DEFAULT_EMBED_CONCURRENCY, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, EndpointRegistry, GEN_AI_SYSTEM_OLLAMA, HttpClient, IMAGE_TOKEN_ESTIMATE, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, MESSAGE_OVERHEAD_TOKENS, McpBridge, ModelAffinityRouter, ModelAffinityScheduler, ModelsClient, NANOS_PER_MS, NANOS_PER_SECOND, NOOP_LOGGER, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaAbortError, OllamaAgentMaxIterationsError, OllamaAgentMaxToolCallsError, OllamaAgentToolLoopError, OllamaAuthError, OllamaBadGatewayError, OllamaClient, OllamaClientError, OllamaGenericClientError, OllamaIncompatibleModelError, OllamaMcpError, OllamaModelRoutingError, OllamaNetworkError, OllamaNotFoundError, OllamaOverloadedError, OllamaQuotaExceededError, OllamaRateLimitError, OllamaRequestTooLargeError, OllamaRequestValidationError, OllamaResponseValidationError, OllamaServerError, OllamaServerVersionUnknownError, OllamaSkillInvalidError, OllamaSkillNotFoundError, OllamaStream, OllamaStreamError, OllamaTimeoutError, OllamaToolTimeoutError, OllamaToolValidationError, OllamaUnsupportedCapabilityError, OpenAIChatCompletionStream, OpenAICompatClient, OpenAICompletionStream, OpenAIResponsesStream, OpenAIResponsesStreamError, QuotaManager, RETRYABLE_STATUS_CODES, ResponsesModule, ToolCallAccumulator, ToolRegistry, WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME, addSpanEvent, applySkill, batchEmbed, calculateBackoff, canonicalToolCallSignature, checkChatContext, checkEndpointHealth, checkGenerateContext, compactConversationHistory, composeMiddleware, contextWarningMessage, createConsoleLogger, createDecision, createModelAffinityScheduler, createOllamaCloudFreeTierQuota, createTimeoutSignal, createWebFetchTool, createWebSearchTool, createWebTools, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateMessageTokens, estimateSystemOneRequestBytes, estimateTokens, extractContextLength as extractNativeContextLength, extractParameterNumCtx, extractUsage, fetchWithBackoff, findOversizedEmbedInputs, findRunningModelContextLength, formatTelemetry, formatWebFetchResult, formatWebSearchResult, imageStringNeedsResolution, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isModelResident, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mapError, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseFrontmatter, parseNdjsonStream, parseSseStream, parseStructuredOutput, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, resolveImageInput, 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, Agent, AnthropicCompatClient, AnthropicMessagesStream, ConversationSession, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_EMBED_BATCH_SIZE, DEFAULT_EMBED_CONCURRENCY, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, EndpointRegistry, GEN_AI_SYSTEM_OLLAMA, HttpClient, IMAGE_TOKEN_ESTIMATE, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, MESSAGE_OVERHEAD_TOKENS, McpBridge, ModelAffinityRouter, ModelAffinityScheduler, ModelsClient, NANOS_PER_MS, NANOS_PER_SECOND, NOOP_LOGGER, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaAbortError, OllamaAgentMaxIterationsError, OllamaAgentMaxToolCallsError, OllamaAgentToolLoopError, OllamaAuthError, OllamaBadGatewayError, OllamaClient, OllamaClientError, OllamaGenericClientError, OllamaIncompatibleModelError, OllamaMcpError, OllamaModelRoutingError, OllamaNetworkError, OllamaNotFoundError, OllamaOverloadedError, OllamaQuotaExceededError, OllamaRateLimitError, OllamaRequestTooLargeError, OllamaRequestValidationError, OllamaResponseValidationError, OllamaServerError, OllamaServerVersionUnknownError, OllamaSkillInvalidError, OllamaSkillNotFoundError, OllamaStream, OllamaStreamError, OllamaTimeoutError, OllamaToolTimeoutError, OllamaToolValidationError, OllamaUnsupportedCapabilityError, OpenAIChatCompletionStream, OpenAICompatClient, OpenAICompletionStream, OpenAIResponsesStream, OpenAIResponsesStreamError, QuotaManager, RETRYABLE_STATUS_CODES, ResponsesModule, ToolCallAccumulator, ToolRegistry, WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME, addSpanEvent, applySkill, batchEmbed, calculateBackoff, canonicalToolCallSignature, checkChatContext, checkEndpointHealth, checkGenerateContext, compactConversationHistory, compareDraftPerformance, composeMiddleware, contextWarningMessage, createConsoleLogger, createDecision, createModelAffinityScheduler, createOllamaCloudFreeTierQuota, createTimeoutSignal, createWebFetchTool, createWebSearchTool, createWebTools, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateMessageTokens, estimateSystemOneRequestBytes, estimateTokens, extractContextLength as extractNativeContextLength, extractParameterNumCtx, extractUsage, fetchWithBackoff, findOversizedEmbedInputs, findRunningModelContextLength, formatTelemetry, formatWebFetchResult, formatWebSearchResult, imageStringNeedsResolution, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isModelResident, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mapError, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseFrontmatter, parseNdjsonStream, parseSseStream, parseStructuredOutput, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, resolveImageInput, sanitizeHistoryForNextTurn, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map