llmist 0.3.1 → 0.4.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { ZodType, ZodTypeAny } from 'zod';
 export { z } from 'zod';
-import { A as AgentHooks, L as LLMMessage, P as ParameterFormat, S as StreamEvent, G as GadgetRegistry, o as LLMStreamChunk, B as BaseGadget, p as ParsedGadgetCall, q as GadgetExecutionResult, r as ProviderAdapter, s as ModelDescriptor, t as ModelSpec, u as LLMGenerationOptions, v as LLMStream } from './mock-stream-C2sBQlvc.cjs';
-export { C as AfterGadgetExecutionAction, D as AfterGadgetExecutionControllerContext, F as AfterLLMCallAction, I as AfterLLMCallControllerContext, J as AfterLLMErrorAction, w as AgentBuilder, K as AgentOptions, N as BeforeGadgetExecutionAction, O as BeforeLLMCallAction, Q as ChunkInterceptorContext, R as Controllers, a9 as CostEstimate, ak as DEFAULT_PROMPTS, E as EventHandlers, ar as GadgetClass, T as GadgetExecutionControllerContext, as as GadgetOrClass, U as GadgetParameterInterceptorContext, V as GadgetResultInterceptorContext, H as HistoryMessage, W as Interceptors, X as LLMCallControllerContext, Y as LLMErrorControllerContext, a8 as LLMMessageBuilder, a7 as LLMRole, a6 as LLMist, a5 as LLMistOptions, Z as MessageInterceptorContext, a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, aa as ModelFeatures, ag as ModelIdentifierParser, ab as ModelLimits, ac as ModelPricing, ad as ModelRegistry, _ as ObserveChunkContext, $ as ObserveGadgetCompleteContext, a0 as ObserveGadgetStartContext, a1 as ObserveLLMCallContext, a2 as ObserveLLMCompleteContext, a3 as ObserveLLMErrorContext, a4 as Observers, ah as PromptConfig, ai as PromptContext, aj as PromptTemplate, ae as ProviderIdentifier, an as QuickOptions, aq as StreamParser, at as TextOnlyAction, au as TextOnlyContext, av as TextOnlyCustomHandler, aw as TextOnlyGadgetConfig, ax as TextOnlyHandler, ay as TextOnlyStrategy, af as TokenUsage, x as collectEvents, y as collectText, ao as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, al as resolvePromptTemplate, am as resolveRulesTemplate, z as runWithHandlers, ap as stream } from './mock-stream-C2sBQlvc.cjs';
+import { A as AgentHooks, o as ModelRegistry, L as LLMMessage, P as ParameterFormat, S as StreamEvent, G as GadgetRegistry, p as LLMStreamChunk, B as BaseGadget, q as ParsedGadgetCall, r as GadgetExecutionResult, s as ProviderAdapter, t as ModelDescriptor, u as ModelSpec, v as LLMGenerationOptions, w as LLMStream } from './mock-stream-C0vOqI3L.cjs';
+export { D as AfterGadgetExecutionAction, F as AfterGadgetExecutionControllerContext, I as AfterLLMCallAction, J as AfterLLMCallControllerContext, K as AfterLLMErrorAction, x as AgentBuilder, N as AgentOptions, O as BeforeGadgetExecutionAction, Q as BeforeLLMCallAction, R as ChunkInterceptorContext, T as Controllers, aa as CostEstimate, ak as DEFAULT_PROMPTS, E as EventHandlers, ar as GadgetClass, U as GadgetExecutionControllerContext, as as GadgetOrClass, V as GadgetParameterInterceptorContext, W as GadgetResultInterceptorContext, H as HistoryMessage, X as Interceptors, Y as LLMCallControllerContext, Z as LLMErrorControllerContext, a9 as LLMMessageBuilder, a8 as LLMRole, a7 as LLMist, a6 as LLMistOptions, _ as MessageInterceptorContext, a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, ab as ModelFeatures, ag as ModelIdentifierParser, ac as ModelLimits, ad as ModelPricing, $ as ObserveChunkContext, a0 as ObserveGadgetCompleteContext, a1 as ObserveGadgetStartContext, a2 as ObserveLLMCallContext, a3 as ObserveLLMCompleteContext, a4 as ObserveLLMErrorContext, a5 as Observers, ah as PromptConfig, ai as PromptContext, aj as PromptTemplate, ae as ProviderIdentifier, an as QuickOptions, aq as StreamParser, at as TextOnlyAction, au as TextOnlyContext, av as TextOnlyCustomHandler, aw as TextOnlyGadgetConfig, ax as TextOnlyHandler, ay as TextOnlyStrategy, af as TokenUsage, y as collectEvents, z as collectText, ao as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, al as resolvePromptTemplate, am as resolveRulesTemplate, C as runWithHandlers, ap as stream } from './mock-stream-C0vOqI3L.cjs';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';
@@ -18,6 +18,7 @@ import { ChatCompletionChunk } from 'openai/resources/chat/completions';
  * - **logging(options?)** - Log LLM calls and gadget execution
  * - **timing()** - Measure execution time for operations
  * - **tokenTracking()** - Track cumulative token usage and costs
+ * - **progressTracking(options?)** - Track progress with iterations, tokens, cost, and timing (SHOWCASE)
  * - **errorLogging()** - Log detailed error information
  * - **silent()** - No output (useful for testing)
  * - **monitoring(options?)** - All-in-one preset combining logging, timing, tokens, and errors
@@ -67,6 +68,89 @@ interface LoggingOptions {
     /** Include verbose details like parameters and results */
     verbose?: boolean;
 }
+/**
+ * Progress statistics reported by progressTracking preset.
+ *
+ * Contains cumulative metrics across all LLM calls in the agent session,
+ * useful for building progress UI, cost monitoring, and performance tracking.
+ */
+interface ProgressStats {
+    /** Current iteration number (increments on each LLM call start) */
+    currentIteration: number;
+    /** Total number of completed LLM calls */
+    totalCalls: number;
+    /** Cumulative input tokens across all calls */
+    totalInputTokens: number;
+    /** Cumulative output tokens across all calls */
+    totalOutputTokens: number;
+    /** Total tokens (input + output) */
+    totalTokens: number;
+    /** Cumulative cost in USD (requires modelRegistry) */
+    totalCost: number;
+    /** Elapsed time in seconds since first call */
+    elapsedSeconds: number;
+}
+/**
+ * Options for progressTracking preset.
+ *
+ * Controls how progress data is tracked and reported during agent execution.
+ */
+interface ProgressTrackingOptions {
+    /**
+     * Model registry for cost calculation.
+     *
+     * If provided, enables automatic cost estimation based on token usage
+     * and model pricing data. Without it, totalCost will always be 0.
+     *
+     * @example
+     * ```typescript
+     * import { LLMist, HookPresets } from 'llmist';
+     *
+     * const client = LLMist.create();
+     * const hooks = HookPresets.progressTracking({
+     *   modelRegistry: client.modelRegistry  // Enable cost tracking
+     * });
+     * ```
+     */
+    modelRegistry?: ModelRegistry;
+    /**
+     * Callback invoked after each LLM call completion with cumulative stats.
+     *
+     * Use this to update progress UI, log metrics, or track budgets in real-time.
+     *
+     * @example
+     * ```typescript
+     * HookPresets.progressTracking({
+     *   modelRegistry: client.modelRegistry,
+     *   onProgress: (stats) => {
+     *     console.log(`Iteration #${stats.currentIteration}`);
+     *     console.log(`Cost so far: $${stats.totalCost.toFixed(4)}`);
+     *     console.log(`Elapsed: ${stats.elapsedSeconds}s`);
+     *   }
+     * })
+     * ```
+     */
+    onProgress?: (stats: ProgressStats) => void;
+    /**
+     * Whether to log progress to console after each LLM call.
+     *
+     * When enabled, prints a summary line with tokens, cost, and elapsed time.
+     * Useful for quick debugging without implementing a custom callback.
+     *
+     * Default: false
+     *
+     * @example
+     * ```typescript
+     * // Quick console-based progress tracking
+     * HookPresets.progressTracking({
+     *   modelRegistry: client.modelRegistry,
+     *   logProgress: true  // Log to console
+     * })
+     * // Output: 📊 Progress: Iteration #2 | 1,234 tokens | $0.0056 | 12.3s
+     * ```
+     */
+    logProgress?: boolean;
+}
 /**
  * Common hook presets.
  */
@@ -232,6 +316,129 @@ declare class HookPresets {
      * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetstokentracking | Full documentation}
      */
     static tokenTracking(): AgentHooks;
+    /**
+     * Tracks comprehensive progress metrics including iterations, tokens, cost, and timing.
+     *
+     * **This preset showcases llmist's core capabilities by demonstrating:**
+     * - Observer pattern for non-intrusive monitoring
+     * - Integration with ModelRegistry for cost estimation
+     * - Callback-based architecture for flexible UI updates
+     * - Provider-agnostic token and cost tracking
+     *
+     * Unlike `tokenTracking()` which only logs to console, this preset provides
+     * structured data through callbacks, making it perfect for building custom UIs,
+     * dashboards, or progress indicators (like the llmist CLI).
+     *
+     * **Output (when logProgress: true):**
+     * - Iteration number and call count
+     * - Cumulative token usage (input + output)
+     * - Cumulative cost in USD (requires modelRegistry)
+     * - Elapsed time in seconds
+     *
+     * **Use cases:**
+     * - Building CLI progress indicators with live updates
+     * - Creating web dashboards with real-time metrics
+     * - Budget monitoring and cost alerts
+     * - Performance tracking and optimization
+     * - Custom logging to external systems (Datadog, CloudWatch, etc.)
+     *
+     * **Performance:** Minimal overhead. Uses Date.now() for timing and optional
+     * ModelRegistry.estimateCost() which is O(1) lookup. Callback invocation is
+     * synchronous and fast.
+     *
+     * @param options - Progress tracking options
+     * @param options.modelRegistry - ModelRegistry for cost estimation (optional)
+     * @param options.onProgress - Callback invoked after each LLM call (optional)
+     * @param options.logProgress - Log progress to console (default: false)
+     * @returns Hook configuration with progress tracking observers
+     *
+     * @example
+     * ```typescript
+     * // Basic usage with callback (RECOMMENDED - used by llmist CLI)
+     * import { LLMist, HookPresets } from 'llmist';
+     *
+     * const client = LLMist.create();
+     *
+     * await client.agent()
+     *   .withHooks(HookPresets.progressTracking({
+     *     modelRegistry: client.modelRegistry,
+     *     onProgress: (stats) => {
+     *       // Update your UI with stats
+     *       console.log(`#${stats.currentIteration} | ${stats.totalTokens} tokens | $${stats.totalCost.toFixed(4)}`);
+     *     }
+     *   }))
+     *   .withGadgets(Calculator)
+     *   .ask("Calculate 15 * 23");
+     * // Output: #1 | 245 tokens | $0.0012
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Console logging mode (quick debugging)
+     * await client.agent()
+     *   .withHooks(HookPresets.progressTracking({
+     *     modelRegistry: client.modelRegistry,
+     *     logProgress: true  // Simple console output
+     *   }))
+     *   .ask("Your prompt");
+     * // Output: 📊 Progress: Iteration #1 | 245 tokens | $0.0012 | 1.2s
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Budget monitoring with alerts
+     * const BUDGET_USD = 0.10;
+     *
+     * await client.agent()
+     *   .withHooks(HookPresets.progressTracking({
+     *     modelRegistry: client.modelRegistry,
+     *     onProgress: (stats) => {
+     *       if (stats.totalCost > BUDGET_USD) {
+     *         throw new Error(`Budget exceeded: $${stats.totalCost.toFixed(4)}`);
+     *       }
+     *     }
+     *   }))
+     *   .ask("Long running task...");
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Web dashboard integration
+     * let progressBar: HTMLElement;
+     *
+     * await client.agent()
+     *   .withHooks(HookPresets.progressTracking({
+     *     modelRegistry: client.modelRegistry,
+     *     onProgress: (stats) => {
+     *       // Update web UI in real-time
+     *       progressBar.textContent = `Iteration ${stats.currentIteration}`;
+     *       progressBar.dataset.cost = stats.totalCost.toFixed(4);
+     *       progressBar.dataset.tokens = stats.totalTokens.toString();
+     *     }
+     *   }))
+     *   .ask("Your prompt");
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // External logging (Datadog, CloudWatch, etc.)
+     * await client.agent()
+     *   .withHooks(HookPresets.progressTracking({
+     *     modelRegistry: client.modelRegistry,
+     *     onProgress: async (stats) => {
+     *       await metrics.gauge('llm.iteration', stats.currentIteration);
+     *       await metrics.gauge('llm.cost', stats.totalCost);
+     *       await metrics.gauge('llm.tokens', stats.totalTokens);
+     *     }
+     *   }))
+     *   .ask("Your prompt");
+     * ```
+     *
+     * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsprogresstrackingoptions | Full documentation}
+     * @see {@link ProgressTrackingOptions} for detailed options
+     * @see {@link ProgressStats} for the callback data structure
+     */
+    static progressTracking(options?: ProgressTrackingOptions): AgentHooks;
     /**
      * Logs detailed error information for debugging and troubleshooting.
      *
@@ -1424,4 +1631,4 @@ declare class OpenAIChatProvider extends BaseProviderAdapter {
 }
 declare function createOpenAIProviderFromEnv(): OpenAIChatProvider | null;
 
-export { AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, ConversationManager, type CreateGadgetConfig, Gadget, type GadgetConfig, GadgetExecutionResult, GadgetExecutor, GadgetRegistry, GeminiGenerativeProvider, HookPresets, HumanInputException, type IConversationManager, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, ModelDescriptor, ModelSpec, OpenAIChatProvider, ParsedGadgetCall, ProviderAdapter, StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGeminiProviderFromEnv, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, resolveModel, validateAndApplyDefaults, validateGadgetParams };
+export { AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, ConversationManager, type CreateGadgetConfig, Gadget, type GadgetConfig, GadgetExecutionResult, GadgetExecutor, GadgetRegistry, GeminiGenerativeProvider, HookPresets, HumanInputException, type IConversationManager, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, ModelDescriptor, ModelRegistry, ModelSpec, OpenAIChatProvider, ParsedGadgetCall, ProviderAdapter, StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGeminiProviderFromEnv, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, resolveModel, validateAndApplyDefaults, validateGadgetParams };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ZodType, ZodTypeAny } from 'zod';
 export { z } from 'zod';
-import { A as AgentHooks, L as LLMMessage, P as ParameterFormat, S as StreamEvent, G as GadgetRegistry, o as LLMStreamChunk, B as BaseGadget, p as ParsedGadgetCall, q as GadgetExecutionResult, r as ProviderAdapter, s as ModelDescriptor, t as ModelSpec, u as LLMGenerationOptions, v as LLMStream } from './mock-stream-C2sBQlvc.js';
-export { C as AfterGadgetExecutionAction, D as AfterGadgetExecutionControllerContext, F as AfterLLMCallAction, I as AfterLLMCallControllerContext, J as AfterLLMErrorAction, w as AgentBuilder, K as AgentOptions, N as BeforeGadgetExecutionAction, O as BeforeLLMCallAction, Q as ChunkInterceptorContext, R as Controllers, a9 as CostEstimate, ak as DEFAULT_PROMPTS, E as EventHandlers, ar as GadgetClass, T as GadgetExecutionControllerContext, as as GadgetOrClass, U as GadgetParameterInterceptorContext, V as GadgetResultInterceptorContext, H as HistoryMessage, W as Interceptors, X as LLMCallControllerContext, Y as LLMErrorControllerContext, a8 as LLMMessageBuilder, a7 as LLMRole, a6 as LLMist, a5 as LLMistOptions, Z as MessageInterceptorContext, a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, aa as ModelFeatures, ag as ModelIdentifierParser, ab as ModelLimits, ac as ModelPricing, ad as ModelRegistry, _ as ObserveChunkContext, $ as ObserveGadgetCompleteContext, a0 as ObserveGadgetStartContext, a1 as ObserveLLMCallContext, a2 as ObserveLLMCompleteContext, a3 as ObserveLLMErrorContext, a4 as Observers, ah as PromptConfig, ai as PromptContext, aj as PromptTemplate, ae as ProviderIdentifier, an as QuickOptions, aq as StreamParser, at as TextOnlyAction, au as TextOnlyContext, av as TextOnlyCustomHandler, aw as TextOnlyGadgetConfig, ax as TextOnlyHandler, ay as TextOnlyStrategy, af as TokenUsage, x as collectEvents, y as collectText, ao as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, al as resolvePromptTemplate, am as resolveRulesTemplate, z as runWithHandlers, ap as stream } from './mock-stream-C2sBQlvc.js';
+import { A as AgentHooks, o as ModelRegistry, L as LLMMessage, P as ParameterFormat, S as StreamEvent, G as GadgetRegistry, p as LLMStreamChunk, B as BaseGadget, q as ParsedGadgetCall, r as GadgetExecutionResult, s as ProviderAdapter, t as ModelDescriptor, u as ModelSpec, v as LLMGenerationOptions, w as LLMStream } from './mock-stream-C0vOqI3L.js';
+export { D as AfterGadgetExecutionAction, F as AfterGadgetExecutionControllerContext, I as AfterLLMCallAction, J as AfterLLMCallControllerContext, K as AfterLLMErrorAction, x as AgentBuilder, N as AgentOptions, O as BeforeGadgetExecutionAction, Q as BeforeLLMCallAction, R as ChunkInterceptorContext, T as Controllers, aa as CostEstimate, ak as DEFAULT_PROMPTS, E as EventHandlers, ar as GadgetClass, U as GadgetExecutionControllerContext, as as GadgetOrClass, V as GadgetParameterInterceptorContext, W as GadgetResultInterceptorContext, H as HistoryMessage, X as Interceptors, Y as LLMCallControllerContext, Z as LLMErrorControllerContext, a9 as LLMMessageBuilder, a8 as LLMRole, a7 as LLMist, a6 as LLMistOptions, _ as MessageInterceptorContext, a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, ab as ModelFeatures, ag as ModelIdentifierParser, ac as ModelLimits, ad as ModelPricing, $ as ObserveChunkContext, a0 as ObserveGadgetCompleteContext, a1 as ObserveGadgetStartContext, a2 as ObserveLLMCallContext, a3 as ObserveLLMCompleteContext, a4 as ObserveLLMErrorContext, a5 as Observers, ah as PromptConfig, ai as PromptContext, aj as PromptTemplate, ae as ProviderIdentifier, an as QuickOptions, aq as StreamParser, at as TextOnlyAction, au as TextOnlyContext, av as TextOnlyCustomHandler, aw as TextOnlyGadgetConfig, ax as TextOnlyHandler, ay as TextOnlyStrategy, af as TokenUsage, y as collectEvents, z as collectText, ao as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, al as resolvePromptTemplate, am as resolveRulesTemplate, C as runWithHandlers, ap as stream } from './mock-stream-C0vOqI3L.js';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';
@@ -18,6 +18,7 @@ import { ChatCompletionChunk } from 'openai/resources/chat/completions';
  * - **logging(options?)** - Log LLM calls and gadget execution
  * - **timing()** - Measure execution time for operations
  * - **tokenTracking()** - Track cumulative token usage and costs
+ * - **progressTracking(options?)** - Track progress with iterations, tokens, cost, and timing (SHOWCASE)
  * - **errorLogging()** - Log detailed error information
  * - **silent()** - No output (useful for testing)
  * - **monitoring(options?)** - All-in-one preset combining logging, timing, tokens, and errors
@@ -67,6 +68,89 @@ interface LoggingOptions {
     /** Include verbose details like parameters and results */
     verbose?: boolean;
 }
+/**
+ * Progress statistics reported by progressTracking preset.
+ *
+ * Contains cumulative metrics across all LLM calls in the agent session,
+ * useful for building progress UI, cost monitoring, and performance tracking.
+ */
+interface ProgressStats {
+    /** Current iteration number (increments on each LLM call start) */
+    currentIteration: number;
+    /** Total number of completed LLM calls */
+    totalCalls: number;
+    /** Cumulative input tokens across all calls */
+    totalInputTokens: number;
+    /** Cumulative output tokens across all calls */
+    totalOutputTokens: number;
+    /** Total tokens (input + output) */
+    totalTokens: number;
+    /** Cumulative cost in USD (requires modelRegistry) */
+    totalCost: number;
+    /** Elapsed time in seconds since first call */
+    elapsedSeconds: number;
+}
+/**
+ * Options for progressTracking preset.
+ *
+ * Controls how progress data is tracked and reported during agent execution.
+ */
+interface ProgressTrackingOptions {
+    /**
+     * Model registry for cost calculation.
+     *
+     * If provided, enables automatic cost estimation based on token usage
+     * and model pricing data. Without it, totalCost will always be 0.
+     *
+     * @example
+     * ```typescript
+     * import { LLMist, HookPresets } from 'llmist';
+     *
+     * const client = LLMist.create();
+     * const hooks = HookPresets.progressTracking({
+     *   modelRegistry: client.modelRegistry  // Enable cost tracking
+     * });
+     * ```
+     */
+    modelRegistry?: ModelRegistry;
+    /**
+     * Callback invoked after each LLM call completion with cumulative stats.
+     *
+     * Use this to update progress UI, log metrics, or track budgets in real-time.
+     *
+     * @example
+     * ```typescript
+     * HookPresets.progressTracking({
+     *   modelRegistry: client.modelRegistry,
+     *   onProgress: (stats) => {
+     *     console.log(`Iteration #${stats.currentIteration}`);
+     *     console.log(`Cost so far: $${stats.totalCost.toFixed(4)}`);
+     *     console.log(`Elapsed: ${stats.elapsedSeconds}s`);
+     *   }
+     * })
+     * ```
+     */
+    onProgress?: (stats: ProgressStats) => void;
+    /**
+     * Whether to log progress to console after each LLM call.
+     *
+     * When enabled, prints a summary line with tokens, cost, and elapsed time.
+     * Useful for quick debugging without implementing a custom callback.
+     *
+     * Default: false
+     *
+     * @example
+     * ```typescript
+     * // Quick console-based progress tracking
+     * HookPresets.progressTracking({
+     *   modelRegistry: client.modelRegistry,
+     *   logProgress: true  // Log to console
+     * })
+     * // Output: 📊 Progress: Iteration #2 | 1,234 tokens | $0.0056 | 12.3s
+     * ```
+     */
+    logProgress?: boolean;
+}
 /**
  * Common hook presets.
  */
@@ -232,6 +316,129 @@ declare class HookPresets {
      * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetstokentracking | Full documentation}
      */
     static tokenTracking(): AgentHooks;
+    /**
+     * Tracks comprehensive progress metrics including iterations, tokens, cost, and timing.
+     *
+     * **This preset showcases llmist's core capabilities by demonstrating:**
+     * - Observer pattern for non-intrusive monitoring
+     * - Integration with ModelRegistry for cost estimation
+     * - Callback-based architecture for flexible UI updates
+     * - Provider-agnostic token and cost tracking
+     *
+     * Unlike `tokenTracking()` which only logs to console, this preset provides
+     * structured data through callbacks, making it perfect for building custom UIs,
+     * dashboards, or progress indicators (like the llmist CLI).
+     *
+     * **Output (when logProgress: true):**
+     * - Iteration number and call count
+     * - Cumulative token usage (input + output)
+     * - Cumulative cost in USD (requires modelRegistry)
+     * - Elapsed time in seconds
+     *
+     * **Use cases:**
+     * - Building CLI progress indicators with live updates
+     * - Creating web dashboards with real-time metrics
+     * - Budget monitoring and cost alerts
+     * - Performance tracking and optimization
+     * - Custom logging to external systems (Datadog, CloudWatch, etc.)
+     *
+     * **Performance:** Minimal overhead. Uses Date.now() for timing and optional
+     * ModelRegistry.estimateCost() which is O(1) lookup. Callback invocation is
+     * synchronous and fast.
+     *
+     * @param options - Progress tracking options
+     * @param options.modelRegistry - ModelRegistry for cost estimation (optional)
+     * @param options.onProgress - Callback invoked after each LLM call (optional)
+     * @param options.logProgress - Log progress to console (default: false)
+     * @returns Hook configuration with progress tracking observers
+     *
+     * @example
+     * ```typescript
+     * // Basic usage with callback (RECOMMENDED - used by llmist CLI)
+     * import { LLMist, HookPresets } from 'llmist';
+     *
+     * const client = LLMist.create();
+     *
+     * await client.agent()
+     *   .withHooks(HookPresets.progressTracking({
+     *     modelRegistry: client.modelRegistry,
+     *     onProgress: (stats) => {
+     *       // Update your UI with stats
+     *       console.log(`#${stats.currentIteration} | ${stats.totalTokens} tokens | $${stats.totalCost.toFixed(4)}`);
+     *     }
+     *   }))
+     *   .withGadgets(Calculator)
+     *   .ask("Calculate 15 * 23");
+     * // Output: #1 | 245 tokens | $0.0012
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Console logging mode (quick debugging)
+     * await client.agent()
+     *   .withHooks(HookPresets.progressTracking({
+     *     modelRegistry: client.modelRegistry,
+     *     logProgress: true  // Simple console output
+     *   }))
+     *   .ask("Your prompt");
+     * // Output: 📊 Progress: Iteration #1 | 245 tokens | $0.0012 | 1.2s
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Budget monitoring with alerts
+     * const BUDGET_USD = 0.10;
+     *
+     * await client.agent()
+     *   .withHooks(HookPresets.progressTracking({
+     *     modelRegistry: client.modelRegistry,
+     *     onProgress: (stats) => {
+     *       if (stats.totalCost > BUDGET_USD) {
+     *         throw new Error(`Budget exceeded: $${stats.totalCost.toFixed(4)}`);
+     *       }
+     *     }
+     *   }))
+     *   .ask("Long running task...");
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Web dashboard integration
+     * let progressBar: HTMLElement;
+     *
+     * await client.agent()
+     *   .withHooks(HookPresets.progressTracking({
+     *     modelRegistry: client.modelRegistry,
+     *     onProgress: (stats) => {
+     *       // Update web UI in real-time
+     *       progressBar.textContent = `Iteration ${stats.currentIteration}`;
+     *       progressBar.dataset.cost = stats.totalCost.toFixed(4);
+     *       progressBar.dataset.tokens = stats.totalTokens.toString();
+     *     }
+     *   }))
+     *   .ask("Your prompt");
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // External logging (Datadog, CloudWatch, etc.)
+     * await client.agent()
+     *   .withHooks(HookPresets.progressTracking({
+     *     modelRegistry: client.modelRegistry,
+     *     onProgress: async (stats) => {
+     *       await metrics.gauge('llm.iteration', stats.currentIteration);
+     *       await metrics.gauge('llm.cost', stats.totalCost);
+     *       await metrics.gauge('llm.tokens', stats.totalTokens);
+     *     }
+     *   }))
+     *   .ask("Your prompt");
+     * ```
+     *
+     * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsprogresstrackingoptions | Full documentation}
+     * @see {@link ProgressTrackingOptions} for detailed options
+     * @see {@link ProgressStats} for the callback data structure
+     */
+    static progressTracking(options?: ProgressTrackingOptions): AgentHooks;
     /**
      * Logs detailed error information for debugging and troubleshooting.
      *
@@ -1424,4 +1631,4 @@ declare class OpenAIChatProvider extends BaseProviderAdapter {
 }
 declare function createOpenAIProviderFromEnv(): OpenAIChatProvider | null;
 
-export { AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, ConversationManager, type CreateGadgetConfig, Gadget, type GadgetConfig, GadgetExecutionResult, GadgetExecutor, GadgetRegistry, GeminiGenerativeProvider, HookPresets, HumanInputException, type IConversationManager, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, ModelDescriptor, ModelSpec, OpenAIChatProvider, ParsedGadgetCall, ProviderAdapter, StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGeminiProviderFromEnv, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, resolveModel, validateAndApplyDefaults, validateGadgetParams };
+export { AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, ConversationManager, type CreateGadgetConfig, Gadget, type GadgetConfig, GadgetExecutionResult, GadgetExecutor, GadgetRegistry, GeminiGenerativeProvider, HookPresets, HumanInputException, type IConversationManager, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, ModelDescriptor, ModelRegistry, ModelSpec, OpenAIChatProvider, ParsedGadgetCall, ProviderAdapter, StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGeminiProviderFromEnv, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, resolveModel, validateAndApplyDefaults, validateGadgetParams };