llmist 0.7.0 → 1.0.0

package/dist/{mock-stream-B2qwECvd.d.cts → mock-stream-DKF5yatf.d.cts}

@@ -40,7 +40,7 @@ interface GadgetExecutionResult {
 interface ParsedGadgetCall {
     gadgetName: string;
     invocationId: string;
-    parametersYaml: string;
+    parametersRaw: string;
     parameters?: Record<string, unknown>;
     parseError?: string;
 }
@@ -116,46 +116,6 @@ type TextOnlyAction = {
     parameters: Record<string, unknown>;
 };
 
-type ParameterFormat = "json" | "yaml" | "toml" | "auto";
-interface StreamParserOptions {
-    startPrefix?: string;
-    endPrefix?: string;
-    /**
-     * Format for parsing gadget parameters.
-     * - 'json': Parse as JSON (more robust, recommended for complex nested data)
-     * - 'yaml': Parse as YAML (backward compatible)
-     * - 'auto': Try JSON first, fall back to YAML
-     * @default 'json'
-     */
-    parameterFormat?: ParameterFormat;
-}
-declare class StreamParser {
-    private buffer;
-    private lastReportedTextLength;
-    private readonly startPrefix;
-    private readonly endPrefix;
-    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;
-    /**
-     * Truncate verbose parse errors to avoid context overflow.
-     * Keeps first meaningful line and limits total length.
-     */
-    private truncateParseError;
-    /**
-     * Parse parameter string according to configured format
-     */
-    private parseParameters;
-    feed(chunk: string): Generator<StreamEvent>;
-    finalize(): Generator<StreamEvent>;
-    reset(): void;
-}
-
 /**
  * Internal base class for gadgets. Most users should use the `Gadget` class
  * (formerly TypedGadget) or `createGadget()` function instead, as they provide
@@ -205,29 +165,29 @@ declare abstract class BaseGadget {
     /**
      * Auto-generated instruction text for the LLM.
      * Combines name, description, and parameter schema into a formatted instruction.
-     * @deprecated Use getInstruction(format) instead for format-specific schemas
+     * @deprecated Use getInstruction() instead
      */
     get instruction(): string;
     /**
-     * Generate instruction text for the LLM with format-specific schema.
+     * Generate instruction text for the LLM.
      * Combines name, description, and parameter schema into a formatted instruction.
      *
-     * @param format - Format for the schema representation ('json' | 'yaml' | 'toml' | 'auto')
+     * @param argPrefix - Optional custom argument prefix for block format examples
      * @returns Formatted instruction string
      */
-    getInstruction(format?: ParameterFormat): string;
+    getInstruction(argPrefix?: string): string;
 }
 
 /**
  * Context provided to prompt template functions for rendering dynamic content.
  */
 interface PromptContext {
-    /** The parameter format being used (json or yaml) */
-    parameterFormat: ParameterFormat;
     /** Custom gadget start prefix */
     startPrefix: string;
     /** Custom gadget end prefix */
     endPrefix: string;
+    /** Custom argument prefix for block format */
+    argPrefix: string;
     /** Number of gadgets being registered */
     gadgetCount: number;
     /** Names of all gadgets */
@@ -268,41 +228,16 @@ interface PromptConfig {
      */
     criticalUsage?: PromptTemplate;
     /**
-     * Format description for YAML parameter format.
-     * Default: "Parameters in YAML format (one per line)"
-     */
-    formatDescriptionYaml?: PromptTemplate;
-    /**
-     * Format description for JSON parameter format.
-     * Default: "Parameters in JSON format (valid JSON object)"
+     * Format description for the block parameter format.
+     * Default uses the configured argPrefix dynamically.
      */
-    formatDescriptionJson?: PromptTemplate;
-    /**
-     * Format description for TOML parameter format.
-     * Default: "Parameters in TOML format (key = value pairs, use heredoc for multiline: key = <<<EOF ... EOF)"
-     */
-    formatDescriptionToml?: PromptTemplate;
+    formatDescription?: PromptTemplate;
     /**
      * Rules that appear in the rules section.
      * Can be an array of strings or a function that returns an array.
-     * Default includes 6 rules about not using function calling.
+     * Default includes rules about not using function calling.
      */
     rules?: PromptTemplate | string[] | ((context: PromptContext) => string[]);
-    /**
-     * Schema label for JSON format.
-     * Default: "\n\nInput Schema (JSON):"
-     */
-    schemaLabelJson?: PromptTemplate;
-    /**
-     * Schema label for YAML format.
-     * 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.
@@ -312,7 +247,6 @@ interface PromptConfig {
 }
 /**
  * Default prompt templates used by llmist.
- * These match the original hardcoded strings.
  */
 declare const DEFAULT_PROMPTS: Required<Omit<PromptConfig, "rules" | "customExamples"> & {
     rules: (context: PromptContext) => string[];
@@ -338,17 +272,19 @@ declare class LLMMessageBuilder {
     private readonly messages;
     private startPrefix;
     private endPrefix;
+    private argPrefix;
     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;
+    withPrefixes(startPrefix: string, endPrefix: string, argPrefix?: string): this;
     addSystem(content: string, metadata?: Record<string, unknown>): this;
-    addGadgets(gadgets: BaseGadget[], parameterFormat?: ParameterFormat, options?: {
+    addGadgets(gadgets: BaseGadget[], options?: {
         startPrefix?: string;
         endPrefix?: string;
+        argPrefix?: string;
     }): this;
     private buildGadgetsSection;
     private buildUsageSection;
@@ -356,8 +292,12 @@ declare class LLMMessageBuilder {
     private buildRulesSection;
     addUser(content: string, metadata?: Record<string, unknown>): this;
     addAssistant(content: string, metadata?: Record<string, unknown>): this;
-    addGadgetCall(gadget: string, parameters: Record<string, unknown>, result: string, parameterFormat?: ParameterFormat): this;
-    private formatParameters;
+    addGadgetCall(gadget: string, parameters: Record<string, unknown>, result: string): this;
+    /**
+     * Format parameters as Block format with JSON Pointer paths.
+     * Uses the configured argPrefix for consistency with system prompt.
+     */
+    private formatBlockParameters;
     build(): LLMMessage[];
 }
 
@@ -374,6 +314,8 @@ interface ModelPricing {
     output: number;
     /** Price per 1 million cached input tokens in USD (if supported) */
     cachedInput?: number;
+    /** Price per 1 million cache write tokens in USD (Anthropic: 1.25x input price) */
+    cacheWriteInput?: number;
 }
 interface ModelFeatures {
     /** Supports streaming responses */
@@ -426,6 +368,10 @@ interface ModelLimits {
 }
 interface CostEstimate {
     inputCost: number;
+    /** Cost for cached input tokens (already included in inputCost calculation) */
+    cachedInputCost: number;
+    /** Cost for cache creation tokens (already included in inputCost calculation, Anthropic only) */
+    cacheCreationCost: number;
     outputCost: number;
     totalCost: number;
     currency: "USD";
@@ -446,6 +392,10 @@ interface TokenUsage {
     inputTokens: number;
     outputTokens: number;
     totalTokens: number;
+    /** Number of input tokens served from cache (subset of inputTokens) */
+    cachedInputTokens?: number;
+    /** Number of input tokens written to cache (subset of inputTokens, Anthropic only) */
+    cacheCreationInputTokens?: number;
 }
 interface LLMStreamChunk {
     text: string;
@@ -587,12 +537,13 @@ declare class ModelRegistry {
     /**
      * Estimate API cost for a given model and token usage
      * @param modelId - Full model identifier
-     * @param inputTokens - Number of input tokens
+     * @param inputTokens - Number of input tokens (total, including cached and cache creation)
      * @param outputTokens - Number of output tokens
-     * @param useCachedInput - Whether to use cached input pricing (if supported by provider)
+     * @param cachedInputTokens - Number of cached input tokens (subset of inputTokens)
+     * @param cacheCreationInputTokens - Number of cache creation tokens (subset of inputTokens, Anthropic only)
      * @returns CostEstimate if model found, undefined otherwise
      */
-    estimateCost(modelId: string, inputTokens: number, outputTokens: number, useCachedInput?: boolean): CostEstimate | undefined;
+    estimateCost(modelId: string, inputTokens: number, outputTokens: number, cachedInputTokens?: number, cacheCreationInputTokens?: number): CostEstimate | undefined;
     /**
      * Validate that requested token count fits within model limits
      * @param modelId - Full model identifier
@@ -961,7 +912,7 @@ interface EventHandlers {
     onGadgetCall?: (call: {
         gadgetName: string;
         parameters?: Record<string, unknown>;
-        parametersYaml: string;
+        parametersRaw: string;
     }) => void | Promise<void>;
     /** Called when a gadget execution completes */
     onGadgetResult?: (result: {
@@ -1179,11 +1130,8 @@ interface ObserveLLMCompleteContext {
     iteration: number;
     options: Readonly<LLMGenerationOptions>;
     finishReason: string | null;
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-    };
+    /** Token usage including cached token counts when available */
+    usage?: TokenUsage;
     /** The complete raw response text */
     rawResponse: string;
     /** The final message that will be added to history (after interceptors) */
@@ -1242,12 +1190,8 @@ interface ObserveChunkContext {
     rawChunk: string;
     /** Accumulated text so far */
     accumulatedText: string;
-    /** Token usage if available (Anthropic sends input tokens at stream start) */
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-    };
+    /** Token usage if available (providers send usage at stream start/end) */
+    usage?: TokenUsage;
     logger: Logger<ILogObj>;
 }
 /**
@@ -1387,11 +1331,8 @@ interface AfterLLMCallControllerContext {
     iteration: number;
     options: Readonly<LLMGenerationOptions>;
     finishReason: string | null;
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-    };
+    /** Token usage including cached token counts when available */
+    usage?: TokenUsage;
     /** The final message (after interceptors) that will be added to history */
     finalMessage: string;
     logger: Logger<ILogObj>;
@@ -1552,12 +1493,12 @@ interface AgentOptions {
     hooks?: AgentHooks;
     /** Callback for human input */
     onHumanInputRequired?: (question: string) => Promise<string>;
-    /** Parameter format */
-    parameterFormat?: ParameterFormat;
     /** Custom gadget start prefix */
     gadgetStartPrefix?: string;
     /** Custom gadget end prefix */
     gadgetEndPrefix?: string;
+    /** Custom gadget argument prefix for block format parameters */
+    gadgetArgPrefix?: string;
     /** Initial messages */
     initialMessages?: Array<{
         role: "system" | "user" | "assistant";
@@ -1619,9 +1560,9 @@ declare class Agent {
     private readonly hooks;
     private readonly conversation;
     private readonly registry;
-    private readonly parameterFormat;
     private readonly gadgetStartPrefix?;
     private readonly gadgetEndPrefix?;
+    private readonly gadgetArgPrefix?;
     private readonly onHumanInputRequired?;
     private readonly textOnlyHandler;
     private readonly textWithGadgetsHandler?;
@@ -1750,9 +1691,9 @@ declare class AgentBuilder {
     private gadgets;
     private initialMessages;
     private onHumanInputRequired?;
-    private parameterFormat?;
     private gadgetStartPrefix?;
     private gadgetEndPrefix?;
+    private gadgetArgPrefix?;
     private textOnlyHandler?;
     private textWithGadgetsHandler?;
     private stopOnGadgetError?;
@@ -1897,18 +1838,6 @@ declare class AgentBuilder {
      * ```
      */
     onHumanInput(handler: (question: string) => Promise<string>): this;
-    /**
-     * Set the parameter format for gadget calls.
-     *
-     * @param format - Parameter format ("json" or "xml")
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withParameterFormat("xml")
-     * ```
-     */
-    withParameterFormat(format: ParameterFormat): this;
     /**
      * Set custom gadget marker prefix.
      *
@@ -1933,6 +1862,18 @@ declare class AgentBuilder {
      * ```
      */
     withGadgetEndPrefix(suffix: string): this;
+    /**
+     * Set custom argument prefix for block format parameters.
+     *
+     * @param prefix - Custom prefix for argument markers (default: "!!!ARG:")
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withGadgetArgPrefix("<<ARG>>")
+     * ```
+     */
+    withGadgetArgPrefix(prefix: string): this;
     /**
      * Set the text-only handler strategy.
      *
@@ -2113,10 +2054,9 @@ declare class AgentBuilder {
      */
     withSyntheticGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): this;
     /**
-     * Format parameters for synthetic gadget calls.
-     * Uses heredoc for multiline string values.
+     * Format parameters as block format with JSON Pointer paths.
      */
-    private formatSyntheticParameters;
+    private formatBlockParameters;
     /**
      * Build and create the agent with the given user prompt.
      * Returns the Agent instance ready to run.
@@ -2772,4 +2712,4 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
-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 };
+export { type MessageInterceptorContext 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 ParsedGadgetCall as P, type BeforeLLMCallAction as Q, type ChunkInterceptorContext as R, type StreamEvent as S, type TokenUsage 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, 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, type GadgetClass as aq, type GadgetOrClass as ar, type TextOnlyAction as as, type TextOnlyContext as at, type TextOnlyCustomHandler as au, type TextOnlyGadgetConfig as av, type TextOnlyHandler as aw, type TextOnlyStrategy as ax, 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 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 };