llmist 0.1.3 → 0.1.5

package/dist/index.cjs

@@ -436,14 +436,15 @@ var init_messages = __esm({
           context
         );
         parts.push(mainInstruction);
-        parts.push(this.buildGadgetsXmlSection(gadgets, parameterFormat));
+        parts.push(this.buildGadgetsSection(gadgets, parameterFormat));
         parts.push(this.buildUsageSection(parameterFormat, context));
         this.messages.push({ role: "system", content: parts.join("") });
         return this;
       }
-      buildGadgetsXmlSection(gadgets, parameterFormat) {
+      buildGadgetsSection(gadgets, parameterFormat) {
         const parts = [];
-        parts.push("<GADGETS>");
+        parts.push("\n\nAVAILABLE GADGETS");
+        parts.push("\n=================\n");
         for (const gadget of gadgets) {
           const gadgetName = gadget.name ?? gadget.constructor.name;
           const instruction = gadget.getInstruction(parameterFormat);
@@ -451,18 +452,17 @@ var init_messages = __esm({
           const schemaIndex = instruction.indexOf(schemaMarker);
           const description = (schemaIndex !== -1 ? instruction.substring(0, schemaIndex) : instruction).trim();
           const schema = schemaIndex !== -1 ? instruction.substring(schemaIndex + schemaMarker.length).trim() : "";
-          parts.push("\n  <gadget>");
           parts.push(`
-    <name>${gadgetName}</name>`);
+GADGET: ${gadgetName}`);
           parts.push(`
-    <description>${description}</description>`);
+${description}`);
           if (schema) {
             parts.push(`
-    <schema format="${parameterFormat}">
-${schema}
-    </schema>`);
+
+PARAMETERS (${parameterFormat.toUpperCase()}):
+${schema}`);
           }
-          parts.push("\n  </gadget>");
+          parts.push("\n\n---");
         }
         return parts.join("");
       }
@@ -477,26 +477,26 @@ ${schema}
           DEFAULT_PROMPTS.formatDescriptionJson,
           context
         );
-        parts.push("<usage>");
+        parts.push("\n\nHOW TO INVOKE GADGETS");
+        parts.push("\n=====================\n");
         const criticalUsage = resolvePromptTemplate(
           this.promptConfig.criticalUsage,
           DEFAULT_PROMPTS.criticalUsage,
           context
         );
         parts.push(`
-  <critical>${criticalUsage}</critical>`);
-        parts.push("\n  <format>");
+CRITICAL: ${criticalUsage}
+`);
+        parts.push("\nFORMAT:");
         parts.push(`
-    <step>Start marker: ${this.startPrefix}gadget_name</step>`);
+  1. Start marker: ${this.startPrefix}gadget_name`);
         parts.push(`
-    <step>${formatDescription}</step>`);
+  2. ${formatDescription}`);
         parts.push(`
-    <step>End marker: ${this.endPrefix}</step>`);
-        parts.push("\n  </format>");
+  3. End marker: ${this.endPrefix}`);
         parts.push(this.buildExamplesSection(parameterFormat, context));
         parts.push(this.buildRulesSection(context));
-        parts.push("\n</usage>");
-        parts.push("\n</GADGETS>\n\n");
+        parts.push("\n");
         return parts.join("");
       }
       buildExamplesSection(parameterFormat, context) {
@@ -504,7 +504,6 @@ ${schema}
           return this.promptConfig.customExamples(context);
         }
         const parts = [];
-        parts.push("\n  <examples>");
         const singleExample = parameterFormat === "yaml" ? `${this.startPrefix}translate
 from: English
 to: Polish
@@ -513,9 +512,10 @@ ${this.endPrefix}` : `${this.startPrefix}translate
 {"from": "English", "to": "Polish", "content": "Paris is the capital of France."}
 ${this.endPrefix}`;
         parts.push(`
-    <example title="Single Gadget">
-${singleExample}
-    </example>`);
+
+EXAMPLE (Single Gadget):
+
+${singleExample}`);
         const multipleExample = parameterFormat === "yaml" ? `${this.startPrefix}translate
 from: English
 to: Polish
@@ -532,21 +532,20 @@ ${this.startPrefix}analyze
 {"type": "economic_analysis", "matter": "Polish Economy", "question": "Polish arms exports 2025."}
 ${this.endPrefix}`;
         parts.push(`
-    <example title="Multiple Gadgets">
-${multipleExample}
-    </example>`);
-        parts.push("\n  </examples>");
+
+EXAMPLE (Multiple Gadgets):
+
+${multipleExample}`);
         return parts.join("");
       }
       buildRulesSection(context) {
         const parts = [];
-        parts.push("\n  <rules>");
+        parts.push("\n\nRULES:");
         const rules = resolveRulesTemplate(this.promptConfig.rules, context);
         for (const rule of rules) {
           parts.push(`
-    <rule>${rule}</rule>`);
+  - ${rule}`);
         }
-        parts.push("\n  </rules>");
         return parts.join("");
       }
       addUser(content, metadata) {
@@ -1186,19 +1185,19 @@ var init_executor = __esm({
 });
 
 // src/gadgets/parser.ts
-var yaml, StreamParser;
+var yaml, globalInvocationCounter, StreamParser;
 var init_parser = __esm({
   "src/gadgets/parser.ts"() {
     "use strict";
     yaml = __toESM(require("js-yaml"), 1);
     init_constants();
+    globalInvocationCounter = 0;
     StreamParser = class {
       buffer = "";
       lastReportedTextLength = 0;
       startPrefix;
       endPrefix;
       parameterFormat;
-      invocationCounter = 0;
       constructor(options = {}) {
         this.startPrefix = options.startPrefix ?? GADGET_START_PREFIX;
         this.endPrefix = options.endPrefix ?? GADGET_END_PREFIX;
@@ -1265,7 +1264,7 @@ var init_parser = __esm({
             invocationId = parts[1];
           } else {
             actualGadgetName = gadgetName;
-            invocationId = `auto_${++this.invocationCounter}`;
+            invocationId = `gadget_${++globalInvocationCounter}`;
           }
           const contentStartIndex = metadataEndIndex + 1;
           let partEndIndex;
@@ -1322,11 +1321,10 @@ var init_parser = __esm({
           yield { type: "text", content: remainingText };
         }
       }
-      // Reset parser state
+      // Reset parser state (note: global invocation counter is NOT reset to ensure unique IDs)
       reset() {
         this.buffer = "";
         this.lastReportedTextLength = 0;
-        this.invocationCounter = 0;
       }
     };
   }
@@ -4321,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.
+   *
+   * **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
    *
-   * Logs LLM calls and gadget executions to console.
+   * **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
+   * // 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
-   * .withHooks(HookPresets.logging())
-   * .withHooks(HookPresets.logging({ verbose: true }))
+   * // 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 {
@@ -4364,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
-   * .withHooks(HookPresets.timing())
+   * // 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
+   * // 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();
@@ -4410,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
-   * .withHooks(HookPresets.tokenTracking())
+   * // 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
+   * // 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;
@@ -4438,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
    *
-   * Logs detailed error information for debugging.
+   * **Use cases:**
+   * - Troubleshooting production issues
+   * - Understanding error patterns and frequency
+   * - Debugging error recovery behavior
+   * - Collecting error metrics for monitoring
    *
-   * @returns Hook configuration
+   * **Performance:** Minimal overhead. Only logs when errors occur.
+   *
+   * @returns Hook configuration that can be passed to .withHooks()
+   *
+   * @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: {...}
+   * ```
+   *
+   * @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 {
@@ -4468,48 +4634,131 @@ var HookPresets = class _HookPresets {
     };
   }
   /**
-   * Preset: Silent (no output).
+   * Returns empty hook configuration for clean output without any logging.
+   *
+   * **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
    *
-   * Useful for testing or when you want complete control.
+   * **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
+   *
+   * **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
+   *
+   * **Use cases:**
+   * - Combining multiple presets (logging + timing + tokens)
+   * - Adding custom hooks to presets
+   * - Building modular, reusable monitoring configurations
+   * - Environment-specific hook composition
    *
-   * 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).
+   * **Performance:** Minimal overhead for merging. Runtime performance depends on merged hooks.
    *
-   * @param hookSets - Array of hook configurations to merge
-   * @returns Merged hook configuration with composed handlers
+   * @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 = {
@@ -4542,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(