llmist 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -4604,6 +4604,189 @@ var HookPresets = class _HookPresets {
       }
     };
   }
+  /**
+   * 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) {
+    const { modelRegistry, onProgress, logProgress = false } = options ?? {};
+    let totalCalls = 0;
+    let currentIteration = 0;
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let totalCost = 0;
+    const startTime = Date.now();
+    return {
+      observers: {
+        // Track iteration on each LLM call start
+        onLLMCallStart: async (ctx) => {
+          currentIteration++;
+        },
+        // Accumulate metrics and report progress on each LLM call completion
+        onLLMCallComplete: async (ctx) => {
+          totalCalls++;
+          if (ctx.usage) {
+            totalInputTokens += ctx.usage.inputTokens;
+            totalOutputTokens += ctx.usage.outputTokens;
+            if (modelRegistry) {
+              try {
+                const modelName = ctx.options.model.includes(":") ? ctx.options.model.split(":")[1] : ctx.options.model;
+                const costEstimate = modelRegistry.estimateCost(
+                  modelName,
+                  ctx.usage.inputTokens,
+                  ctx.usage.outputTokens
+                );
+                if (costEstimate) {
+                  totalCost += costEstimate.totalCost;
+                }
+              } catch (error) {
+                if (logProgress) {
+                  console.warn(`\u26A0\uFE0F  Cost estimation failed:`, error);
+                }
+              }
+            }
+          }
+          const stats = {
+            currentIteration,
+            totalCalls,
+            totalInputTokens,
+            totalOutputTokens,
+            totalTokens: totalInputTokens + totalOutputTokens,
+            totalCost,
+            elapsedSeconds: Number(((Date.now() - startTime) / 1e3).toFixed(1))
+          };
+          if (onProgress) {
+            onProgress(stats);
+          }
+          if (logProgress) {
+            const formattedTokens = stats.totalTokens >= 1e3 ? `${(stats.totalTokens / 1e3).toFixed(1)}k` : `${stats.totalTokens}`;
+            const formattedCost = stats.totalCost > 0 ? `$${stats.totalCost.toFixed(4)}` : "$0";
+            console.log(
+              `\u{1F4CA} Progress: Iteration #${stats.currentIteration} | ${formattedTokens} tokens | ${formattedCost} | ${stats.elapsedSeconds}s`
+            );
+          }
+        }
+      }
+    };
+  }
   /**
    * Logs detailed error information for debugging and troubleshooting.
    *