llmist 0.1.4 → 0.1.5

package/dist/index.cjs

@@ -4319,18 +4319,59 @@ init_event_handlers();
 // src/agent/hook-presets.ts
 var HookPresets = class _HookPresets {
   /**
-   * Preset: Basic logging of all events.
+   * Logs LLM calls and gadget execution to console with optional verbosity.
    *
-   * Logs LLM calls and gadget executions to console.
+   * **Output (basic mode):**
+   * - LLM call start/complete events with iteration numbers
+   * - Gadget execution start/complete with gadget names
+   * - Token counts when available
+   *
+   * **Output (verbose mode):**
+   * - All basic mode output
+   * - Full gadget parameters (formatted JSON)
+   * - Full gadget results
+   * - Complete LLM response text
+   *
+   * **Use cases:**
+   * - Basic development debugging and execution flow visibility
+   * - Understanding agent decision-making and tool usage
+   * - Troubleshooting gadget invocations
+   *
+   * **Performance:** Minimal overhead. Console writes are synchronous but fast.
    *
    * @param options - Logging options
-   * @returns Hook configuration
+   * @param options.verbose - Include full parameters and results. Default: false
+   * @returns Hook configuration that can be passed to .withHooks()
+   *
+   * @example
+   * ```typescript
+   * // Basic logging
+   * await LLMist.createAgent()
+   *   .withHooks(HookPresets.logging())
+   *   .ask("Calculate 15 * 23");
+   * // Output: [LLM] Starting call (iteration 0)
+   * //         [GADGET] Executing Calculator
+   * //         [GADGET] Completed Calculator
+   * //         [LLM] Completed (tokens: 245)
+   * ```
    *
    * @example
    * ```typescript
-   * .withHooks(HookPresets.logging())
-   * .withHooks(HookPresets.logging({ verbose: true }))
+   * // Verbose logging with full details
+   * await LLMist.createAgent()
+   *   .withHooks(HookPresets.logging({ verbose: true }))
+   *   .ask("Calculate 15 * 23");
+   * // Output includes: parameters, results, and full responses
    * ```
+   *
+   * @example
+   * ```typescript
+   * // Environment-based verbosity
+   * const isDev = process.env.NODE_ENV === 'development';
+   * .withHooks(HookPresets.logging({ verbose: isDev }))
+   * ```
+   *
+   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsloggingoptions | Full documentation}
    */
   static logging(options = {}) {
     return {
@@ -4362,16 +4403,54 @@ var HookPresets = class _HookPresets {
     };
   }
   /**
-   * Preset: Performance timing for all operations.
-   *
    * Measures and logs execution time for LLM calls and gadgets.
    *
-   * @returns Hook configuration
+   * **Output:**
+   * - Duration in milliseconds with ⏱️ emoji for each operation
+   * - Separate timing for each LLM iteration
+   * - Separate timing for each gadget execution
+   *
+   * **Use cases:**
+   * - Performance profiling and optimization
+   * - Identifying slow operations (LLM calls vs gadget execution)
+   * - Monitoring response times in production
+   * - Capacity planning and SLA tracking
+   *
+   * **Performance:** Negligible overhead. Uses Date.now() for timing measurements.
+   *
+   * @returns Hook configuration that can be passed to .withHooks()
+   *
+   * @example
+   * ```typescript
+   * // Basic timing
+   * await LLMist.createAgent()
+   *   .withHooks(HookPresets.timing())
+   *   .withGadgets(Weather, Database)
+   *   .ask("What's the weather in NYC?");
+   * // Output: ⏱️ LLM call took 1234ms
+   * //         ⏱️ Gadget Weather took 567ms
+   * //         ⏱️ LLM call took 890ms
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Combined with logging for full context
+   * .withHooks(HookPresets.merge(
+   *   HookPresets.logging(),
+   *   HookPresets.timing()
+   * ))
+   * ```
    *
    * @example
    * ```typescript
-   * .withHooks(HookPresets.timing())
+   * // Correlate performance with cost
+   * .withHooks(HookPresets.merge(
+   *   HookPresets.timing(),
+   *   HookPresets.tokenTracking()
+   * ))
    * ```
+   *
+   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetstiming | Full documentation}
    */
   static timing() {
     const timings = /* @__PURE__ */ new Map();
@@ -4408,16 +4487,57 @@ var HookPresets = class _HookPresets {
     };
   }
   /**
-   * Preset: Token usage tracking.
+   * Tracks cumulative token usage across all LLM calls.
+   *
+   * **Output:**
+   * - Per-call token count with 📊 emoji
+   * - Cumulative total across all calls
+   * - Call count for average calculations
+   *
+   * **Use cases:**
+   * - Cost monitoring and budget tracking
+   * - Optimizing prompts to reduce token usage
+   * - Comparing token efficiency across different approaches
+   * - Real-time cost estimation
    *
-   * Tracks and logs cumulative token usage across all LLM calls.
+   * **Performance:** Minimal overhead. Simple counter increments.
    *
-   * @returns Hook configuration
+   * **Note:** Token counts depend on the provider's response. Some providers
+   * may not include usage data, in which case counts won't be logged.
+   *
+   * @returns Hook configuration that can be passed to .withHooks()
+   *
+   * @example
+   * ```typescript
+   * // Basic token tracking
+   * await LLMist.createAgent()
+   *   .withHooks(HookPresets.tokenTracking())
+   *   .ask("Summarize this document...");
+   * // Output: 📊 Tokens this call: 1,234
+   * //         📊 Total tokens: 1,234 (across 1 calls)
+   * //         📊 Tokens this call: 567
+   * //         📊 Total tokens: 1,801 (across 2 calls)
+   * ```
    *
    * @example
    * ```typescript
-   * .withHooks(HookPresets.tokenTracking())
+   * // Cost calculation with custom hook
+   * let totalTokens = 0;
+   * .withHooks(HookPresets.merge(
+   *   HookPresets.tokenTracking(),
+   *   {
+   *     observers: {
+   *       onLLMCallComplete: async (ctx) => {
+   *         totalTokens += ctx.usage?.totalTokens ?? 0;
+   *         const cost = (totalTokens / 1_000_000) * 3.0; // $3 per 1M tokens
+   *         console.log(`💰 Estimated cost: $${cost.toFixed(4)}`);
+   *       },
+   *     },
+   *   }
+   * ))
    * ```
+   *
+   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetstokentracking | Full documentation}
    */
   static tokenTracking() {
     let totalTokens = 0;
@@ -4436,16 +4556,64 @@ var HookPresets = class _HookPresets {
     };
   }
   /**
-   * Preset: Error logging.
+   * Logs detailed error information for debugging and troubleshooting.
+   *
+   * **Output:**
+   * - LLM errors with ❌ emoji, including model and recovery status
+   * - Gadget errors with full context (parameters, error message)
+   * - Separate logging for LLM and gadget failures
+   *
+   * **Use cases:**
+   * - Troubleshooting production issues
+   * - Understanding error patterns and frequency
+   * - Debugging error recovery behavior
+   * - Collecting error metrics for monitoring
+   *
+   * **Performance:** Minimal overhead. Only logs when errors occur.
+   *
+   * @returns Hook configuration that can be passed to .withHooks()
    *
-   * Logs detailed error information for debugging.
+   * @example
+   * ```typescript
+   * // Basic error logging
+   * await LLMist.createAgent()
+   *   .withHooks(HookPresets.errorLogging())
+   *   .withGadgets(Database)
+   *   .ask("Fetch user data");
+   * // Output (on LLM error): ❌ LLM Error (iteration 1): Rate limit exceeded
+   * //                        Model: gpt-5-nano
+   * //                        Recovered: true
+   * // Output (on gadget error): ❌ Gadget Error: Database
+   * //                            Error: Connection timeout
+   * //                            Parameters: {...}
+   * ```
    *
-   * @returns Hook configuration
+   * @example
+   * ```typescript
+   * // Combine with monitoring for full context
+   * .withHooks(HookPresets.merge(
+   *   HookPresets.monitoring(),  // Includes errorLogging
+   *   customErrorAnalytics
+   * ))
+   * ```
    *
    * @example
    * ```typescript
-   * .withHooks(HookPresets.errorLogging())
+   * // Error analytics collection
+   * const errors: any[] = [];
+   * .withHooks(HookPresets.merge(
+   *   HookPresets.errorLogging(),
+   *   {
+   *     observers: {
+   *       onLLMCallError: async (ctx) => {
+   *         errors.push({ type: 'llm', error: ctx.error, recovered: ctx.recovered });
+   *       },
+   *     },
+   *   }
+   * ))
    * ```
+   *
+   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetserrorlogging | Full documentation}
    */
   static errorLogging() {
     return {
@@ -4466,48 +4634,131 @@ var HookPresets = class _HookPresets {
     };
   }
   /**
-   * Preset: Silent (no output).
+   * Returns empty hook configuration for clean output without any logging.
    *
-   * Useful for testing or when you want complete control.
+   * **Output:**
+   * - None. Returns {} (empty object).
+   *
+   * **Use cases:**
+   * - Clean test output without console noise
+   * - Production environments where logging is handled externally
+   * - Baseline for custom hook development
+   * - Temporary disable of all hook output
+   *
+   * **Performance:** Zero overhead. No-op hook configuration.
    *
    * @returns Empty hook configuration
    *
    * @example
    * ```typescript
-   * .withHooks(HookPresets.silent())
+   * // Clean test output
+   * describe('Agent tests', () => {
+   *   it('should calculate correctly', async () => {
+   *     const result = await LLMist.createAgent()
+   *       .withHooks(HookPresets.silent()) // No console output
+   *       .withGadgets(Calculator)
+   *       .askAndCollect("What is 15 times 23?");
+   *
+   *     expect(result).toContain("345");
+   *   });
+   * });
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Conditional silence based on environment
+   * const isTesting = process.env.NODE_ENV === 'test';
+   * .withHooks(isTesting ? HookPresets.silent() : HookPresets.monitoring())
    * ```
+   *
+   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetssilent | Full documentation}
    */
   static silent() {
     return {};
   }
   /**
-   * Merge multiple hook configurations.
+   * Combines multiple hook configurations into one.
+   *
+   * Merge allows you to compose preset and custom hooks for modular monitoring
+   * configurations. Understanding merge behavior is crucial for proper composition.
+   *
+   * **Merge behavior:**
+   * - **Observers:** Composed - all handlers run sequentially in order
+   * - **Interceptors:** Last one wins - only the last interceptor applies
+   * - **Controllers:** Last one wins - only the last controller applies
    *
-   * Combines hook presets or custom configurations into a single object.
-   * When multiple hooks target the same lifecycle event, they are composed
-   * to run sequentially (all handlers will execute).
+   * **Why interceptors/controllers don't compose:**
+   * - Interceptors have different signatures per method, making composition impractical
+   * - Controllers return specific actions that can't be meaningfully combined
+   * - Only observers support composition because they're read-only and independent
    *
-   * @param hookSets - Array of hook configurations to merge
-   * @returns Merged hook configuration with composed handlers
+   * **Use cases:**
+   * - Combining multiple presets (logging + timing + tokens)
+   * - Adding custom hooks to presets
+   * - Building modular, reusable monitoring configurations
+   * - Environment-specific hook composition
+   *
+   * **Performance:** Minimal overhead for merging. Runtime performance depends on merged hooks.
+   *
+   * @param hookSets - Variable number of hook configurations to merge
+   * @returns Single merged hook configuration with composed/overridden handlers
    *
    * @example
    * ```typescript
+   * // Combine multiple presets
+   * .withHooks(HookPresets.merge(
+   *   HookPresets.logging(),
+   *   HookPresets.timing(),
+   *   HookPresets.tokenTracking()
+   * ))
+   * // All observers from all three presets will run
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Add custom observer to preset (both run)
    * .withHooks(HookPresets.merge(
-   *   HookPresets.logging({ verbose: true }),
    *   HookPresets.timing(),
-   *   HookPresets.tokenTracking(),
    *   {
-   *     // Custom hook
    *     observers: {
    *       onLLMCallComplete: async (ctx) => {
-   *         saveToDatabase(ctx);
-   *       }
-   *     }
+   *         await saveMetrics({ tokens: ctx.usage?.totalTokens });
+   *       },
+   *     },
    *   }
    * ))
-   * // All onLLMCallComplete handlers from logging, timing, tokenTracking,
-   * // and the custom hook will execute in order
    * ```
+   *
+   * @example
+   * ```typescript
+   * // Multiple interceptors (last wins!)
+   * .withHooks(HookPresets.merge(
+   *   {
+   *     interceptors: {
+   *       interceptTextChunk: (chunk) => chunk.toUpperCase(), // Ignored
+   *     },
+   *   },
+   *   {
+   *     interceptors: {
+   *       interceptTextChunk: (chunk) => chunk.toLowerCase(), // This wins
+   *     },
+   *   }
+   * ))
+   * // Result: text will be lowercase
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Modular environment-based configuration
+   * const baseHooks = HookPresets.errorLogging();
+   * const devHooks = HookPresets.merge(baseHooks, HookPresets.monitoring({ verbose: true }));
+   * const prodHooks = HookPresets.merge(baseHooks, HookPresets.tokenTracking());
+   *
+   * const hooks = process.env.NODE_ENV === 'production' ? prodHooks : devHooks;
+   * .withHooks(hooks)
+   * ```
+   *
+   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsmergehooksets | Full documentation}
    */
   static merge(...hookSets) {
     const merged = {
@@ -4540,18 +4791,62 @@ var HookPresets = class _HookPresets {
     return merged;
   }
   /**
-   * Preset: Complete monitoring suite.
+   * Composite preset combining logging, timing, tokenTracking, and errorLogging.
+   *
+   * This is the recommended preset for development and initial production deployments,
+   * providing comprehensive observability with a single method call.
+   *
+   * **Includes:**
+   * - All output from `logging()` preset (with optional verbosity)
+   * - All output from `timing()` preset (execution times)
+   * - All output from `tokenTracking()` preset (token usage)
+   * - All output from `errorLogging()` preset (error details)
+   *
+   * **Output format:**
+   * - Event logging: [LLM]/[GADGET] messages
+   * - Timing: ⏱️ emoji with milliseconds
+   * - Tokens: 📊 emoji with per-call and cumulative counts
+   * - Errors: ❌ emoji with full error details
+   *
+   * **Use cases:**
+   * - Full observability during development
+   * - Comprehensive monitoring in production
+   * - One-liner for complete agent visibility
+   * - Troubleshooting and debugging with full context
+   *
+   * **Performance:** Combined overhead of all four presets, but still minimal in practice.
+   *
+   * @param options - Monitoring options
+   * @param options.verbose - Passed to logging() preset for detailed output. Default: false
+   * @returns Merged hook configuration combining all monitoring presets
    *
-   * Combines logging, timing, and token tracking.
+   * @example
+   * ```typescript
+   * // Basic monitoring (recommended for development)
+   * await LLMist.createAgent()
+   *   .withHooks(HookPresets.monitoring())
+   *   .withGadgets(Calculator, Weather)
+   *   .ask("What is 15 times 23, and what's the weather in NYC?");
+   * // Output: All events, timing, tokens, and errors in one place
+   * ```
    *
-   * @param options - Options for monitoring
-   * @returns Merged hook configuration
+   * @example
+   * ```typescript
+   * // Verbose monitoring with full details
+   * await LLMist.createAgent()
+   *   .withHooks(HookPresets.monitoring({ verbose: true }))
+   *   .ask("Your prompt");
+   * // Output includes: parameters, results, and complete responses
+   * ```
    *
    * @example
    * ```typescript
-   * .withHooks(HookPresets.monitoring())
-   * .withHooks(HookPresets.monitoring({ verbose: true }))
+   * // Environment-based monitoring
+   * const isDev = process.env.NODE_ENV === 'development';
+   * .withHooks(HookPresets.monitoring({ verbose: isDev }))
    * ```
+   *
+   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsmonitoringoptions | Full documentation}
    */
   static monitoring(options = {}) {
     return _HookPresets.merge(