llmist 1.3.1 → 1.5.0

package/dist/index.cjs

@@ -857,38 +857,83 @@ function formatParamsAsBlock(params, prefix = "", argPrefix = GADGET_ARG_PREFIX)
   }
   return lines.join("\n");
 }
-function formatSchemaAsPlainText(schema, indent = "") {
+function formatParamLine(key, propObj, isRequired, indent = "") {
+  const type = propObj.type;
+  const description = propObj.description;
+  const enumValues = propObj.enum;
+  let line = `${indent}- ${key}`;
+  if (type === "array") {
+    const items = propObj.items;
+    const itemType = items?.type || "any";
+    line += ` (array of ${itemType})`;
+  } else if (type === "object" && propObj.properties) {
+    line += " (object)";
+  } else {
+    line += ` (${type})`;
+  }
+  if (isRequired && indent !== "") {
+    line += " [required]";
+  }
+  if (description) {
+    line += `: ${description}`;
+  }
+  if (enumValues) {
+    line += ` - one of: ${enumValues.map((v) => `"${v}"`).join(", ")}`;
+  }
+  return line;
+}
+function formatSchemaAsPlainText(schema, indent = "", atRoot = true) {
   const lines = [];
   const properties = schema.properties || {};
   const required = schema.required || [];
-  for (const [key, prop] of Object.entries(properties)) {
-    const propObj = prop;
-    const type = propObj.type;
-    const description = propObj.description;
-    const isRequired = required.includes(key);
-    const enumValues = propObj.enum;
-    let line = `${indent}- ${key}`;
-    if (type === "array") {
-      const items = propObj.items;
-      const itemType = items?.type || "any";
-      line += ` (array of ${itemType})`;
-    } else if (type === "object" && propObj.properties) {
-      line += " (object)";
-    } else {
-      line += ` (${type})`;
+  if (atRoot && indent === "") {
+    const requiredProps = [];
+    const optionalProps = [];
+    for (const [key, prop] of Object.entries(properties)) {
+      if (required.includes(key)) {
+        requiredProps.push([key, prop]);
+      } else {
+        optionalProps.push([key, prop]);
+      }
     }
-    if (isRequired) {
-      line += " [required]";
+    const reqCount = requiredProps.length;
+    const optCount = optionalProps.length;
+    if (reqCount > 0 || optCount > 0) {
+      const parts = [];
+      if (reqCount > 0) parts.push(`${reqCount} required`);
+      if (optCount > 0) parts.push(`${optCount} optional`);
+      lines.push(parts.join(", "));
+      lines.push("");
     }
-    if (description) {
-      line += `: ${description}`;
+    if (reqCount > 0) {
+      lines.push("REQUIRED Parameters:");
+      for (const [key, prop] of requiredProps) {
+        lines.push(formatParamLine(key, prop, true, ""));
+        const propObj = prop;
+        if (propObj.type === "object" && propObj.properties) {
+          lines.push(formatSchemaAsPlainText(propObj, "  ", false));
+        }
+      }
     }
-    if (enumValues) {
-      line += ` - one of: ${enumValues.map((v) => `"${v}"`).join(", ")}`;
+    if (optCount > 0) {
+      if (reqCount > 0) lines.push("");
+      lines.push("OPTIONAL Parameters:");
+      for (const [key, prop] of optionalProps) {
+        lines.push(formatParamLine(key, prop, false, ""));
+        const propObj = prop;
+        if (propObj.type === "object" && propObj.properties) {
+          lines.push(formatSchemaAsPlainText(propObj, "  ", false));
+        }
+      }
     }
-    lines.push(line);
-    if (type === "object" && propObj.properties) {
-      lines.push(formatSchemaAsPlainText(propObj, indent + "  "));
+    return lines.join("\n");
+  }
+  for (const [key, prop] of Object.entries(properties)) {
+    const isRequired = required.includes(key);
+    lines.push(formatParamLine(key, prop, isRequired, indent));
+    const propObj = prop;
+    if (propObj.type === "object" && propObj.properties) {
+      lines.push(formatSchemaAsPlainText(propObj, indent + "  ", false));
     }
   }
   return lines.join("\n");
@@ -939,10 +984,11 @@ var init_gadget = __esm({
        * Generate instruction text for the LLM.
        * Combines name, description, and parameter schema into a formatted instruction.
        *
-       * @param argPrefix - Optional custom argument prefix for block format examples
+       * @param optionsOrArgPrefix - Optional custom prefixes for examples, or just argPrefix string for backwards compatibility
        * @returns Formatted instruction string
        */
-      getInstruction(argPrefix) {
+      getInstruction(optionsOrArgPrefix) {
+        const options = typeof optionsOrArgPrefix === "string" ? { argPrefix: optionsOrArgPrefix } : optionsOrArgPrefix;
         const parts = [];
         parts.push(this.description);
         if (this.parameterSchema) {
@@ -956,18 +1002,25 @@ var init_gadget = __esm({
         }
         if (this.examples && this.examples.length > 0) {
           parts.push("\n\nExamples:");
-          const effectiveArgPrefix = argPrefix ?? GADGET_ARG_PREFIX;
+          const effectiveArgPrefix = options?.argPrefix ?? GADGET_ARG_PREFIX;
+          const effectiveStartPrefix = options?.startPrefix ?? GADGET_START_PREFIX;
+          const effectiveEndPrefix = options?.endPrefix ?? GADGET_END_PREFIX;
+          const gadgetName = this.name || this.constructor.name;
           this.examples.forEach((example, index) => {
             if (index > 0) {
               parts.push("");
+              parts.push("---");
+              parts.push("");
             }
             if (example.comment) {
               parts.push(`# ${example.comment}`);
             }
-            parts.push("Input:");
+            parts.push(`${effectiveStartPrefix}${gadgetName}`);
             parts.push(formatParamsAsBlock(example.params, "", effectiveArgPrefix));
+            parts.push(effectiveEndPrefix);
             if (example.output !== void 0) {
-              parts.push("Output:");
+              parts.push("");
+              parts.push("Expected Output:");
               parts.push(example.output);
             }
           });
@@ -3307,6 +3360,8 @@ var init_agent = __esm({
       outputLimitCharLimit;
       // Context compaction
       compactionManager;
+      // Cancellation
+      signal;
       /**
        * Creates a new Agent instance.
        * @internal This constructor is private. Use LLMist.createAgent() or AgentBuilder instead.
@@ -3374,6 +3429,7 @@ var init_agent = __esm({
             options.compactionConfig
           );
         }
+        this.signal = options.signal;
       }
       /**
        * Get the gadget registry for this agent.
@@ -3491,7 +3547,8 @@ var init_agent = __esm({
               model: this.model,
               messages: this.conversation.getMessages(),
               temperature: this.temperature,
-              maxTokens: this.defaultMaxTokens
+              maxTokens: this.defaultMaxTokens,
+              signal: this.signal
             };
             await this.safeObserve(async () => {
               if (this.hooks.observers?.onLLMCallStart) {
@@ -4109,7 +4166,7 @@ var init_base_provider = __esm({
       async *stream(options, descriptor, spec) {
         const preparedMessages = this.prepareMessages(options.messages);
         const payload = this.buildRequestPayload(options, descriptor, spec, preparedMessages);
-        const rawStream = await this.executeStreamRequest(payload);
+        const rawStream = await this.executeStreamRequest(payload, options.signal);
         yield* this.wrapStream(rawStream);
       }
       /**
@@ -4227,9 +4284,9 @@ var init_anthropic = __esm({
         };
         return payload;
       }
-      async executeStreamRequest(payload) {
+      async executeStreamRequest(payload, signal) {
         const client = this.client;
-        const stream2 = await client.messages.create(payload);
+        const stream2 = await client.messages.create(payload, signal ? { signal } : void 0);
         return stream2;
       }
       async *wrapStream(iterable) {
@@ -4561,9 +4618,15 @@ var init_gemini = __esm({
           config
         };
       }
-      async executeStreamRequest(payload) {
+      async executeStreamRequest(payload, signal) {
         const client = this.client;
-        const streamResponse = await client.models.generateContentStream(payload);
+        const streamResponse = await client.models.generateContentStream({
+          ...payload,
+          config: {
+            ...payload.config,
+            ...signal ? { abortSignal: signal } : {}
+          }
+        });
         return streamResponse;
       }
       /**
@@ -5152,9 +5215,9 @@ var init_openai = __esm({
           ...shouldIncludeTemperature ? { temperature } : {}
         };
       }
-      async executeStreamRequest(payload) {
+      async executeStreamRequest(payload, signal) {
         const client = this.client;
-        const stream2 = await client.chat.completions.create(payload);
+        const stream2 = await client.chat.completions.create(payload, signal ? { signal } : void 0);
         return stream2;
       }
       async *wrapStream(iterable) {
@@ -5817,6 +5880,7 @@ var init_builder = __esm({
       gadgetOutputLimit;
       gadgetOutputLimitPercent;
       compactionConfig;
+      signal;
       constructor(client) {
         this.client = client;
       }
@@ -6263,6 +6327,35 @@ var init_builder = __esm({
         this.compactionConfig = { enabled: false };
         return this;
       }
+      /**
+       * Set an abort signal for cancelling requests mid-flight.
+       *
+       * When the signal is aborted, the current LLM request will be cancelled
+       * and the agent loop will exit gracefully.
+       *
+       * @param signal - AbortSignal from an AbortController
+       * @returns This builder for chaining
+       *
+       * @example
+       * ```typescript
+       * const controller = new AbortController();
+       *
+       * // Cancel after 30 seconds
+       * setTimeout(() => controller.abort(), 30000);
+       *
+       * const agent = LLMist.createAgent()
+       *   .withModel("sonnet")
+       *   .withSignal(controller.signal)
+       *   .ask("Write a long story");
+       *
+       * // Or cancel on user action
+       * document.getElementById("cancel").onclick = () => controller.abort();
+       * ```
+       */
+      withSignal(signal) {
+        this.signal = signal;
+        return this;
+      }
       /**
        * Add a synthetic gadget call to the conversation history.
        *
@@ -6379,7 +6472,8 @@ ${endPrefix}`
           defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
           gadgetOutputLimit: this.gadgetOutputLimit,
           gadgetOutputLimitPercent: this.gadgetOutputLimitPercent,
-          compactionConfig: this.compactionConfig
+          compactionConfig: this.compactionConfig,
+          signal: this.signal
         };
         return new Agent(AGENT_INTERNAL_KEY, options);
       }
@@ -6482,7 +6576,8 @@ ${endPrefix}`
           defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
           gadgetOutputLimit: this.gadgetOutputLimit,
           gadgetOutputLimitPercent: this.gadgetOutputLimitPercent,
-          compactionConfig: this.compactionConfig
+          compactionConfig: this.compactionConfig,
+          signal: this.signal
         };
         return new Agent(AGENT_INTERNAL_KEY, options);
       }