llmist 0.1.3 → 0.1.5

package/README.md

@@ -1,12 +1,14 @@
 # llmist
 
 [![CI](https://github.com/zbigniewsobiecki/llmist/actions/workflows/ci.yml/badge.svg)](https://github.com/zbigniewsobiecki/llmist/actions/workflows/ci.yml)
-[![codecov](https://codecov.io/gh/zbigniewsobiecki/llmist/branch/main/graph/badge.svg)](https://codecov.io/gh/zbigniewsobiecki/llmist)
-[![npm version](https://badge.fury.io/js/llmist.svg)](https://www.npmjs.com/package/llmist)
+[![codecov](https://codecov.io/gh/zbigniewsobiecki/llmist/graph/badge.svg)](https://codecov.io/gh/zbigniewsobiecki/llmist)
+[![npm version](https://img.shields.io/npm/v/llmist.svg)](https://www.npmjs.com/package/llmist)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 > **Universal TypeScript LLM client with streaming-first tool execution and simple, extensible agent framework**
 
+> **⚠️ EARLY WORK IN PROGRESS** - This library is under active development. APIs may change without notice. Use in production at your own risk.
+
 llmist is an asynchonous, streaming-first, provider-agnostic LLM client that makes it easy to build AI agents with **any model**—no structured outputs or native tool calling required. Switch between OpenAI, Anthropic, and Gemini without changing your code, plug into any part of the Agent workflow, have tools (Gadgets) triggered while still streaming. 
 
 ---
@@ -19,7 +21,6 @@ llmist is an asynchonous, streaming-first, provider-agnostic LLM client that mak
 - **🪝 Powerful Hooks** - Monitor, customize, and control every step of execution
 - **🎨 Beautiful API** - Fluent builder pattern with model shortcuts and presets
 - **🧪 Testing-Friendly** - Built-in mocking system for zero-cost testing
-- **🤖 Soon-to-be Production-Ready** - Timeouts, error recovery, human-in-the-loop, structured logging
 
 ---
 
@@ -152,31 +153,85 @@ const calculator = createGadget({
 
 ### 🪝 Lifecycle Hooks
 
+Monitor, transform, and control agent execution with ready-to-use presets or custom hooks:
+
+**Quick start with presets:**
+
+```typescript
+import { LLMist, HookPresets } from 'llmist';
+
+// Full monitoring suite (recommended for development)
+await LLMist.createAgent()
+  .withHooks(HookPresets.monitoring())
+  .ask('Your prompt');
+// Output: Logs + timing + token tracking + error logging
+
+// Combine specific presets for focused monitoring
+await LLMist.createAgent()
+  .withHooks(HookPresets.merge(
+    HookPresets.timing(),
+    HookPresets.tokenTracking()
+  ))
+  .ask('Your prompt');
+```
+
+**Available presets:**
+- `logging()` / `logging({ verbose: true })` - Event logging with optional details
+- `timing()` - Execution time measurements
+- `tokenTracking()` - Cumulative token usage and cost tracking
+- `errorLogging()` - Detailed error information
+- `silent()` - No output (for testing)
+- `monitoring()` - All-in-one preset combining logging, timing, tokens, and errors
+- `merge()` - Combine multiple presets or add custom hooks
+
+**Production vs Development patterns:**
+
 ```typescript
-import { HookPresets } from 'llmist';
+// Environment-based configuration
+const isDev = process.env.NODE_ENV === 'development';
+const hooks = isDev
+  ? HookPresets.monitoring({ verbose: true })  // Full visibility in dev
+  : HookPresets.merge(
+      HookPresets.errorLogging(),              // Only errors in prod
+      HookPresets.tokenTracking()              // Track costs
+    );
 
-// Use presets for instant monitoring
 await LLMist.createAgent()
-  .withHooks(HookPresets.monitoring())  // Logs + timing + tokens + errors
+  .withHooks(hooks)
   .ask('Your prompt');
+```
 
-// Or combine specific presets
-.withHooks(HookPresets.merge(
-  HookPresets.timing(),
-  HookPresets.tokenTracking()
-))
+**Custom hooks for advanced control:**
 
-// Or write custom hooks
+```typescript
+// Observers: read-only monitoring
 .withHooks({
   observers: {
     onLLMCallComplete: async (ctx) => {
       console.log(`Used ${ctx.usage?.totalTokens} tokens`);
+      await sendMetricsToDataDog(ctx);
     },
   },
+})
+
+// Interceptors: transform data in flight
+.withHooks({
   interceptors: {
     interceptTextChunk: (chunk) => chunk.toUpperCase(),
   },
 })
+
+// Controllers: control execution flow
+.withHooks({
+  controllers: {
+    beforeLLMCall: async (ctx) => {
+      if (shouldCache(ctx)) {
+        return { action: 'skip', syntheticResponse: cachedResponse };
+      }
+      return { action: 'proceed' };
+    },
+  },
+})
 ```
 
 📖 **[Hooks Guide](./docs/HOOKS.md)** | **[Examples](./examples/03-hooks.ts)**

package/dist/{chunk-TP7HE3MN.js → chunk-J3NCIWMY.js}

@@ -424,14 +424,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);
@@ -439,18 +440,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("");
       }
@@ -465,26 +465,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) {
@@ -492,7 +492,6 @@ ${schema}
           return this.promptConfig.customExamples(context);
         }
         const parts = [];
-        parts.push("\n  <examples>");
         const singleExample = parameterFormat === "yaml" ? `${this.startPrefix}translate
 from: English
 to: Polish
@@ -501,9 +500,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
@@ -520,21 +520,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) {
@@ -1009,18 +1008,18 @@ var init_executor = __esm({
 
 // src/gadgets/parser.ts
 import * as yaml from "js-yaml";
-var StreamParser;
+var globalInvocationCounter, StreamParser;
 var init_parser = __esm({
   "src/gadgets/parser.ts"() {
     "use strict";
     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;
@@ -1087,7 +1086,7 @@ var init_parser = __esm({
             invocationId = parts[1];
           } else {
             actualGadgetName = gadgetName;
-            invocationId = `auto_${++this.invocationCounter}`;
+            invocationId = `gadget_${++globalInvocationCounter}`;
           }
           const contentStartIndex = metadataEndIndex + 1;
           let partEndIndex;
@@ -1144,11 +1143,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;
       }
     };
   }
@@ -4447,4 +4445,4 @@ export {
   init_builder,
   BaseGadget
 };
-//# sourceMappingURL=chunk-TP7HE3MN.js.map
+//# sourceMappingURL=chunk-J3NCIWMY.js.map