llmist 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,1101 @@
+import { ZodType, ZodTypeAny } from 'zod';
+export { z } from 'zod';
+import { A as AgentHooks, L as LLMMessage, P as ParameterFormat, S as StreamEvent, G as GadgetRegistry, o as LLMStreamChunk, B as BaseGadget, p as ParsedGadgetCall, q as GadgetExecutionResult, r as ProviderAdapter, s as ModelDescriptor, t as ModelSpec, u as LLMGenerationOptions, v as LLMStream } from './mock-stream-D4erlo7B.js';
+export { C as AfterGadgetExecutionAction, D as AfterGadgetExecutionControllerContext, F as AfterLLMCallAction, I as AfterLLMCallControllerContext, J as AfterLLMErrorAction, w as AgentBuilder, K as AgentOptions, N as BeforeGadgetExecutionAction, O as BeforeLLMCallAction, Q as ChunkInterceptorContext, R as Controllers, a9 as CostEstimate, ak as DEFAULT_PROMPTS, E as EventHandlers, ar as GadgetClass, T as GadgetExecutionControllerContext, as as GadgetOrClass, U as GadgetParameterInterceptorContext, V as GadgetResultInterceptorContext, H as HistoryMessage, W as Interceptors, X as LLMCallControllerContext, Y as LLMErrorControllerContext, a8 as LLMMessageBuilder, a7 as LLMRole, a6 as LLMist, a5 as LLMistOptions, Z as MessageInterceptorContext, a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, aa as ModelFeatures, ag as ModelIdentifierParser, ab as ModelLimits, ac as ModelPricing, ad as ModelRegistry, _ as ObserveChunkContext, $ as ObserveGadgetCompleteContext, a0 as ObserveGadgetStartContext, a1 as ObserveLLMCallContext, a2 as ObserveLLMCompleteContext, a3 as ObserveLLMErrorContext, a4 as Observers, ah as PromptConfig, ai as PromptContext, aj as PromptTemplate, ae as ProviderIdentifier, an as QuickOptions, aq as StreamParser, at as TextOnlyAction, au as TextOnlyContext, av as TextOnlyCustomHandler, aw as TextOnlyGadgetConfig, ax as TextOnlyHandler, ay as TextOnlyStrategy, af as TokenUsage, x as collectEvents, y as collectText, ao as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, al as resolvePromptTemplate, am as resolveRulesTemplate, z as runWithHandlers, ap as stream } from './mock-stream-D4erlo7B.js';
+import { Logger, ILogObj } from 'tslog';
+import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
+import OpenAI from 'openai';
+import { ChatCompletionChunk } from 'openai/resources/chat/completions';
+
+/**
+ * Common hook presets for logging, timing, and monitoring.
+ *
+ * @example
+ * ```typescript
+ * import { HookPresets } from 'llmist/hooks';
+ *
+ * const agent = LLMist.createAgent()
+ *   .withHooks(HookPresets.logging())
+ *   .ask("...");
+ *
+ * // Or combine multiple presets
+ * const agent = LLMist.createAgent()
+ *   .withHooks(HookPresets.merge(
+ *     HookPresets.logging({ verbose: true }),
+ *     HookPresets.timing(),
+ *     HookPresets.tokenTracking()
+ *   ))
+ *   .ask("...");
+ * ```
+ */
+
+/**
+ * Options for logging preset.
+ */
+interface LoggingOptions {
+    /** Include verbose details like parameters and results */
+    verbose?: boolean;
+}
+/**
+ * Common hook presets.
+ */
+declare class HookPresets {
+    /**
+     * Preset: Basic logging of all events.
+     *
+     * Logs LLM calls and gadget executions to console.
+     *
+     * @param options - Logging options
+     * @returns Hook configuration
+     *
+     * @example
+     * ```typescript
+     * .withHooks(HookPresets.logging())
+     * .withHooks(HookPresets.logging({ verbose: true }))
+     * ```
+     */
+    static logging(options?: LoggingOptions): AgentHooks;
+    /**
+     * Preset: Performance timing for all operations.
+     *
+     * Measures and logs execution time for LLM calls and gadgets.
+     *
+     * @returns Hook configuration
+     *
+     * @example
+     * ```typescript
+     * .withHooks(HookPresets.timing())
+     * ```
+     */
+    static timing(): AgentHooks;
+    /**
+     * Preset: Token usage tracking.
+     *
+     * Tracks and logs cumulative token usage across all LLM calls.
+     *
+     * @returns Hook configuration
+     *
+     * @example
+     * ```typescript
+     * .withHooks(HookPresets.tokenTracking())
+     * ```
+     */
+    static tokenTracking(): AgentHooks;
+    /**
+     * Preset: Error logging.
+     *
+     * Logs detailed error information for debugging.
+     *
+     * @returns Hook configuration
+     *
+     * @example
+     * ```typescript
+     * .withHooks(HookPresets.errorLogging())
+     * ```
+     */
+    static errorLogging(): AgentHooks;
+    /**
+     * Preset: Silent (no output).
+     *
+     * Useful for testing or when you want complete control.
+     *
+     * @returns Empty hook configuration
+     *
+     * @example
+     * ```typescript
+     * .withHooks(HookPresets.silent())
+     * ```
+     */
+    static silent(): AgentHooks;
+    /**
+     * Merge multiple hook configurations.
+     *
+     * Combines hook presets or custom configurations into a single object.
+     * When multiple hooks target the same lifecycle event, they are composed
+     * to run sequentially (all handlers will execute).
+     *
+     * @param hookSets - Array of hook configurations to merge
+     * @returns Merged hook configuration with composed handlers
+     *
+     * @example
+     * ```typescript
+     * .withHooks(HookPresets.merge(
+     *   HookPresets.logging({ verbose: true }),
+     *   HookPresets.timing(),
+     *   HookPresets.tokenTracking(),
+     *   {
+     *     // Custom hook
+     *     observers: {
+     *       onLLMCallComplete: async (ctx) => {
+     *         saveToDatabase(ctx);
+     *       }
+     *     }
+     *   }
+     * ))
+     * // All onLLMCallComplete handlers from logging, timing, tokenTracking,
+     * // and the custom hook will execute in order
+     * ```
+     */
+    static merge(...hookSets: AgentHooks[]): AgentHooks;
+    /**
+     * Preset: Complete monitoring suite.
+     *
+     * Combines logging, timing, and token tracking.
+     *
+     * @param options - Options for monitoring
+     * @returns Merged hook configuration
+     *
+     * @example
+     * ```typescript
+     * .withHooks(HookPresets.monitoring())
+     * .withHooks(HookPresets.monitoring({ verbose: true }))
+     * ```
+     */
+    static monitoring(options?: LoggingOptions): AgentHooks;
+}
+
+/**
+ * Core interfaces for the Agent architecture.
+ * These interfaces define the contracts for the composable services that make up the agent system.
+ */
+
+/**
+ * Manages the conversation history and message building.
+ * This interface abstracts conversation state management from the orchestration logic.
+ */
+interface IConversationManager {
+    /**
+     * Adds a user message to the conversation.
+     */
+    addUserMessage(content: string): void;
+    /**
+     * Adds an assistant message to the conversation.
+     */
+    addAssistantMessage(content: string): void;
+    /**
+     * Adds a gadget call and its result to the conversation.
+     */
+    addGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): void;
+    /**
+     * Gets the complete conversation history including base messages (system prompts, gadget instructions).
+     */
+    getMessages(): LLMMessage[];
+}
+
+/**
+ * ConversationManager handles conversation state and message building.
+ * Extracted from AgentLoop to follow Single Responsibility Principle.
+ */
+
+/**
+ * Default implementation of IConversationManager.
+ * Manages conversation history by building on top of base messages (system prompt, gadget instructions).
+ */
+declare class ConversationManager implements IConversationManager {
+    private readonly baseMessages;
+    private readonly initialMessages;
+    private readonly historyBuilder;
+    private readonly parameterFormat;
+    constructor(baseMessages: LLMMessage[], initialMessages: LLMMessage[], parameterFormat?: ParameterFormat);
+    addUserMessage(content: string): void;
+    addAssistantMessage(content: string): void;
+    addGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): void;
+    getMessages(): LLMMessage[];
+}
+
+/**
+ * StreamProcessor: The heart of the new hooks architecture.
+ *
+ * Replaces the complex wiring between Agent, ResponseProcessor, and GadgetRuntime.
+ * Owns ALL stream processing and hook coordination with a clean, predictable flow.
+ */
+
+/**
+ * Configuration for the StreamProcessor.
+ */
+interface StreamProcessorOptions {
+    /** Current iteration number */
+    iteration: number;
+    /** Gadget registry for execution */
+    registry: GadgetRegistry;
+    /** Parameter format for parsing */
+    parameterFormat: ParameterFormat;
+    /** Custom gadget start prefix */
+    gadgetStartPrefix?: string;
+    /** Custom gadget end prefix */
+    gadgetEndPrefix?: string;
+    /** Hooks for lifecycle events */
+    hooks?: AgentHooks;
+    /** Logger instance */
+    logger?: Logger<ILogObj>;
+    /** Callback for human input */
+    onHumanInputRequired?: (question: string) => Promise<string>;
+    /** Whether to stop on gadget errors */
+    stopOnGadgetError?: boolean;
+    /** Custom error continuation logic */
+    shouldContinueAfterError?: (context: {
+        error: string;
+        gadgetName: string;
+        errorType: "parse" | "validation" | "execution";
+        parameters?: Record<string, unknown>;
+    }) => boolean | Promise<boolean>;
+    /** Default gadget timeout */
+    defaultGadgetTimeoutMs?: number;
+}
+/**
+ * Result of stream processing.
+ */
+interface StreamProcessingResult {
+    /** All emitted events */
+    outputs: StreamEvent[];
+    /** Whether the loop should break */
+    shouldBreakLoop: boolean;
+    /** Whether any gadgets were executed */
+    didExecuteGadgets: boolean;
+    /** LLM finish reason */
+    finishReason: string | null;
+    /** Token usage */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    /** The raw accumulated response text */
+    rawResponse: string;
+    /** The final message (after interceptors) */
+    finalMessage: string;
+}
+/**
+ * StreamProcessor: Coordinates all stream processing and hook execution.
+ *
+ * Execution order:
+ * 1. Raw chunk arrives from LLM
+ * 2. Interceptor: interceptRawChunk (transform raw text)
+ * 3. Observer: onStreamChunk (logging)
+ * 4. Parse for gadgets
+ * 5. If gadget found:
+ *    a. Interceptor: interceptGadgetParameters (transform params)
+ *    b. Controller: beforeGadgetExecution (can skip)
+ *    c. Observer: onGadgetExecutionStart
+ *    d. Execute gadget
+ *    e. Interceptor: interceptGadgetResult (transform result)
+ *    f. Controller: afterGadgetExecution (can provide fallback)
+ *    g. Observer: onGadgetExecutionComplete
+ * 6. If text chunk:
+ *    a. Interceptor: interceptTextChunk (transform display text)
+ *    b. Yield to user
+ * 7. Stream complete
+ * 8. Interceptor: interceptAssistantMessage (transform final message)
+ */
+declare class StreamProcessor {
+    private readonly iteration;
+    private readonly registry;
+    private readonly hooks;
+    private readonly logger;
+    private readonly parser;
+    private readonly executor;
+    private readonly stopOnGadgetError;
+    private readonly shouldContinueAfterError?;
+    private accumulatedText;
+    private shouldStopExecution;
+    private observerFailureCount;
+    constructor(options: StreamProcessorOptions);
+    /**
+     * Process an LLM stream and return structured results.
+     */
+    process(stream: AsyncIterable<LLMStreamChunk>): Promise<StreamProcessingResult>;
+    /**
+     * Process a single parsed event (text or gadget call).
+     */
+    private processEvent;
+    /**
+     * Process a text event through interceptors.
+     */
+    private processTextEvent;
+    /**
+     * Process a gadget call through the full lifecycle.
+     */
+    private processGadgetCall;
+    /**
+     * Safely execute an observer, catching and logging any errors.
+     * Observers are non-critical, so errors are logged but don't crash the system.
+     */
+    private safeObserve;
+    /**
+     * Execute multiple observers in parallel.
+     * All observers run concurrently and failures are tracked but don't crash.
+     */
+    private runObserversInParallel;
+    /**
+     * Check if execution should continue after an error.
+     *
+     * Returns true if we should continue processing subsequent gadgets, false if we should stop.
+     *
+     * Logic:
+     * - If custom shouldContinueAfterError is provided, use it
+     * - Otherwise, use stopOnGadgetError config:
+     *   - stopOnGadgetError=true → return false (stop execution)
+     *   - stopOnGadgetError=false → return true (continue execution)
+     */
+    private checkContinueAfterError;
+    /**
+     * Determine the type of error from a gadget execution.
+     */
+    private determineErrorType;
+}
+
+/**
+ * Model shortcuts and aliases for more expressive DX.
+ *
+ * This module provides convenient aliases for common model names,
+ * allowing developers to use short, memorable names instead of
+ * verbose provider:model-id formats.
+ *
+ * @example
+ * ```typescript
+ * // Instead of:
+ * model: "openai:gpt-5-nano"
+ *
+ * // You can use:
+ * model: "gpt5-nano"
+ * // or even:
+ * model: "gpt-5-nano" // Auto-detects provider
+ * ```
+ */
+/**
+ * Map of common model aliases to their full provider:model-id format.
+ */
+declare const MODEL_ALIASES: Record<string, string>;
+/**
+ * Options for resolveModel function.
+ */
+interface ResolveModelOptions {
+    /**
+     * If true, throw an error for unknown model names instead of falling back to OpenAI.
+     * This helps catch typos like "gp4" instead of "gpt4".
+     * Default: false
+     */
+    strict?: boolean;
+    /**
+     * If true, suppress warnings for unknown model names.
+     * Default: false
+     */
+    silent?: boolean;
+}
+/**
+ * Resolves a model name to its full provider:model format.
+ *
+ * Supports:
+ * - Direct aliases: 'gpt5', 'sonnet', 'flash'
+ * - Auto-detection: 'gpt-5-nano' → 'openai:gpt-5-nano'
+ * - Pass-through: 'openai:gpt-5' → 'openai:gpt-5'
+ *
+ * Warnings:
+ * - Logs a warning when an unknown model name falls back to OpenAI
+ * - Use { strict: true } to throw an error instead
+ * - Use { silent: true } to suppress warnings
+ *
+ * @param model - Model name or alias
+ * @param options - Resolution options
+ * @returns Full provider:model-id string
+ *
+ * @example
+ * ```typescript
+ * resolveModel('gpt5')              // → 'openai:gpt-5'
+ * resolveModel('sonnet')            // → 'anthropic:claude-3-5-sonnet-latest'
+ * resolveModel('gpt-5-nano')        // → 'openai:gpt-5-nano'
+ * resolveModel('openai:gpt-5')      // → 'openai:gpt-5' (passthrough)
+ * resolveModel('claude-3-5-sonnet') // → 'anthropic:claude-3-5-sonnet'
+ *
+ * // Typo detection
+ * resolveModel('gp5')  // ⚠️ Warning: Unknown model 'gp5', falling back to 'openai:gp5'
+ *
+ * // Strict mode (throws on typos)
+ * resolveModel('gp5', { strict: true })  // ❌ Error: Unknown model 'gp5'
+ * ```
+ */
+declare function resolveModel(model: string, options?: ResolveModelOptions): string;
+/**
+ * Check if a model string is already in provider:model format.
+ *
+ * @param model - Model string to check
+ * @returns True if the model has a provider prefix
+ *
+ * @example
+ * ```typescript
+ * hasProviderPrefix('openai:gpt-4o')    // → true
+ * hasProviderPrefix('gpt4')              // → false
+ * hasProviderPrefix('claude-3-5-sonnet') // → false
+ * ```
+ */
+declare function hasProviderPrefix(model: string): boolean;
+/**
+ * Extract the provider from a full model string.
+ *
+ * @param model - Full model string (provider:model-id)
+ * @returns Provider name, or undefined if no prefix
+ *
+ * @example
+ * ```typescript
+ * getProvider('openai:gpt-4o')     // → 'openai'
+ * getProvider('anthropic:claude')  // → 'anthropic'
+ * getProvider('gpt4')              // → undefined
+ * ```
+ */
+declare function getProvider(model: string): string | undefined;
+/**
+ * Extract the model ID from a full model string.
+ *
+ * @param model - Full model string (provider:model-id)
+ * @returns Model ID, or the original string if no prefix
+ *
+ * @example
+ * ```typescript
+ * getModelId('openai:gpt-4o')      // → 'gpt-4o'
+ * getModelId('anthropic:claude')   // → 'claude'
+ * getModelId('gpt4')               // → 'gpt4'
+ * ```
+ */
+declare function getModelId(model: string): string;
+
+/**
+ * Function-based gadget creation helper.
+ *
+ * For simple gadgets, use createGadget() instead of defining a class.
+ * Parameters are automatically typed from the Zod schema.
+ *
+ * @example
+ * ```typescript
+ * const calculator = createGadget({
+ *   description: "Performs arithmetic operations",
+ *   schema: z.object({
+ *     operation: z.enum(["add", "subtract"]),
+ *     a: z.number(),
+ *     b: z.number(),
+ *   }),
+ *   execute: ({ operation, a, b }) => {
+ *     // Automatically typed!
+ *     return operation === "add" ? String(a + b) : String(a - b);
+ *   },
+ * });
+ * ```
+ */
+
+/**
+ * Infer the TypeScript type from a Zod schema.
+ */
+type InferSchema$1<T> = T extends ZodType<infer U> ? U : never;
+/**
+ * Configuration for creating a function-based gadget.
+ */
+interface CreateGadgetConfig<TSchema extends ZodType> {
+    /** Optional custom name (defaults to "FunctionGadget") */
+    name?: string;
+    /** Human-readable description of what the gadget does */
+    description: string;
+    /** Zod schema for parameter validation */
+    schema: TSchema;
+    /** Execution function with typed parameters */
+    execute: (params: InferSchema$1<TSchema>) => string | Promise<string>;
+    /** Optional timeout in milliseconds */
+    timeoutMs?: number;
+}
+/**
+ * Creates a gadget from a function (simpler than class-based approach).
+ *
+ * This is perfect for simple gadgets where you don't need the full
+ * power of a class. Parameters are automatically typed from the schema.
+ *
+ * @param config - Configuration with execute function and schema
+ * @returns Gadget instance ready to be registered
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { createGadget } from 'llmist';
+ *
+ * // Simple calculator gadget
+ * const calculator = createGadget({
+ *   description: "Performs arithmetic operations",
+ *   schema: z.object({
+ *     operation: z.enum(["add", "subtract", "multiply", "divide"]),
+ *     a: z.number().describe("First number"),
+ *     b: z.number().describe("Second number"),
+ *   }),
+ *   execute: ({ operation, a, b }) => {
+ *     // Parameters are automatically typed!
+ *     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);
+ *     }
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Async gadget with custom name and timeout
+ * const weather = createGadget({
+ *   name: "weather",
+ *   description: "Fetches current weather for a city",
+ *   schema: z.object({
+ *     city: z.string().min(1).describe("City name"),
+ *   }),
+ *   timeoutMs: 10000,
+ *   execute: async ({ city }) => {
+ *     const response = await fetch(`https://api.weather.com/${city}`);
+ *     const data = await response.json();
+ *     return `Weather in ${city}: ${data.description}, ${data.temp}°C`;
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use with agent
+ * const agent = LLMist.createAgent()
+ *   .withGadgets(calculator, weather)
+ *   .ask("What's the weather in Paris and what's 10 + 5?");
+ * ```
+ */
+declare function createGadget<TSchema extends ZodType>(config: CreateGadgetConfig<TSchema>): BaseGadget;
+
+/**
+ * Exception that gadgets can throw to signal the agent loop should terminate.
+ *
+ * When a gadget throws this exception, the agent loop will:
+ * 1. Complete the current iteration
+ * 2. Return the exception message as the gadget's result
+ * 3. Exit the loop instead of continuing to the next iteration
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * class FinishGadget extends Gadget({
+ *   name: 'Finish',
+ *   description: 'Signals task completion',
+ *   schema: z.object({
+ *     message: z.string().optional(),
+ *   }),
+ * }) {
+ *   execute(params: this['params']): string {
+ *     const message = params.message || 'Task completed';
+ *     throw new BreakLoopException(message);
+ *   }
+ * }
+ * ```
+ */
+declare class BreakLoopException extends Error {
+    constructor(message?: string);
+}
+/**
+ * Exception that gadgets can throw to request human input during execution.
+ *
+ * When a gadget throws this exception, the agent loop will:
+ * 1. Pause execution and wait for human input
+ * 2. If `onHumanInputRequired` callback is provided, call it and await the answer
+ * 3. Return the user's answer as the gadget's result
+ * 4. Continue the loop with the answer added to conversation history
+ *
+ * If no callback is provided, the loop will yield a `human_input_required` event
+ * and the caller must handle it externally.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * class AskUserGadget extends Gadget({
+ *   name: 'AskUser',
+ *   description: 'Ask the user a question and get their answer',
+ *   schema: z.object({
+ *     question: z.string().min(1, 'Question is required'),
+ *   }),
+ * }) {
+ *   execute(params: this['params']): string {
+ *     throw new HumanInputException(params.question);
+ *   }
+ * }
+ * ```
+ */
+declare class HumanInputException extends Error {
+    readonly question: string;
+    constructor(question: string);
+}
+
+declare class GadgetExecutor {
+    private readonly registry;
+    private readonly onHumanInputRequired?;
+    private readonly defaultGadgetTimeoutMs?;
+    private readonly logger;
+    constructor(registry: GadgetRegistry, onHumanInputRequired?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined);
+    /**
+     * Creates a promise that rejects with a TimeoutException after the specified timeout.
+     */
+    private createTimeoutPromise;
+    execute(call: ParsedGadgetCall): Promise<GadgetExecutionResult>;
+    executeAll(calls: ParsedGadgetCall[]): Promise<GadgetExecutionResult[]>;
+}
+
+/**
+ * Infer the TypeScript type from a Zod schema.
+ */
+type InferSchema<T> = T extends ZodType<infer U> ? U : never;
+/**
+ * Configuration for creating a typed gadget.
+ */
+interface GadgetConfig<TSchema extends ZodType> {
+    /** Human-readable description of what the gadget does */
+    description: string;
+    /** Zod schema for parameter validation */
+    schema: TSchema;
+    /** Optional custom name (defaults to class name) */
+    name?: string;
+    /** Optional timeout in milliseconds */
+    timeoutMs?: number;
+}
+/**
+ * Factory function to create a typed gadget base class.
+ *
+ * The returned class automatically infers parameter types from the Zod schema,
+ * eliminating the need for manual type assertions in the execute method.
+ *
+ * @param config - Configuration with description and schema
+ * @returns Base class to extend with typed execute method
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { Gadget } from 'llmist';
+ *
+ * class Calculator extends Gadget({
+ *   description: "Performs arithmetic operations",
+ *   schema: z.object({
+ *     operation: z.enum(["add", "subtract", "multiply", "divide"]),
+ *     a: z.number().describe("First number"),
+ *     b: z.number().describe("Second number"),
+ *   }),
+ * }) {
+ *   execute(params: this['params']): string {
+ *     // params is automatically typed as:
+ *     // { operation: "add" | "subtract" | "multiply" | "divide"; a: number; b: number }
+ *     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);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With async execution
+ * class WeatherGadget extends Gadget({
+ *   description: "Fetches weather for a city",
+ *   schema: z.object({
+ *     city: z.string().min(1).describe("City name"),
+ *   }),
+ *   timeoutMs: 10000,
+ * }) {
+ *   async execute(params: this['params']): Promise<string> {
+ *     const { city } = params; // Automatically typed as { city: string }
+ *     const weather = await fetchWeather(city);
+ *     return `Weather in ${city}: ${weather}`;
+ *   }
+ * }
+ * ```
+ */
+declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>): {
+    new (): {
+        description: string;
+        parameterSchema: TSchema;
+        name: string | undefined;
+        timeoutMs: number | undefined;
+        /**
+         * Type helper property for accessing inferred parameter type.
+         * This is used in the execute method signature: `execute(params: this['params'])`
+         *
+         * Note: This is just for type inference - the actual params in execute()
+         * will be Record<string, unknown> which you can safely cast to this['params']
+         */
+        readonly params: InferSchema<TSchema>;
+        /**
+         * Execute the gadget. Subclasses should cast params to this['params'].
+         *
+         * @param params - Validated parameters from the LLM
+         * @returns Result as a string (or Promise<string> for async gadgets)
+         *
+         * @example
+         * ```typescript
+         * execute(params: Record<string, unknown>): string {
+         *   const typed = params as this['params'];
+         *   // Now 'typed' is fully typed!
+         *   return String(typed.a + typed.b);
+         * }
+         * ```
+         */
+        execute(params: Record<string, unknown>): string | Promise<string>;
+        get instruction(): string;
+        getInstruction(format?: ParameterFormat): string;
+    } & {
+        params: InferSchema<TSchema>;
+    };
+};
+
+/**
+ * Validation utilities for gadget parameters.
+ *
+ * Provides standalone validation with Zod schema support, including
+ * default application and formatted error output.
+ *
+ * @module gadgets/validation
+ */
+
+/**
+ * Individual validation issue with path and message.
+ */
+interface ValidationIssue {
+    /** Dot-separated path to the invalid field (e.g., "user.email") */
+    path: string;
+    /** Human-readable error message */
+    message: string;
+}
+/**
+ * Result of parameter validation.
+ * Discriminated union based on `success` field.
+ */
+type ValidationResult<T = Record<string, unknown>> = {
+    success: true;
+    /** Validated and transformed data with defaults applied */
+    data: T;
+} | {
+    success: false;
+    /** Formatted error message */
+    error: string;
+    /** Individual validation issues */
+    issues: ValidationIssue[];
+};
+/**
+ * Validate parameters against a Zod schema and apply defaults/transformations.
+ *
+ * This replicates the validation behavior from GadgetExecutor, making it
+ * available for direct use in tests and other contexts.
+ *
+ * @param schema - Zod schema to validate against
+ * @param params - Raw parameters to validate
+ * @returns ValidationResult with either validated data or error details
+ *
+ * @example
+ * ```typescript
+ * import { validateAndApplyDefaults } from 'llmist';
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({
+ *   delay: z.number().default(100),
+ *   retries: z.number().int().min(0).default(3),
+ * });
+ *
+ * const result = validateAndApplyDefaults(schema, { delay: 50 });
+ * if (result.success) {
+ *   console.log(result.data); // { delay: 50, retries: 3 }
+ * }
+ * ```
+ */
+declare function validateAndApplyDefaults<T = Record<string, unknown>>(schema: ZodTypeAny, params: Record<string, unknown>): ValidationResult<T>;
+/**
+ * Validate gadget parameters using the gadget's schema.
+ *
+ * Convenience wrapper that extracts the schema from a gadget instance.
+ * If the gadget has no schema, validation always succeeds with the
+ * original parameters.
+ *
+ * @param gadget - Gadget instance with optional parameterSchema
+ * @param params - Raw parameters to validate
+ * @returns ValidationResult with either validated data or error details
+ *
+ * @example
+ * ```typescript
+ * import { validateGadgetParams, createGadget } from 'llmist';
+ * import { z } from 'zod';
+ *
+ * const calculator = createGadget({
+ *   description: 'Add numbers',
+ *   schema: z.object({
+ *     a: z.number(),
+ *     b: z.number().default(0),
+ *   }),
+ *   execute: ({ a, b }) => String(a + b),
+ * });
+ *
+ * const result = validateGadgetParams(calculator, { a: 5 });
+ * if (result.success) {
+ *   console.log(result.data); // { a: 5, b: 0 }
+ * }
+ * ```
+ */
+declare function validateGadgetParams(gadget: BaseGadget, params: Record<string, unknown>): ValidationResult;
+
+/**
+ * Logger configuration options for the library.
+ */
+interface LoggerOptions {
+    /**
+     * Log level: 0=silly, 1=trace, 2=debug, 3=info, 4=warn, 5=error, 6=fatal
+     * @default 4 (warn)
+     */
+    minLevel?: number;
+    /**
+     * Output type: 'pretty' for development, 'json' for production
+     * @default 'pretty'
+     */
+    type?: "pretty" | "json" | "hidden";
+    /**
+     * Logger name (appears in logs)
+     */
+    name?: string;
+}
+/**
+ * Create a new logger instance for the library.
+ *
+ * @param options - Logger configuration options
+ * @returns Configured Logger instance
+ *
+ * @example
+ * ```typescript
+ * // Development logger with pretty output
+ * const logger = createLogger({ type: 'pretty', minLevel: 2 });
+ *
+ * // Production logger with JSON output
+ * const logger = createLogger({ type: 'json', minLevel: 3 });
+ *
+ * // Silent logger for tests
+ * const logger = createLogger({ type: 'hidden' });
+ * ```
+ */
+declare function createLogger(options?: LoggerOptions): Logger<ILogObj>;
+/**
+ * Default logger instance for the library.
+ * Users can replace this with their own configured logger.
+ */
+declare const defaultLogger: Logger<ILogObj>;
+
+/**
+ * Base Provider Adapter
+ *
+ * Abstract base class for provider adapters that implements the Template Method pattern.
+ * This class defines the skeleton of the streaming algorithm, leaving provider-specific
+ * details to be implemented by concrete subclasses.
+ *
+ * The streaming workflow consists of four main steps:
+ * 1. Prepare messages (optional transformation for provider-specific requirements)
+ * 2. Build the request payload (provider-specific formatting)
+ * 3. Execute the stream request (call the provider's SDK)
+ * 4. Wrap the stream (transform provider-specific chunks into universal format)
+ */
+
+declare abstract class BaseProviderAdapter implements ProviderAdapter {
+    protected readonly client: unknown;
+    abstract readonly providerId: string;
+    constructor(client: unknown);
+    abstract supports(descriptor: ModelDescriptor): boolean;
+    /**
+     * Optionally provide model specifications for this provider.
+     * This allows the model registry to discover available models and their capabilities.
+     */
+    getModelSpecs?(): ModelSpec[];
+    /**
+     * Template method that defines the skeleton of the streaming algorithm.
+     * This orchestrates the four-step process without dictating provider-specific details.
+     */
+    stream(options: LLMGenerationOptions, descriptor: ModelDescriptor, spec?: ModelSpec): LLMStream;
+    /**
+     * Prepare messages for the request.
+     * Default implementation returns messages unchanged.
+     * Override this to implement provider-specific message transformations
+     * (e.g., Gemini's consecutive message merging, Anthropic's system message extraction).
+     *
+     * @param messages - The input messages
+     * @returns Prepared messages
+     */
+    protected prepareMessages(messages: LLMMessage[]): LLMMessage[];
+    /**
+     * Build the provider-specific request payload.
+     * This method must be implemented by each concrete provider.
+     *
+     * @param options - The generation options
+     * @param descriptor - The model descriptor
+     * @param spec - Optional model specification with metadata
+     * @param messages - The prepared messages
+     * @returns Provider-specific payload ready for the API call
+     */
+    protected abstract buildRequestPayload(options: LLMGenerationOptions, descriptor: ModelDescriptor, spec: ModelSpec | undefined, messages: LLMMessage[]): unknown;
+    /**
+     * Execute the stream request using the provider's SDK.
+     * This method must be implemented by each concrete provider.
+     *
+     * @param payload - The provider-specific payload
+     * @returns An async iterable of provider-specific chunks
+     */
+    protected abstract executeStreamRequest(payload: unknown): Promise<AsyncIterable<unknown>>;
+    /**
+     * Wrap the provider-specific stream into the universal LLMStream format.
+     * This method must be implemented by each concrete provider.
+     *
+     * @param rawStream - The provider-specific stream
+     * @returns Universal LLMStream
+     */
+    protected abstract wrapStream(rawStream: AsyncIterable<unknown>): LLMStream;
+}
+
+declare class AnthropicMessagesProvider extends BaseProviderAdapter {
+    readonly providerId: "anthropic";
+    supports(descriptor: ModelDescriptor): boolean;
+    getModelSpecs(): ModelSpec[];
+    protected buildRequestPayload(options: LLMGenerationOptions, descriptor: ModelDescriptor, spec: ModelSpec | undefined, messages: LLMMessage[]): MessageCreateParamsStreaming;
+    protected executeStreamRequest(payload: MessageCreateParamsStreaming): Promise<AsyncIterable<MessageStreamEvent>>;
+    protected wrapStream(iterable: AsyncIterable<unknown>): LLMStream;
+    /**
+     * Count tokens in messages using Anthropic's native token counting API.
+     *
+     * This method provides accurate token estimation for Anthropic models by:
+     * - Using the native messages.countTokens() API
+     * - Properly handling system messages and conversation structure
+     * - Transforming messages to Anthropic's expected format
+     *
+     * @param messages - The messages to count tokens for
+     * @param descriptor - Model descriptor containing the model name
+     * @param _spec - Optional model specification (currently unused)
+     * @returns Promise resolving to the estimated input token count
+     *
+     * @throws Never throws - falls back to character-based estimation (4 chars/token) on error
+     *
+     * @example
+     * ```typescript
+     * const count = await provider.countTokens(
+     *   [{ role: "user", content: "Hello!" }],
+     *   { provider: "anthropic", name: "claude-3-5-sonnet-20241022" }
+     * );
+     * ```
+     */
+    countTokens(messages: LLMMessage[], descriptor: ModelDescriptor, _spec?: ModelSpec): Promise<number>;
+}
+declare function createAnthropicProviderFromEnv(): AnthropicMessagesProvider | null;
+
+declare function discoverProviderAdapters(): ProviderAdapter[];
+
+type GeminiChunk = {
+    text?: () => string;
+    candidates?: Array<{
+        content?: {
+            parts?: Array<{
+                text?: string;
+            }>;
+        };
+        finishReason?: string;
+    }>;
+    usageMetadata?: {
+        promptTokenCount?: number;
+        candidatesTokenCount?: number;
+        totalTokenCount?: number;
+    };
+};
+declare class GeminiGenerativeProvider extends BaseProviderAdapter {
+    readonly providerId: "gemini";
+    supports(descriptor: ModelDescriptor): boolean;
+    getModelSpecs(): ModelSpec[];
+    protected buildRequestPayload(options: LLMGenerationOptions, descriptor: ModelDescriptor, _spec: ModelSpec | undefined, messages: LLMMessage[]): {
+        model: string;
+        contents: Array<{
+            role: string;
+            parts: Array<{
+                text: string;
+            }>;
+        }>;
+        config: Record<string, unknown>;
+    };
+    protected executeStreamRequest(payload: {
+        model: string;
+        contents: Array<{
+            role: string;
+            parts: Array<{
+                text: string;
+            }>;
+        }>;
+        config: Record<string, unknown>;
+    }): Promise<AsyncIterable<GeminiChunk>>;
+    private extractSystemAndContents;
+    private mergeConsecutiveMessages;
+    private convertContentsForNewSDK;
+    private buildGenerationConfig;
+    protected wrapStream(iterable: AsyncIterable<unknown>): LLMStream;
+    private extractText;
+    private extractFinishReason;
+    private extractUsage;
+    /**
+     * Count tokens in messages using Gemini's native token counting API.
+     *
+     * This method provides accurate token estimation for Gemini models by:
+     * - Using the SDK's countTokens() method
+     * - Properly extracting and handling system instructions
+     * - Transforming messages to Gemini's expected format
+     *
+     * @param messages - The messages to count tokens for
+     * @param descriptor - Model descriptor containing the model name
+     * @param _spec - Optional model specification (currently unused)
+     * @returns Promise resolving to the estimated input token count
+     *
+     * @throws Never throws - falls back to character-based estimation (4 chars/token) on error
+     *
+     * @example
+     * ```typescript
+     * const count = await provider.countTokens(
+     *   [{ role: "user", content: "Hello!" }],
+     *   { provider: "gemini", name: "gemini-1.5-pro" }
+     * );
+     * ```
+     */
+    countTokens(messages: LLMMessage[], descriptor: ModelDescriptor, _spec?: ModelSpec): Promise<number>;
+}
+declare function createGeminiProviderFromEnv(): GeminiGenerativeProvider | null;
+
+declare class OpenAIChatProvider extends BaseProviderAdapter {
+    readonly providerId: "openai";
+    supports(descriptor: ModelDescriptor): boolean;
+    getModelSpecs(): ModelSpec[];
+    protected buildRequestPayload(options: LLMGenerationOptions, descriptor: ModelDescriptor, spec: ModelSpec | undefined, messages: LLMMessage[]): Parameters<OpenAI["chat"]["completions"]["create"]>[0];
+    protected executeStreamRequest(payload: Parameters<OpenAI["chat"]["completions"]["create"]>[0]): Promise<AsyncIterable<ChatCompletionChunk>>;
+    protected wrapStream(iterable: AsyncIterable<unknown>): LLMStream;
+    /**
+     * Count tokens in messages using OpenAI's tiktoken library.
+     *
+     * This method provides accurate token estimation for OpenAI models by:
+     * - Using the model-specific tokenizer encoding
+     * - Accounting for message formatting overhead
+     * - Falling back to gpt-4o encoding for unknown models
+     *
+     * @param messages - The messages to count tokens for
+     * @param descriptor - Model descriptor containing the model name
+     * @param _spec - Optional model specification (currently unused)
+     * @returns Promise resolving to the estimated input token count
+     *
+     * @throws Never throws - falls back to character-based estimation (4 chars/token) on error
+     *
+     * @example
+     * ```typescript
+     * const count = await provider.countTokens(
+     *   [{ role: "user", content: "Hello!" }],
+     *   { provider: "openai", name: "gpt-4" }
+     * );
+     * ```
+     */
+    countTokens(messages: LLMMessage[], descriptor: ModelDescriptor, _spec?: ModelSpec): Promise<number>;
+}
+declare function createOpenAIProviderFromEnv(): OpenAIChatProvider | null;
+
+export { AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, ConversationManager, type CreateGadgetConfig, Gadget, type GadgetConfig, GadgetExecutionResult, GadgetExecutor, GadgetRegistry, GeminiGenerativeProvider, HookPresets, HumanInputException, type IConversationManager, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, ModelDescriptor, ModelSpec, OpenAIChatProvider, ParsedGadgetCall, ProviderAdapter, StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGeminiProviderFromEnv, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, resolveModel, validateAndApplyDefaults, validateGadgetParams };