llmist 9.1.2 → 9.2.0

package/README.md

@@ -0,0 +1,104 @@
+# llmist
+
+<p align="center">
+  <a href="https://github.com/zbigniewsobiecki/llmist/actions/workflows/ci.yml"><img src="https://github.com/zbigniewsobiecki/llmist/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://codecov.io/gh/zbigniewsobiecki/llmist"><img src="https://codecov.io/gh/zbigniewsobiecki/llmist/graph/badge.svg?branch=dev" alt="codecov"></a>
+  <a href="https://www.npmjs.com/package/llmist"><img src="https://img.shields.io/npm/v/llmist.svg" alt="npm version"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a>
+</p>
+
+**Streaming-first multi-provider LLM client in TypeScript with home-made tool calling.**
+
+llmist implements its own tool calling syntax called "gadgets" - tools execute the moment their block is parsed, not after the response completes. Works with any model that can follow instructions.
+
+## Installation
+
+```bash
+npm install llmist
+# or
+bun add llmist
+```
+
+## Quick Start
+
+```typescript
+import { Gadget, LLMist, z } from 'llmist';
+
+// Define a gadget (tool) with Zod schema
+class Calculator extends Gadget({
+  description: 'Performs arithmetic operations',
+  schema: z.object({
+    operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
+    a: z.number(),
+    b: z.number(),
+  }),
+}) {
+  execute(params: this['params']): string {
+    const { operation, a, b } = params;
+    switch (operation) {
+      case 'add': return String(a + b);
+      case 'subtract': return String(a - b);
+      case 'multiply': return String(a * b);
+      case 'divide': return String(a / b);
+    }
+  }
+}
+
+// Run the agent
+const answer = await LLMist.createAgent()
+  .withModel('sonnet')
+  .withGadgets(Calculator)
+  .askAndCollect('What is 15 times 23?');
+
+console.log(answer);
+```
+
+## Features
+
+- **Streaming-first** - Tools execute mid-stream, not after response completes
+- **Multi-provider** - OpenAI, Anthropic, Gemini with unified API
+- **Type-safe** - Full TypeScript inference from Zod schemas
+- **Flexible hooks** - Observers, interceptors, and controllers for deep integration
+- **Built-in cost tracking** - Real-time token counting and cost estimation
+- **Multimodal** - Vision and audio input support
+
+## Providers
+
+Set one of these environment variables:
+
+```bash
+export OPENAI_API_KEY="sk-..."
+export ANTHROPIC_API_KEY="sk-ant-..."
+export GEMINI_API_KEY="..."
+```
+
+Use model aliases for convenience:
+
+```typescript
+.withModel('sonnet')   // Claude 3.5 Sonnet
+.withModel('opus')     // Claude Opus 4
+.withModel('gpt4o')    // GPT-4o
+.withModel('flash')    // Gemini 2.0 Flash
+```
+
+## Documentation
+
+Full documentation at [llmist.dev](https://llmist.dev)
+
+- [Getting Started](https://llmist.dev/library/getting-started/introduction/)
+- [Creating Gadgets](https://llmist.dev/library/guides/creating-gadgets/)
+- [Hooks System](https://llmist.dev/library/guides/hooks/)
+- [Provider Configuration](https://llmist.dev/library/providers/overview/)
+
+## Examples
+
+See the [examples directory](https://github.com/zbigniewsobiecki/llmist/tree/main/examples) for runnable examples covering all features.
+
+## Related Packages
+
+- [`@llmist/cli`](https://www.npmjs.com/package/@llmist/cli) - Command-line interface
+- [`@llmist/testing`](https://www.npmjs.com/package/@llmist/testing) - Testing utilities and mocks
+
+## License
+
+MIT

package/dist/index.cjs

@@ -1272,7 +1272,11 @@ var init_messages = __esm({
         parts.push("\n=================\n");
         for (const gadget of gadgets) {
           const gadgetName = gadget.name ?? gadget.constructor.name;
-          const instruction = gadget.getInstruction(this.argPrefix);
+          const instruction = gadget.getInstruction({
+            argPrefix: this.argPrefix,
+            startPrefix: this.startPrefix,
+            endPrefix: this.endPrefix
+          });
           const schemaMarker = "\n\nInput Schema (BLOCK):";
           const schemaIndex = instruction.indexOf(schemaMarker);
           const description = (schemaIndex !== -1 ? instruction.substring(0, schemaIndex) : instruction).trim();
@@ -6017,13 +6021,13 @@ var init_openai = __esm({
       async generateSpeech(options) {
         const client = this.client;
         const spec = getOpenAISpeechModelSpec(options.model);
-        const format = options.responseFormat ?? spec?.defaultFormat ?? "mp3";
+        const format2 = options.responseFormat ?? spec?.defaultFormat ?? "mp3";
         const voice = options.voice ?? spec?.defaultVoice ?? "alloy";
         const response = await client.audio.speech.create({
           model: options.model,
           input: options.input,
           voice,
-          response_format: format,
+          response_format: format2,
           speed: options.speed ?? 1
         });
         const audioBuffer = await response.arrayBuffer();
@@ -6035,7 +6039,7 @@ var init_openai = __esm({
             characterCount: options.input.length
           },
           cost,
-          format
+          format: format2
         };
       }
       buildApiRequest(options, descriptor, spec, messages) {
@@ -11074,6 +11078,7 @@ __export(index_exports, {
   Agent: () => Agent,
   AgentBuilder: () => AgentBuilder,
   AnthropicMessagesProvider: () => AnthropicMessagesProvider,
+  BaseSessionManager: () => BaseSessionManager,
   CompactionManager: () => CompactionManager,
   ConversationManager: () => ConversationManager,
   DEFAULT_COMPACTION_CONFIG: () => DEFAULT_COMPACTION_CONFIG,
@@ -11102,6 +11107,7 @@ __export(index_exports, {
   ModelIdentifierParser: () => ModelIdentifierParser,
   ModelRegistry: () => ModelRegistry,
   OpenAIChatProvider: () => OpenAIChatProvider,
+  SimpleSessionManager: () => SimpleSessionManager,
   SlidingWindowStrategy: () => SlidingWindowStrategy,
   StreamProcessor: () => StreamProcessor,
   SummarizationStrategy: () => SummarizationStrategy,
@@ -11120,6 +11126,7 @@ __export(index_exports, {
   createLogger: () => createLogger,
   createMediaOutput: () => createMediaOutput,
   createOpenAIProviderFromEnv: () => createOpenAIProviderFromEnv,
+  createSubagent: () => createSubagent,
   defaultLogger: () => defaultLogger,
   detectAudioMimeType: () => detectAudioMimeType,
   detectImageMimeType: () => detectImageMimeType,
@@ -11128,12 +11135,25 @@ __export(index_exports, {
   filterByDepth: () => filterByDepth,
   filterByParent: () => filterByParent,
   filterRootEvents: () => filterRootEvents,
+  format: () => format,
+  formatBytes: () => formatBytes,
+  formatDate: () => formatDate,
+  formatDuration: () => formatDuration,
   formatLLMError: () => formatLLMError,
-  getHostExports: () => getHostExports,
+  gadgetError: () => gadgetError,
+  gadgetSuccess: () => gadgetSuccess,
+  getErrorMessage: () => getErrorMessage,
+  getHostExports: () => getHostExports2,
   getModelId: () => getModelId,
+  getPresetGadgets: () => getPresetGadgets,
   getProvider: () => getProvider,
+  getSubagent: () => getSubagent,
   groupByParent: () => groupByParent,
+  hasHostExports: () => hasHostExports,
+  hasPreset: () => hasPreset,
   hasProviderPrefix: () => hasProviderPrefix,
+  hasSubagents: () => hasSubagents,
+  humanDelay: () => humanDelay,
   imageFromBase64: () => imageFromBase64,
   imageFromBuffer: () => imageFromBuffer,
   imageFromUrl: () => imageFromUrl,
@@ -11148,9 +11168,13 @@ __export(index_exports, {
   isSubagentEvent: () => isSubagentEvent,
   isTextPart: () => isTextPart,
   iterationProgressHint: () => iterationProgressHint,
+  listPresets: () => listPresets,
+  listSubagents: () => listSubagents,
   normalizeMessageContent: () => normalizeMessageContent,
   parallelGadgetHint: () => parallelGadgetHint,
   parseDataUrl: () => parseDataUrl,
+  parseManifest: () => parseManifest,
+  randomDelay: () => randomDelay,
   resolveConfig: () => resolveConfig,
   resolveHintTemplate: () => resolveHintTemplate,
   resolveModel: () => resolveModel,
@@ -11168,10 +11192,15 @@ __export(index_exports, {
   schemaToJSONSchema: () => schemaToJSONSchema,
   stream: () => stream,
   text: () => text,
+  timing: () => timing,
   toBase64: () => toBase64,
+  truncate: () => truncate,
   validateAndApplyDefaults: () => validateAndApplyDefaults,
   validateGadgetParams: () => validateGadgetParams,
   validateGadgetSchema: () => validateGadgetSchema,
+  withErrorHandling: () => withErrorHandling,
+  withRetry: () => withRetry,
+  withTimeout: () => withTimeout,
   z: () => import_zod3.z
 });
 module.exports = __toCommonJS(index_exports);
@@ -11968,17 +11997,17 @@ init_gadget_output_store();
 // src/agent/hints.ts
 init_prompt_config();
 function iterationProgressHint(options) {
-  const { timing = "always", showUrgency = true, template } = options ?? {};
+  const { timing: timing2 = "always", showUrgency = true, template } = options ?? {};
   return {
     controllers: {
       beforeLLMCall: async (ctx) => {
         const iteration = ctx.iteration + 1;
         const maxIterations = ctx.maxIterations;
         const progress = iteration / maxIterations;
-        if (timing === "late" && progress < 0.5) {
+        if (timing2 === "late" && progress < 0.5) {
           return { action: "proceed" };
         }
-        if (timing === "urgent" && progress < 0.8) {
+        if (timing2 === "urgent" && progress < 0.8) {
           return { action: "proceed" };
         }
         const remaining = maxIterations - iteration;
@@ -12139,6 +12168,24 @@ init_typed_gadget();
 
 // src/gadgets/helpers.ts
 init_input_content();
+function gadgetSuccess(data = {}) {
+  return JSON.stringify({ success: true, ...data });
+}
+function gadgetError(message, details) {
+  return JSON.stringify({ error: message, ...details });
+}
+function getErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function withErrorHandling(execute) {
+  return async (params, ctx) => {
+    try {
+      return await execute(params, ctx);
+    } catch (error) {
+      return gadgetError(getErrorMessage(error));
+    }
+  };
+}
 function createMediaOutput(kind, data, mimeType, options) {
   const buffer = data instanceof Buffer ? data : Buffer.from(data);
   return {
@@ -12334,7 +12381,313 @@ init_anthropic();
 init_discovery();
 init_gemini();
 init_openai();
+
+// src/utils/format.ts
+function truncate(text3, maxLength, suffix = "...") {
+  if (text3.length <= maxLength) return text3;
+  const truncateAt = maxLength - suffix.length;
+  if (truncateAt <= 0) return suffix.slice(0, maxLength);
+  return text3.slice(0, truncateAt) + suffix;
+}
+function formatBytes(bytes, decimals = 1) {
+  if (bytes === 0) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB", "TB", "PB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  const size = bytes / Math.pow(k, i);
+  const formatted = size % 1 === 0 ? size.toString() : size.toFixed(decimals);
+  return `${formatted} ${sizes[i]}`;
+}
+function formatDate(isoDate, options = {
+  year: "numeric",
+  month: "short",
+  day: "numeric",
+  hour: "2-digit",
+  minute: "2-digit"
+}) {
+  try {
+    const date = new Date(isoDate);
+    return date.toLocaleString(void 0, options);
+  } catch {
+    return isoDate;
+  }
+}
+function formatDuration(ms, options = {}) {
+  if (ms < 1e3) {
+    return `${Math.round(ms)}ms`;
+  }
+  const seconds = Math.floor(ms / 1e3);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  if (hours > 0) {
+    const remainingMinutes = minutes % 60;
+    const remainingSeconds = seconds % 60;
+    if (options.compact) {
+      return `${hours}h ${remainingMinutes}m`;
+    }
+    return remainingSeconds > 0 ? `${hours}h ${remainingMinutes}m ${remainingSeconds}s` : `${hours}h ${remainingMinutes}m`;
+  }
+  if (minutes > 0) {
+    const remainingSeconds = seconds % 60;
+    return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
+  }
+  const secs = ms / 1e3;
+  return secs % 1 === 0 ? `${secs}s` : `${secs.toFixed(1)}s`;
+}
+var format = {
+  truncate,
+  bytes: formatBytes,
+  date: formatDate,
+  duration: formatDuration
+};
+
+// src/utils/timing.ts
+function randomDelay(min, max) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+async function humanDelay(min = 50, max = 150) {
+  const delay = randomDelay(min, max);
+  return new Promise((resolve) => setTimeout(resolve, delay));
+}
+async function withTimeout(fn, timeoutMs, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("Operation aborted"));
+      return;
+    }
+    let settled = false;
+    const timeoutId = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        reject(new Error(`Operation timed out after ${timeoutMs}ms`));
+      }
+    }, timeoutMs);
+    const abortHandler = () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timeoutId);
+        reject(new Error("Operation aborted"));
+      }
+    };
+    signal?.addEventListener("abort", abortHandler);
+    fn().then((result) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timeoutId);
+        signal?.removeEventListener("abort", abortHandler);
+        resolve(result);
+      }
+    }).catch((error) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timeoutId);
+        signal?.removeEventListener("abort", abortHandler);
+        reject(error);
+      }
+    });
+  });
+}
+async function withRetry(fn, options = {}) {
+  const {
+    maxRetries = 3,
+    delay = 1e3,
+    backoff = "exponential",
+    maxDelay = 3e4,
+    shouldRetry = () => true,
+    onRetry
+  } = options;
+  let lastError;
+  let currentDelay = delay;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt >= maxRetries || !shouldRetry(error, attempt)) {
+        throw error;
+      }
+      const waitTime = Math.min(currentDelay, maxDelay);
+      onRetry?.(error, attempt + 1, waitTime);
+      await new Promise((resolve) => setTimeout(resolve, waitTime));
+      if (backoff === "exponential") {
+        currentDelay *= 2;
+      } else {
+        currentDelay += delay;
+      }
+    }
+  }
+  throw lastError;
+}
+var timing = {
+  randomDelay,
+  humanDelay,
+  withTimeout,
+  withRetry
+};
+
+// src/session/manager.ts
+var BaseSessionManager = class {
+  /** Map of session ID to session object */
+  sessions = /* @__PURE__ */ new Map();
+  /** Counter for generating unique session IDs */
+  idCounter = 0;
+  /**
+   * Generate a unique session ID with the given prefix.
+   *
+   * @param prefix - Prefix for the ID (e.g., "p" for pages, "b" for browsers)
+   * @returns Unique ID like "p1", "p2", etc.
+   */
+  generateId(prefix) {
+    return `${prefix}${++this.idCounter}`;
+  }
+  /**
+   * Get a session by ID.
+   */
+  getSession(id) {
+    return this.sessions.get(id);
+  }
+  /**
+   * Get a session by ID, throwing if not found.
+   */
+  requireSession(id) {
+    const session = this.sessions.get(id);
+    if (!session) {
+      throw new Error(`Session not found: ${id}`);
+    }
+    return session;
+  }
+  /**
+   * List all active session IDs.
+   */
+  listSessions() {
+    return Array.from(this.sessions.keys());
+  }
+  /**
+   * Check if a session exists.
+   */
+  hasSession(id) {
+    return this.sessions.has(id);
+  }
+  /**
+   * Close all sessions.
+   * Closes sessions in reverse order (most recent first).
+   */
+  async closeAll() {
+    const ids = this.listSessions().reverse();
+    for (const id of ids) {
+      try {
+        await this.closeSession(id);
+      } catch {
+      }
+    }
+  }
+};
+var SimpleSessionManager = class extends BaseSessionManager {
+  /**
+   * Create a session by storing the provided data.
+   */
+  async createSession(data) {
+    const id = this.generateId("s");
+    if (data !== void 0) {
+      this.sessions.set(id, data);
+    }
+    return id;
+  }
+  /**
+   * Close a session by removing it from the map.
+   */
+  async closeSession(id) {
+    this.sessions.delete(id);
+  }
+  /**
+   * Set session data directly.
+   */
+  setSession(id, data) {
+    this.sessions.set(id, data);
+  }
+};
+
+// src/agent/subagent.ts
 function getHostExports(ctx) {
+  if (!ctx?.hostExports) {
+    throw new Error(
+      "hostExports not available. Subagent gadgets must be run via llmist agent. Ensure you are using llmist >= 6.2.0 and running through the CLI or AgentBuilder."
+    );
+  }
+  return ctx.hostExports;
+}
+function createSubagent(ctx, options) {
+  const {
+    name,
+    gadgets,
+    systemPrompt,
+    model: runtimeModel,
+    defaultModel = "sonnet",
+    maxIterations: runtimeMaxIterations,
+    defaultMaxIterations = 15,
+    hooks,
+    temperature
+  } = options;
+  const { AgentBuilder: AgentBuilder2, LLMist: LLMist2 } = getHostExports(ctx);
+  const client = new LLMist2();
+  const model = resolveSubagentModel(ctx, name, runtimeModel, defaultModel);
+  const maxIterations = resolveValue(ctx, name, {
+    runtime: runtimeMaxIterations,
+    subagentKey: "maxIterations",
+    defaultValue: defaultMaxIterations
+  });
+  let builder = new AgentBuilder2(client).withModel(model).withGadgets(...gadgets).withMaxIterations(maxIterations).withParentContext(ctx);
+  if (systemPrompt) {
+    builder = builder.withSystem(systemPrompt);
+  }
+  if (hooks) {
+    builder = builder.withHooks(hooks);
+  }
+  if (temperature !== void 0) {
+    builder = builder.withTemperature(temperature);
+  }
+  if (ctx.logger) {
+    builder = builder.withLogger(ctx.logger);
+  }
+  return builder;
+}
+function hasHostExports(ctx) {
+  return ctx?.hostExports !== void 0;
+}
+
+// src/package/manifest.ts
+function parseManifest(packageJson) {
+  const llmist = packageJson.llmist;
+  if (!llmist || typeof llmist !== "object") {
+    return void 0;
+  }
+  return llmist;
+}
+function hasPreset(manifest, presetName) {
+  return manifest?.presets?.[presetName] !== void 0;
+}
+function getPresetGadgets(manifest, presetName) {
+  const preset = manifest?.presets?.[presetName];
+  if (preset === void 0) return void 0;
+  return preset;
+}
+function hasSubagents(manifest) {
+  return manifest?.subagents !== void 0 && Object.keys(manifest.subagents).length > 0;
+}
+function getSubagent(manifest, name) {
+  return manifest?.subagents?.[name];
+}
+function listSubagents(manifest) {
+  if (!manifest?.subagents) return [];
+  return Object.keys(manifest.subagents);
+}
+function listPresets(manifest) {
+  if (!manifest?.presets) return [];
+  return Object.keys(manifest.presets);
+}
+
+// src/index.ts
+function getHostExports2(ctx) {
   if (!ctx?.hostExports) {
     throw new Error(
       "hostExports not available. Gadgets that create subagents must be run via llmist agent, not standalone. Ensure you are using llmist >= 6.2.0."
@@ -12349,6 +12702,7 @@ function getHostExports(ctx) {
   Agent,
   AgentBuilder,
   AnthropicMessagesProvider,
+  BaseSessionManager,
   CompactionManager,
   ConversationManager,
   DEFAULT_COMPACTION_CONFIG,
@@ -12377,6 +12731,7 @@ function getHostExports(ctx) {
   ModelIdentifierParser,
   ModelRegistry,
   OpenAIChatProvider,
+  SimpleSessionManager,
   SlidingWindowStrategy,
   StreamProcessor,
   SummarizationStrategy,
@@ -12395,6 +12750,7 @@ function getHostExports(ctx) {
   createLogger,
   createMediaOutput,
   createOpenAIProviderFromEnv,
+  createSubagent,
   defaultLogger,
   detectAudioMimeType,
   detectImageMimeType,
@@ -12403,12 +12759,25 @@ function getHostExports(ctx) {
   filterByDepth,
   filterByParent,
   filterRootEvents,
+  format,
+  formatBytes,
+  formatDate,
+  formatDuration,
   formatLLMError,
+  gadgetError,
+  gadgetSuccess,
+  getErrorMessage,
   getHostExports,
   getModelId,
+  getPresetGadgets,
   getProvider,
+  getSubagent,
   groupByParent,
+  hasHostExports,
+  hasPreset,
   hasProviderPrefix,
+  hasSubagents,
+  humanDelay,
   imageFromBase64,
   imageFromBuffer,
   imageFromUrl,
@@ -12423,9 +12792,13 @@ function getHostExports(ctx) {
   isSubagentEvent,
   isTextPart,
   iterationProgressHint,
+  listPresets,
+  listSubagents,
   normalizeMessageContent,
   parallelGadgetHint,
   parseDataUrl,
+  parseManifest,
+  randomDelay,
   resolveConfig,
   resolveHintTemplate,
   resolveModel,
@@ -12443,10 +12816,15 @@ function getHostExports(ctx) {
   schemaToJSONSchema,
   stream,
   text,
+  timing,
   toBase64,
+  truncate,
   validateAndApplyDefaults,
   validateGadgetParams,
   validateGadgetSchema,
+  withErrorHandling,
+  withRetry,
+  withTimeout,
   z
 });
 //# sourceMappingURL=index.cjs.map