llmist 0.4.1 → 0.5.1

package/dist/{mock-stream-C0vOqI3L.d.ts → mock-stream-C8mBXRzJ.d.ts}

@@ -1,6 +1,33 @@
 import { Logger, ILogObj } from 'tslog';
 import { ZodTypeAny } from 'zod';
 
+/**
+ * Example of gadget usage to help LLMs understand proper invocation.
+ *
+ * Examples are rendered alongside the schema in `getInstruction()` to provide
+ * concrete usage patterns for the LLM.
+ *
+ * @template TParams - Inferred parameter type from Zod schema (defaults to Record<string, unknown>)
+ *
+ * @example
+ * ```typescript
+ * const calculator = createGadget({
+ *   schema: z.object({ a: z.number(), b: z.number() }),
+ *   examples: [
+ *     { params: { a: 5, b: 3 }, output: "8", comment: "Addition example" }
+ *   ],
+ *   // ...
+ * });
+ * ```
+ */
+interface GadgetExample<TParams = Record<string, unknown>> {
+    /** Example parameter values (typed to match schema) */
+    params: TParams;
+    /** Optional expected output/result string */
+    output?: string;
+    /** Optional description explaining what this example demonstrates */
+    comment?: string;
+}
 interface GadgetExecutionResult {
     gadgetName: string;
     invocationId: string;
@@ -89,7 +116,7 @@ type TextOnlyAction = {
     parameters: Record<string, unknown>;
 };
 
-type ParameterFormat = "json" | "yaml" | "auto";
+type ParameterFormat = "json" | "yaml" | "toml" | "auto";
 interface StreamParserOptions {
     startPrefix?: string;
     endPrefix?: string;
@@ -110,6 +137,11 @@ declare class StreamParser {
     private readonly parameterFormat;
     constructor(options?: StreamParserOptions);
     private takeTextUntil;
+    /**
+     * Parse gadget name, handling both old format (name:invocationId) and new format (just name).
+     * For new format, generates a unique invocation ID.
+     */
+    private parseGadgetName;
     /**
      * Parse parameter string according to configured format
      */
@@ -149,6 +181,14 @@ declare abstract class BaseGadget {
      * Set to 0 or undefined to disable timeout for this gadget.
      */
     timeoutMs?: number;
+    /**
+     * Optional usage examples to help LLMs understand proper invocation.
+     * Examples are rendered in getInstruction() alongside the schema.
+     *
+     * Note: Uses broader `unknown` type to allow typed examples from subclasses
+     * while maintaining runtime compatibility.
+     */
+    examples?: GadgetExample<unknown>[];
     /**
      * Execute the gadget with the given parameters.
      * Can be synchronous or asynchronous.
@@ -167,7 +207,7 @@ declare abstract class BaseGadget {
      * Generate instruction text for the LLM with format-specific schema.
      * Combines name, description, and parameter schema into a formatted instruction.
      *
-     * @param format - Format for the schema representation ('json' | 'yaml' | 'auto')
+     * @param format - Format for the schema representation ('json' | 'yaml' | 'toml' | 'auto')
      * @returns Formatted instruction string
      */
     getInstruction(format?: ParameterFormat): string;
@@ -232,6 +272,11 @@ interface PromptConfig {
      * Default: "Parameters in JSON format (valid JSON object)"
      */
     formatDescriptionJson?: PromptTemplate;
+    /**
+     * Format description for TOML parameter format.
+     * Default: "Parameters in TOML format (key = value pairs, use triple-quotes for multiline)"
+     */
+    formatDescriptionToml?: PromptTemplate;
     /**
      * Rules that appear in the rules section.
      * Can be an array of strings or a function that returns an array.
@@ -248,6 +293,11 @@ interface PromptConfig {
      * Default: "\n\nInput Schema (YAML):"
      */
     schemaLabelYaml?: PromptTemplate;
+    /**
+     * Schema label for TOML format.
+     * Default: "\n\nInput Schema (TOML):"
+     */
+    schemaLabelToml?: PromptTemplate;
     /**
      * Custom examples to show in the examples section.
      * If provided, replaces the default examples entirely.
@@ -285,6 +335,11 @@ declare class LLMMessageBuilder {
     private endPrefix;
     private promptConfig;
     constructor(promptConfig?: PromptConfig);
+    /**
+     * Set custom prefixes for gadget markers.
+     * Used to configure history builder to match system prompt markers.
+     */
+    withPrefixes(startPrefix: string, endPrefix: string): this;
     addSystem(content: string, metadata?: Record<string, unknown>): this;
     addGadgets(gadgets: BaseGadget[], parameterFormat?: ParameterFormat, options?: {
         startPrefix?: string;
@@ -2598,4 +2653,4 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
-export { type ObserveChunkContext as $, type AgentHooks as A, BaseGadget as B, runWithHandlers as C, type AfterGadgetExecutionAction as D, type EventHandlers as E, type AfterGadgetExecutionControllerContext as F, GadgetRegistry as G, type HistoryMessage as H, type AfterLLMCallAction as I, type AfterLLMCallControllerContext as J, type AfterLLMErrorAction as K, type LLMMessage as L, MockProviderAdapter as M, type AgentOptions as N, type BeforeGadgetExecutionAction as O, type ParameterFormat as P, type BeforeLLMCallAction as Q, type ChunkInterceptorContext as R, type StreamEvent as S, type Controllers as T, type GadgetExecutionControllerContext as U, type GadgetParameterInterceptorContext as V, type GadgetResultInterceptorContext as W, type Interceptors as X, type LLMCallControllerContext as Y, type LLMErrorControllerContext as Z, type MessageInterceptorContext as _, MockBuilder as a, type ObserveGadgetCompleteContext as a0, type ObserveGadgetStartContext as a1, type ObserveLLMCallContext as a2, type ObserveLLMCompleteContext as a3, type ObserveLLMErrorContext as a4, type Observers as a5, type LLMistOptions as a6, LLMist as a7, type LLMRole as a8, LLMMessageBuilder as a9, type CostEstimate as aa, type ModelFeatures as ab, type ModelLimits as ac, type ModelPricing as ad, type ProviderIdentifier as ae, type TokenUsage as af, ModelIdentifierParser as ag, type PromptConfig as ah, type PromptContext as ai, type PromptTemplate as aj, DEFAULT_PROMPTS as ak, resolvePromptTemplate as al, resolveRulesTemplate as am, type QuickOptions as an, complete as ao, stream as ap, StreamParser as aq, type GadgetClass as ar, type GadgetOrClass as as, type TextOnlyAction as at, type TextOnlyContext as au, type TextOnlyCustomHandler as av, type TextOnlyGadgetConfig as aw, type TextOnlyHandler as ax, type TextOnlyStrategy as ay, createMockClient as b, createMockAdapter as c, MockManager as d, createMockStream as e, createTextMockStream as f, getMockManager as g, type MockMatcher as h, type MockMatcherContext as i, type MockOptions as j, type MockRegistration as k, type MockResponse as l, mockLLM as m, type MockStats as n, ModelRegistry as o, type LLMStreamChunk as p, type ParsedGadgetCall as q, type GadgetExecutionResult as r, type ProviderAdapter as s, type ModelDescriptor as t, type ModelSpec as u, type LLMGenerationOptions as v, type LLMStream as w, AgentBuilder as x, collectEvents as y, collectText as z };
+export { type MessageInterceptorContext as $, type AgentHooks as A, BaseGadget as B, collectText as C, runWithHandlers as D, type EventHandlers as E, type AfterGadgetExecutionAction as F, GadgetRegistry as G, type HistoryMessage as H, type AfterGadgetExecutionControllerContext as I, type AfterLLMCallAction as J, type AfterLLMCallControllerContext as K, type LLMMessage as L, MockProviderAdapter as M, type AfterLLMErrorAction as N, type AgentOptions as O, type ParameterFormat as P, type BeforeGadgetExecutionAction as Q, type BeforeLLMCallAction as R, type StreamEvent as S, type ChunkInterceptorContext as T, type Controllers as U, type GadgetExecutionControllerContext as V, type GadgetParameterInterceptorContext as W, type GadgetResultInterceptorContext as X, type Interceptors as Y, type LLMCallControllerContext as Z, type LLMErrorControllerContext as _, MockBuilder as a, type ObserveChunkContext as a0, type ObserveGadgetCompleteContext as a1, type ObserveGadgetStartContext as a2, type ObserveLLMCallContext as a3, type ObserveLLMCompleteContext as a4, type ObserveLLMErrorContext as a5, type Observers as a6, type LLMistOptions as a7, LLMist as a8, type LLMRole as a9, LLMMessageBuilder as aa, type CostEstimate as ab, type ModelFeatures as ac, type ModelLimits as ad, type ModelPricing as ae, type ProviderIdentifier as af, type TokenUsage as ag, ModelIdentifierParser as ah, type PromptConfig as ai, type PromptContext as aj, type PromptTemplate as ak, DEFAULT_PROMPTS as al, resolvePromptTemplate as am, resolveRulesTemplate as an, type QuickOptions as ao, complete as ap, stream as aq, StreamParser as ar, type GadgetClass as as, type GadgetOrClass as at, type TextOnlyAction as au, type TextOnlyContext as av, type TextOnlyCustomHandler as aw, type TextOnlyGadgetConfig as ax, type TextOnlyHandler as ay, type TextOnlyStrategy as az, createMockClient as b, createMockAdapter as c, MockManager as d, createMockStream as e, createTextMockStream as f, getMockManager as g, type MockMatcher as h, type MockMatcherContext as i, type MockOptions as j, type MockRegistration as k, type MockResponse as l, mockLLM as m, type MockStats as n, ModelRegistry as o, type LLMStreamChunk as p, type GadgetExample as q, type ParsedGadgetCall as r, type GadgetExecutionResult as s, type ProviderAdapter as t, type ModelDescriptor as u, type ModelSpec as v, type LLMGenerationOptions as w, type LLMStream as x, AgentBuilder as y, collectEvents as z };