@flatfile/improv/dist/index.d.ts

A powerful TypeScript library for building AI agents with multi-threaded conversations, tool execution, and event handling capabilities

import { z } from 'zod';
import { EventEmitter2 } from 'eventemitter2';
import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime';
export { Type } from '@google/genai';

/**
 * Abstract base class for all event-emitting classes
 * Provides event forwarding functionality and type-safe event emission
 */
declare abstract class EventSource extends EventEmitter2 implements EventSourceInterface {
    constructor();
    /**
     * Forward all events from a source EventEmitter2 instance
     * Preserves the original event name and merges any additional context
     */
    protected forwardEvents(source: EventSourceInterface, context?: Record<string, any>): void;
    protected debug(message: string, data?: any): void;
    protected error(...args: any[]): void;
}
interface EventSourceInterface {
    on(event: string, listener: (...args: any[]) => void): any;
}

/**
 * Implement a class that represents a message in the thread.
 * - content - the content of the message
 * - json - the json content of the message (if any) - support a number of ways of finding it
 * - role - the role of the message (user, assistant, tool)
 * - toolCalls - the tool calls that were made in the message
 * - toolResults - the results of the tool calls
 * - attachments - array of attachments (documents, images, videos)
 * - cache: boolean - whether the message is cached
 */
type MessageRole = "system" | "user" | "assistant" | "tool";
type AttachmentType = "document" | "image" | "video";
type DocumentFormat = "pdf" | "csv" | "doc" | "docx" | "xls" | "xlsx" | "html" | "txt" | "md";
type ImageFormat = "png" | "jpeg" | "gif" | "webp";
type VideoFormat = "mkv" | "mov" | "mp4" | "webm" | "flv" | "mpeg" | "mpg" | "wmv" | "three_gp";
interface AttachmentSource {
    bytes?: Uint8Array;
    uri?: string;
    bucketOwner?: string;
}
interface BaseAttachment {
    type: AttachmentType;
    source: AttachmentSource;
}
interface DocumentAttachment extends BaseAttachment {
    type: "document";
    format: DocumentFormat;
    name: string;
}
interface ImageAttachment extends BaseAttachment {
    type: "image";
    format: ImageFormat;
}
interface VideoAttachment extends BaseAttachment {
    type: "video";
    format: VideoFormat;
}
type Attachment = DocumentAttachment | ImageAttachment | VideoAttachment;
interface ToolCall {
    name: string;
    toolUseId: string;
    arguments: Record<string, any>;
}
interface Reasoning {
    text: string;
    type: "text";
    signature: string;
}
interface ToolResult {
    name: string;
    toolUseId: string;
    result: any;
    error?: string;
}
declare class Message {
    private _content?;
    private _role;
    private _reasoning;
    private _toolCalls;
    private _toolResults;
    private _attachments;
    private _cache;
    constructor({ content, role, toolCalls, toolResults, attachments, reasoning, cache, }: {
        content?: string | undefined;
        role?: MessageRole;
        reasoning?: Reasoning[];
        toolCalls?: ToolCall[];
        toolResults?: ToolResult[];
        attachments?: Attachment[];
        cache?: boolean;
    });
    get content(): string | undefined;
    get role(): MessageRole;
    get toolCalls(): ToolCall[];
    get toolResults(): ToolResult[];
    get attachments(): Attachment[];
    get cache(): boolean;
    get reasoning(): Reasoning[];
    isToolResponse(): boolean;
    isAssistantMessage(): boolean;
    isUserMessage(): boolean;
    isSystemMessage(): boolean;
    isToolCall(): boolean;
    /**
     * Get attachments of a specific type
     */
    getAttachmentsByType<T extends Attachment>(type: AttachmentType): T[];
    /**
     * Add an attachment to the message
     */
    addAttachment(attachment: Attachment): void;
    /**
     * Remove an attachment from the message
     */
    removeAttachment(index: number): void;
    /**
     * Attempts to parse and return JSON content from the message
     * Supports multiple formats:
     * 1. Direct JSON string
     * 2. JSON within markdown code blocks
     * 3. JSON within specific delimiters
     */
    get json(): any | null;
}

/**
 * Implement a class that represents a tool.
 * - name - the name of the tool
 * - description - the description of the tool
 * - parameters - the parameters of the tool
 * - execute(): Promise<any> - the function that executes the tool
 * - setFollowUp() - add a follow-up message to the tool call
 * - toMessages(): Message[] - convert the tool to a list of messages include tool response messages and any follow-up messages
 */

interface ToolParameter {
    name: string;
    type: "string" | "number" | "boolean" | "object" | "array";
    description: string;
    required?: boolean;
}
interface ToolCallResult {
    success: boolean;
    result: any;
    toolCall: ToolCall;
    error?: string;
}
interface ToolInterface extends EventSourceInterface {
    name: string;
    description: string;
    parameters: z.ZodTypeAny;
    executeTool: (args: any, toolCall: ToolCall) => Promise<any>;
}
declare function makeToolFromInterface(t: ToolInterface): Tool;
interface ToolOptions {
    name: string;
    description: string;
    parameters: z.ZodTypeAny;
    followUpMessage?: string;
    executeFn: (args: Record<string, any>, toolCall: ToolCall) => Promise<any>;
    id?: string;
    trace?: boolean;
    traceMetadata?: Record<string, unknown>;
}
declare class Tool extends EventSource implements ToolInterface {
    readonly id: string;
    followUpMessage?: string;
    name: string;
    description: string;
    parameters: z.ZodTypeAny;
    private readonly executeFn;
    private readonly trace;
    private readonly traceMetadata?;
    constructor(options: ToolOptions);
    /**
     * Get the name of the tool
     */
    getName(): string;
    /**
     * Get the description of the tool
     */
    getDescription(): string;
    /**
     * Get the parameters of the tool
     */
    getParameters(): z.ZodTypeAny;
    /**
     * Execute the tool with the given arguments
     */
    executeTool(args: any, toolCall: ToolCall): Promise<ToolCallResult>;
    /**
     * Execute the tool with tracing if enabled
     * @param args Tool arguments
     * @param toolCall The tool call object
     * @returns Result of the tool execution
     */
    private executeWithTracing;
    /**
     * Format tool inputs for better tracing display
     * @param args Raw tool arguments
     * @returns Formatted input object
     */
    private formatToolInput;
    /**
     * Set a follow-up message to be included after the tool response
     */
    setFollowUp(message: string): void;
    /**
     * Convert the tool to a list of messages including tool response messages
     * and any follow-up messages
     */
    toMessages(result: ToolCallResult): Message[];
}

/**
 * Implement a class that tracks a thread of messages between the user and the assistant.
 * - constructor({messages: Message[], tools: Tool[], driver: BedrockThreadDriver}) - initialize the thread with a list of messages and tools
 * - push() - add a message to the thread
 * - shift() - remove the oldest message from the thread
 * - pop() - remove the newest message from the thread
 * - last() - get the oldest message from the thread
 * - size() - get the number of messages in the thread
 * - clear(filter?: (message: Message) => boolean) - remove all messages from the thread
 * - all() - get all messages from the thread
 * - handle(message: Message) - handle a message from the LLM
 *   - includes tool calling or triggering events
 * - send(message?: Message) - send a message or the current thread state to the LLM
 * - fork() - create a new thread with the same history and tools
 */

interface ThreadDriver {
    sendThread(thread: Thread): Promise<Thread>;
    streamThread(thread: Thread): AsyncGenerator<{
        stream: AsyncGenerator<string, void>;
        message: Message;
    }, Thread>;
    parallelToolCalls?: boolean;
}
declare class Thread extends EventSource {
    private messages;
    private readonly tools;
    readonly toolChoice: "auto" | "any";
    private readonly driver;
    private readonly maxSteps;
    private currentSteps;
    private responseHandlers;
    readonly id: string;
    readonly parallelToolCalls: boolean;
    constructor({ messages, tools, driver, toolChoice, maxSteps, parallelToolCalls, }: {
        messages?: Message[];
        tools?: ToolInterface[];
        toolChoice?: "auto" | "any";
        driver: ThreadDriver;
        maxSteps?: number;
        parallelToolCalls?: boolean;
    });
    /**
     * Register a handler to be called when an assistant message without tool calls is received
     */
    onResponse(handler: (message: Message) => Promise<void>): void;
    /**
     * Execute all registered response handlers
     */
    private executeResponseHandlers;
    /**
     * Add a message to the thread
     */
    push(message: Message): void;
    /**
     * Remove the most recent message from the thread
     */
    pop(): Message | undefined;
    /**
     * Remove the oldest message from the thread
     */
    shift(): Message | undefined;
    /**
     * Get the most recent message from the thread
     */
    last(): Message | undefined;
    /**
     * Get the number of messages in the thread
     */
    size(): number;
    /**
     * Remove all messages from the thread that match the filter
     * If no filter is provided, remove all messages
     */
    clear(filter?: (message: Message) => boolean): void;
    /**
     * Get all messages from the thread
     */
    all(): Message[];
    /**
     * Check if the thread has reached its maximum number of steps
     * @returns true if max steps reached, false otherwise
     */
    private checkMaxSteps;
    /**
     * Execute a tool call and process its response
     * @param toolCall The tool call to execute
     * @param tool The tool to execute with
     */
    private executeToolCall;
    /**
     * Process a message containing tool calls
     * @param message The message containing tool calls
     */
    private processToolCalls;
    /**
     * Process an assistant message without tool calls
     * @param message The assistant message to process
     */
    private processAssistantMessage;
    /**
     * Handle a message from the LLM
     * This includes processing tool calls and triggering events
     */
    processLastMessage(): Promise<Thread>;
    /**
     * Send a message or the current thread state to the LLM
     */
    send(message?: Message, toolResponse?: boolean): Promise<this>;
    /**
     * Wraps a stream with completion handling
     */
    private wrapStream;
    /**
     * Stream a message or the current thread state to the LLM
     */
    stream(message?: Message, toolResponse?: boolean): Promise<AsyncGenerator<string, void>>;
    /**
     * Handle the completion of a stream
     */
    private streamComplete;
    /**
     * Validates that the thread has a user message as the first non-system message
     * @throws Error if validation fails
     */
    private validateThread;
    /**
     * Get all available tools in the thread
     */
    getTools(): Tool[];
    /**
     * Add a new tool to the thread
     * @param tool The tool to add
     * @returns The tool that was added
     */
    addTool(tool: Tool | ToolInterface): Tool;
    /**
     * Generate a unique thread ID using UUID v4
     */
    private generateThreadId;
    /**
     * Create a new thread with the same message history and tools
     */
    fork(): Thread;
}

/**
 * An evaluator will run after an agent completes. It has the ability to request that the agent
 * continue working, reset the agent, or invoke other agents.
 *
 * Evaluators are triggered on the first non-tool-call message.
 * Evaluators can be chained, but each evaluator must be resolved first.
 * Evaluators may continue the thread, but if so, must not resolve a promise until they do.
 * Evaluators cannot be triggered twice on the same thread.
 *
 *
 * Evaluators must resolve before the agent will resolve.
 */
declare function makeEvaluator(fn: Evaluator): Evaluator;
type Evaluator = (props: {
    thread: Thread;
    agent: Agent;
    complete: (result: boolean) => void;
}) => (() => void) | undefined;

/**
 * AI Agent, capable of running many threads in parallel, self-reflection, and evaluation.
 * - knowledge (array of facts)
 * - instructions (array of instructions)
 * - memory (array of serialized threads)
 * - system prompt
 * - tools
 * - evaluator(s)
 * - driver(s)
 */

interface AgentKnowledge {
    fact: string;
    source?: string;
    timestamp?: Date;
}
interface AgentInstruction {
    instruction: string;
    priority: number;
    context?: string;
}
interface AgentMemory {
    threadId: string;
    messages: Message[];
    timestamp: Date;
    metadata?: Record<string, any>;
}
interface AgentOptions {
    onComplete?: (agent: Agent) => Promise<void>;
    knowledge?: AgentKnowledge[];
    instructions?: AgentInstruction[];
    memory?: AgentMemory[];
    systemPrompt?: string;
    tools?: ToolInterface[];
    driver: ThreadDriver;
    evaluators?: Evaluator[];
    trace?: boolean;
    traceMetadata?: Record<string, unknown>;
}
declare class Agent extends EventSource {
    knowledge: AgentKnowledge[];
    instructions: AgentInstruction[];
    memory: AgentMemory[];
    systemPrompt: string;
    tools: Tool[];
    driver: ThreadDriver;
    activeThreads: Map<string, Thread>;
    evaluators: Evaluator[];
    private readonly trace;
    private readonly traceMetadata?;
    constructor({ knowledge, instructions, memory, systemPrompt, tools, driver, evaluators, trace, traceMetadata, }: AgentOptions);
    /**
     * Get tools defined using decorators on the agent class
     */
    private getDecoratedTools;
    /**
     * Add a new tool to the agent
     * @param tool The tool interface to add
     * @returns The created Tool instance
     */
    addTool(tool: ToolInterface): Tool;
    /**
     * Execute the agent with a prompt
     */
    executeAgent(prompt: string): void;
    /**
     * Create a new thread with optional messages or prompt
     */
    createThread(props: {
        messages?: Message[];
        prompt?: string;
        systemPrompt?: string;
        onResponse?: (message: Message) => Promise<void>;
    }): Thread;
    /**
     * Get an active thread by its ID
     */
    getThread(threadId: string): Thread | undefined;
    /**
     * Get all active threads
     */
    getActiveThreads(): Map<string, Thread>;
    /**
     * Close a thread and store its messages in memory
     */
    closeThread(threadId: string): void;
    /**
     * Add a new piece of knowledge to the agent
     */
    addKnowledge(knowledge: AgentKnowledge): void;
    /**
     * Add a new instruction to the agent
     */
    addInstruction(instruction: AgentInstruction): void;
    /**
     * Get all tools available to the agent
     */
    getTools(): Tool[];
    /**
     * Get all knowledge available to the agent
     */
    getKnowledge(): AgentKnowledge[];
    /**
     * Get all instructions available to the agent
     */
    getInstructions(): AgentInstruction[];
    /**
     * Get all memory entries available to the agent
     */
    getMemory(): AgentMemory[];
    setSystemPrompt(systemPrompt: string): void;
    /**
     * Build the system prompt combining knowledge, instructions, and base prompt
     */
    private buildSystemPrompt;
    /**
     * Execute a task with tracing enabled
     * @param name The name of the trace
     * @param task The task to execute
     * @param metadata Additional metadata for tracing (e.g. runId, tags)
     */
    protected executeTask<T>(name: string, task: () => Promise<T>, metadata?: Record<string, unknown>): Promise<T>;
}

declare abstract class AgentTool extends Agent implements ToolInterface {
    abstract readonly name: string;
    abstract readonly description: string;
    abstract readonly parameters: z.ZodTypeAny;
    abstract executeTool(args: any, toolCall: ToolCall): Promise<any>;
}

/**
 * Decorator to mark a method as a tool with a name
 * Optional - if not provided, the method name will be used
 */
declare const ToolName: (name: string) => (target: any, propertyKey: string, _descriptor: PropertyDescriptor) => void;
/**
 * Decorator to add a description to a tool method
 */
declare const ToolDescription: (description: string) => (target: any, propertyKey: string, _descriptor: PropertyDescriptor) => void;
/**
 * Decorator to define a parameter for a tool method
 * @param name Parameter name
 * @param description Parameter description
 * @param type Zod schema for parameter validation
 */
declare const ToolParam: (name: string, description: string, type: z.ZodTypeAny) => (target: any, propertyKey: string, _parameterIndex: number) => void;
/**
 * Get all tool methods from a class instance
 */
declare const getToolMethods: (instance: any) => ToolInterface[];

type ThreeKeyedLockEvaluatorProps = {
    evalPrompt?: string;
    exitPrompt?: string;
};
declare const threeKeyedLockEvaluator: ({ evalPrompt, exitPrompt, }: ThreeKeyedLockEvaluatorProps) => Evaluator;

type AgentToolEvaluatorProps = {
    agent: Agent;
    toolName: string;
    description: string;
    promptTemplate?: string;
    parameters?: z.ZodTypeAny;
    followUpMessage?: string;
};
/**
 * Creates an evaluator that allows one agent to use another agent as a tool.
 * This is useful for delegating specific tasks to specialized agents.
 *
 * @param props Configuration for the agent tool evaluator
 * @returns An evaluator function that integrates an agent as a tool
 */
declare const agentToolEvaluator: ({ agent, toolName, description, promptTemplate, parameters, followUpMessage, }: AgentToolEvaluatorProps) => Evaluator;

/**
 * Abstract base class for model drivers.
 * Implements common functionality and defines the interface for model-specific implementations.
 */
declare abstract class BaseModelDriver extends EventSource implements ThreadDriver {
    /**
     * Process and send a thread to the model and return the updated thread
     */
    abstract sendThread(thread: Thread): Promise<Thread>;
    /**
     * Stream a response from the model
     */
    abstract streamThread(thread: Thread): AsyncGenerator<{
        stream: AsyncGenerator<string, void>;
        message: Message;
    }, Thread>;
}

/**
 * Implement a class that represents a Google Gemini AI client
 * and provides a set of tools for converting messages to and from the LLM.
 * - sendThread(thread: Thread): Thread - send a message to the LLM
 * - streamThread(thread: Thread): AsyncGenerator<string, Thread> - stream a message to the LLM
 */

/**
 * Available Gemini model options
 */
type GeminiModel = "gemini-2.5-flash" | "gemini-2.5-pro-exp-03-25" | "gemini-2.0-flash-lite" | "gemini-2.0-flash-thinking-exp-01-21" | "gemini-1.5-flash" | "gemini-1.5-pro" | "gemini-1.0-pro";
/**
 * Schema for structured output
 */
interface Schema {
    type: "string" | "integer" | "number" | "boolean" | "array" | "object";
    format?: string;
    description?: string;
    nullable?: boolean;
    enum?: string[];
    maxItems?: string;
    minItems?: string;
    properties?: Record<string, Schema>;
    required?: string[];
    propertyOrdering?: string[];
    items?: Schema;
}
interface GeminiConfig {
    model?: GeminiModel | string;
    temperature?: number;
    maxTokens?: number;
    apiKey?: string;
    cache?: boolean;
    /**
     * Whether to enable tracing
     * @default false
     */
    trace?: boolean;
    /**
     * Additional metadata for tracing
     */
    traceMetadata?: Record<string, unknown>;
    /**
     * Schema for structured output
     */
    responseSchema?: Schema;
}
declare class GeminiThreadDriver extends BaseModelDriver {
    private readonly genAI;
    private readonly model;
    private readonly temperature;
    private readonly maxTokens;
    private readonly cache;
    private readonly responseSchema?;
    /**
     * Get list of available model names for easy reference
     */
    static getAvailableModels(): GeminiModel[];
    constructor(config?: GeminiConfig);
    /**
     * Convert messages to Gemini API format
     */
    private convertMessagesToGeminiFormat;
    /**
     * Parse tool calls from the Gemini API response
     */
    private parseToolCalls;
    /**
     * Send the thread state to the LLM and process the response
     */
    sendThread(thread: Thread): Promise<Thread>;
    /**
     * Create tool config for Gemini API
     */
    private createToolConfig;
    /**
     * Stream the thread state to the LLM and process the response chunk by chunk
     */
    streamThread(thread: Thread): AsyncGenerator<{
        stream: AsyncGenerator<string, void>;
        message: Message;
    }, Thread>;
    /**
     * Create a stream processor for handling Gemini API streaming responses
     */
    private createStreamProcessor;
}

/**
 * Implement a class that represents a Cohere AI client
 * and provides a set of tools for converting messages to and from the LLM.
 * - sendThread(thread: Thread): Thread - send a message to the LLM
 * - streamThread(thread: Thread): AsyncGenerator<string, Thread> - stream a message to the LLM
 */

/**
 * Available Cohere models
 */
type CohereModel = "command-a-03-2025" | "command-r7b-12-2024" | "command-r-plus-08-2024" | "command-r-plus-04-2024" | "command-r-plus" | "command-r-08-2024" | "command-r-03-2024" | "command-r" | "command" | "command-light" | "command-light-nightly";
/**
 * Configuration options for the Cohere driver
 */
interface CohereConfig {
    /**
     * Cohere API Key
     */
    apiKey?: string;
    /**
     * Model to use
     * @default "command-r-plus"
     */
    model?: CohereModel;
    /**
     * Temperature for response generation
     * @default 0.7
     */
    temperature?: number;
    /**
     * Maximum number of tokens to generate
     */
    maxTokens?: number;
    /**
     * Whether to cache responses
     * @default false
     */
    cache?: boolean;
    /**
     * Enable tracing for this driver
     * @default false
     */
    trace?: boolean;
    /**
     * Additional metadata for tracing
     */
    traceMetadata?: Record<string, unknown>;
}
/**
 * Represents a Cohere AI client and provides tools for converting messages to/from the LLM
 */
declare class CohereThreadDriver extends BaseModelDriver {
    /**
     * Cohere API Client
     */
    private client;
    /**
     * Cohere model to use
     */
    private model;
    /**
     * Temperature for response generation
     */
    private temperature;
    /**
     * Maximum number of tokens to generate
     */
    private maxTokens?;
    /**
     * Whether to cache responses
     */
    private cache;
    /**
     * Returns a list of available Cohere models
     */
    static getAvailableModels(): CohereModel[];
    /**
     * Create a new Cohere driver
     * @param config Configuration options
     */
    constructor(config?: CohereConfig);
    /**
     * Send a thread to the LLM and get a response
     * @param thread Thread to send
     * @returns Updated thread with LLM response
     */
    sendThread(thread: Thread): Promise<Thread>;
    /**
     * Stream a thread to the LLM and get a streaming response
     * @param thread Thread to send
     * @returns AsyncGenerator yielding the stream and updated thread
     */
    streamThread(thread: Thread): AsyncGenerator<{
        stream: AsyncGenerator<string, void>;
        message: Message;
    }, Thread>;
    /**
     * Create a stream generator for handling streaming responses
     */
    private createStreamGenerator;
    /**
     * Convert a thread's messages to Cohere's API format
     * @param thread Thread to convert
     * @returns Object containing messages array and optional system message
     */
    private convertMessagesToCohereFormat;
    /**
     * Create tool definitions from thread tools
     * @param tools Tools to convert
     * @returns Array of tool definitions for Cohere API
     */
    private createToolDefinitions;
    /**
     * Parse tool calls from Cohere API response
     * @param response Cohere API response
     * @returns Array of tool calls if present
     */
    private parseToolCalls;
}

/**
 * Implement a class that represents an OpenAI client
 * and provides a set of tools for converting messages to and from the LLM.
 * - sendThread(thread: Thread): Thread - send a message to the LLM
 * - streamThread(thread: Thread): AsyncGenerator<string, Thread> - stream a message to the LLM
 */

/**
 * Available OpenAI models
 */
type OpenAIModel = "gpt-4o" | "gpt-4o-mini" | "gpt-4" | "gpt-4-turbo" | "gpt-3.5-turbo" | "gpt-4-vision-preview";
/**
 * Configuration options for the OpenAI driver
 */
interface OpenAIConfig {
    /**
     * OpenAI API Key
     */
    apiKey?: string;
    /**
     * Model to use
     * @default "gpt-4o"
     */
    model?: OpenAIModel;
    /**
     * Temperature for response generation
     * @default 0.7
     */
    temperature?: number;
    /**
     * Maximum number of tokens to generate
     */
    maxTokens?: number;
    /**
     * Whether to cache responses
     * @default false
     */
    cache?: boolean;
    /**
     * Whether to enable tracing
     * @default false
     */
    trace?: boolean;
    /**
     * Additional metadata for tracing
     */
    traceMetadata?: Record<string, unknown>;
}
/**
 * Represents an OpenAI client and provides tools for converting messages to/from the LLM
 */
declare class OpenAIThreadDriver extends BaseModelDriver {
    /**
     * OpenAI API Client
     */
    private client;
    /**
     * OpenAI model to use
     */
    private model;
    /**
     * Temperature for response generation
     */
    private temperature;
    /**
     * Maximum number of tokens to generate
     */
    private maxTokens?;
    /**
     * Whether to cache responses
     */
    private cache;
    /**
     * Returns a list of available OpenAI models
     */
    static getAvailableModels(): OpenAIModel[];
    /**
     * Create a new OpenAI driver
     * @param config Configuration options
     */
    constructor(config?: OpenAIConfig);
    /**
     * Send a thread to the LLM and get a response
     * @param thread Thread to send
     * @returns Updated thread with LLM response
     */
    sendThread(thread: Thread): Promise<Thread>;
    /**
     * Stream a thread to the LLM and get a streaming response
     * @param thread Thread to send
     * @returns AsyncGenerator yielding the stream and updated thread
     */
    streamThread(thread: Thread): AsyncGenerator<{
        stream: AsyncGenerator<string, void>;
        message: Message;
    }, Thread>;
    /**
     * Create a stream generator that handles updates to the message
     */
    private createStreamGenerator;
    /**
     * Format messages from the Thread object to the OpenAI API format
     */
    private formatMessagesForAPI;
    /**
     * Create tool definitions for the OpenAI API
     */
    private createToolDefinitions;
    /**
     * Parse tool calls from the OpenAI API response
     */
    private parseToolCalls;
}

/**
 * Implement a class that represents a Bedrock client and provides a set of tools for converting messages to and from the LLM.
 * - sendThread(thread: Thread): Thread - send a message to the LLM
 */

/**
 * Available Bedrock model options
 */
type BedrockModel = "anthropic.claude-3-haiku-20240307-v1:0" | "anthropic.claude-3-sonnet-20240229-v1:0" | "anthropic.claude-3-opus-20240229-v1:0" | "anthropic.claude-instant-v1" | "anthropic.claude-v2" | "anthropic.claude-v2:1" | "amazon.titan-text-lite-v1" | "amazon.titan-text-express-v1" | "amazon.titan-text-premier-v1" | "amazon.titan-embed-text-v1" | "amazon.titan-embed-image-v1" | "amazon.titan-image-generator-v1" | "ai21.j2-mid-v1" | "ai21.j2-ultra-v1" | "ai21.jamba-instruct-v1:0" | "cohere.command-text-v14" | "cohere.command-light-text-v14" | "cohere.embed-english-v3" | "cohere.embed-multilingual-v3" | "meta.llama2-13b-chat-v1" | "meta.llama2-70b-chat-v1" | "meta.llama3-8b-instruct-v1:0" | "meta.llama3-70b-instruct-v1:0" | "stability.stable-diffusion-xl-v1" | "stability.stable-diffusion-xl-v0" | string;
interface BedrockConfig {
    model?: BedrockModel;
    temperature?: number;
    maxTokens?: number;
    cache?: boolean;
    client?: BedrockRuntimeClient;
    trace?: boolean;
    traceMetadata?: Record<string, unknown>;
    reasoning_config?: Record<string, any>;
}
declare class BedrockThreadDriver extends BaseModelDriver {
    private readonly decoder;
    private readonly client;
    private readonly cache;
    private readonly model;
    private readonly temperature;
    private readonly maxTokens;
    private readonly reasoning_config?;
    constructor(config?: BedrockConfig);
    /**
     * Convert attachments to Bedrock content blocks
     */
    private convertAttachmentsToContentBlocks;
    /**
     * Convert thread messages to Bedrock format, separating system messages
     */
    private convertMessagesToBedrockFormat;
    /**
     * Parse tool calls from the LLM response content blocks
     */
    private parseToolCalls;
    /**
     * Send the thread state to the LLM and process the response
     */
    sendThread(thread: Thread): Promise<Thread>;
    /**
     * Stream the thread state to the LLM and process the response chunk by chunk
     */
    streamThread(thread: Thread): AsyncGenerator<{
        stream: AsyncGenerator<string, void>;
        message: Message;
    }, Thread>;
    /**
     * Validate thread content length and emptiness
     */
    private validateThread;
    /**
     * Format messages for streaming request
     */
    private formatMessagesForStreaming;
    /**
     * Create streaming request input
     */
    private createStreamingInput;
    /**
     * Process a single chunk from the Bedrock stream
     */
    private processStreamChunk;
    /**
     * Create a stream processor for handling Bedrock response chunks
     */
    private createStreamProcessor;
}

/**
 * Implement a class that represents a Cerebras AI client
 * and provides a set of tools for converting messages to and from the LLM.
 * - sendThread(thread: Thread): Thread - send a message to the LLM
 * - streamThread(thread: Thread): AsyncGenerator<string, Thread> - stream a message to the LLM
 */

/**
 * Available Cerebras models
 */
type CerebrasModel = "llama-4-scout-17b-16e-instruct" | "llama3.1-8b" | "llama-3.3-70b" | "deepSeek-r1-distill-llama-70B";
/**
 * Configuration options for the Cerebras driver
 */
interface CerebrasConfig {
    /**
     * Cerebras API Key
     */
    apiKey?: string;
    /**
     * Model to use
     * @default "llama3.1-8b"
     */
    model?: CerebrasModel | string;
    /**
     * Temperature for response generation
     * @default 0.7
     */
    temperature?: number;
    /**
     * Maximum number of tokens to generate
     */
    maxTokens?: number;
    /**
     * Whether to cache responses
     * @default false
     */
    cache?: boolean;
    /**
     * Enable tracing for this driver
     * @default false
     */
    trace?: boolean;
    /**
     * Additional metadata for tracing
     */
    traceMetadata?: Record<string, unknown>;
    /**
     * Disable parallel tool calls
     * Some Cerebras models don't support parallel tool calls
     * @default false
     */
    disableParallelToolCalls?: boolean;
    /**
     * Maximum number of tool calls allowed per thread to prevent infinite loops
     * @default 10
     */
    maxTotalToolCalls?: number;
    /**
     * Optional JSON schema to enforce for the response format.
     * See: https://inference-docs.cerebras.ai/capabilities/structured-outputs
     */
    responseFormatSchema?: Record<string, any>;
    /**
     * Optional name for the JSON schema provided in responseFormatSchema.
     * Used if responseFormatSchema is set.
     * @default "improv_schema"
     */
    responseFormatName?: string;
    /**
     * Optional flag to enforce strict adherence to the responseFormatSchema.
     * Used if responseFormatSchema is set.
     * @default true
     */
    responseFormatStrict?: boolean;
    /**
     * Whether to run tool calls in parallel
     * @default false
     */
    parallelToolCalls?: boolean;
}
/**
 * Represents a Cerebras AI client and provides tools for converting messages to/from the LLM
 */
declare class CerebrasThreadDriver extends BaseModelDriver {
    /**
     * Cerebras API Client
     */
    private client;
    /**
     * Cerebras model to use
     */
    private model;
    /**
     * Temperature for response generation
     */
    private temperature;
    /**
     * Maximum number of tokens to generate
     */
    private maxTokens?;
    /**
     * Whether to cache responses
     */
    private cache;
    /**
     * Whether parallel tool calls are disabled
     */
    private disableParallelToolCalls;
    /**
     * Track recent tool calls to prevent infinite loops
     */
    private recentToolCalls;
    /**
     * Timeframe for tracking repeated tool calls (in milliseconds)
     */
    private toolCallTimeframe;
    /**
     * Maximum number of tool calls allowed per thread to prevent infinite loops
     */
    private maxTotalToolCalls;
    /**
     * Counter for total number of tool calls processed in the current thread
     */
    private totalToolCallsCounter;
    /**
     * Whether to run tool calls in parallel
     */
    parallelToolCalls: boolean;
    /**
     * Key-value store to track repeat tool calls by their hash
     * The key is toolName:argsHash and the value is the count
     */
    private toolCallTracker;
    /**
     * Optional JSON schema for structured outputs.
     */
    private responseFormatSchema?;
    /**
     * Name for the response format schema.
     */
    private responseFormatName;
    /**
     * Strictness for the response format schema.
     */
    private responseFormatStrict;
    /**
     * Returns a list of available Cerebras models
     */
    static getAvailableModels(): CerebrasModel[];
    /**
     * Create a new Cerebras driver
     * @param config Configuration options
     */
    constructor(config?: CerebrasConfig);
    /**
     * Configure model-specific settings to handle known issues
     */
    private configureModelSpecificSettings;
    /**
     * Try several fallback strategies to handle errors.
     * This is useful for working around limitations or issues with the Cerebras API.
     *
     * @param params Original API parameters
     * @param apiError Original API error
     * @returns CerebrasResponse from a successful strategy, or throws if all strategies fail
     */
    private tryFallbackStrategies;
    /**
     * Hash the tool call arguments to compare for duplicates
     */
    private hashToolCallArgs;
    /**
     * Check if a tool call has been made before with the same arguments
     * Returns true for any repeat calls, allowing only the first occurrence
     */
    private isRepeatedToolCall;
    /**
     * Simplifies the message history after a tool call to prevent model confusion.
     * Replaces the original user request and assistant tool call with a summary.
     */
    private simplifyMessagesAfterToolCall;
    /**
     * Send a thread to the LLM and get a response
     * @param thread Thread to send
     * @returns Updated thread with LLM response
     */
    sendThread(thread: Thread): Promise<Thread>;
    /**
     * Stream a thread to the LLM and get a streaming response
     * @param thread Thread to send
     * @returns AsyncGenerator yielding the stream and updated thread
     */
    streamThread(thread: Thread): AsyncGenerator<{
        stream: AsyncGenerator<string, void>;
        message: Message;
    }, Thread>;
    /**
     * Create a stream generator that handles updates to the message
     */
    private createStreamGenerator;
    /**
     * Format messages from the Thread object to the Cerebras API format
     */
    private formatMessagesForAPI;
    /**
     * Create tool definitions for the Cerebras API
     */
    private createToolDefinitions;
    /**
     * Parse tool calls from the Cerebras API response
     */
    private parseToolCalls;
    /**
     * Check if a tool should be excluded from the tool call limit count
     * Some utility tools like SuggestNextStepsTool are meant to be called multiple times
     * and shouldn't count toward the limit
     */
    private isUtilityTool;
    /**
     * Update the tool call counter appropriately based on the tools being called
     * Utility tools don't count toward the limit
     */
    private updateToolCallCounter;
    /**
     * Convert a Cerebras streaming response to an AsyncIterable
     */
    private createAsyncIterableFromResponse;
    /**
     * Parse message content for embedded JSON tool calls
     * This handles cases where the model returns tool calls as JSON directly in the message content
     *
     * @param content The message content to parse
     * @returns ToolCall[] array if tool calls were found, undefined otherwise
     */
    private parseEmbeddedToolCalls;
    /**
     * Preprocess tool definitions to handle special field references like @{{{...}}}
     */
    private preprocessToolDefinitions;
    /**
     * Handle special field references in content
     */
    private preprocessFieldReferences;
}

/**
 * Implement a class that represents a Hugging Face Inference client
 * and provides a set of tools for converting messages to and from the LLM.
 * - sendThread(thread: Thread): Thread - send a message to the LLM
 * - streamThread(thread: Thread): AsyncGenerator<string, Thread> - stream a message to the LLM
 */

/**
 * Available Hugging Face models for text generation
 * These are just examples of popular models - there are thousands available
 */
type HuggingFaceModel = "meta-llama/Llama-3.1-8B-Instruct" | "meta-llama/Llama-3.1-70B-Instruct" | "mistralai/Mistral-7B-Instruct-v0.3" | "mistralai/Mixtral-8x7B-Instruct-v0.1" | "tiiuae/falcon-7b-instruct" | "google/flan-t5-xxl";
/**
 * Configuration options for the Hugging Face driver
 */
interface HuggingFaceConfig {
    /**
     * Hugging Face API Token
     */
    apiToken?: string;
    /**
     * Model to use
     * @default "meta-llama/Llama-3.1-8B-Instruct"
     */
    model?: HuggingFaceModel | string;
    /**
     * Custom endpoint URL (if using a custom deployed endpoint)
     */
    endpointUrl?: string;
    /**
     * Temperature for response generation
     * @default 0.7
     */
    temperature?: number;
    /**
     * Maximum number of tokens to generate
     */
    maxTokens?: number;
    /**
     * Whether to cache responses
     * @default false
     */
    cache?: boolean;
    /**
     * Enable tracing for this driver
     * @default false
     */
    trace?: boolean;
    /**
     * Additional metadata for tracing
     */
    traceMetadata?: Record<string, unknown>;
    /**
     * Provider to use
     * @default "cerebras"
     */
    provider?: string;
}
/**
 * Represents a Hugging Face Inference client and provides tools for converting messages to/from the LLM
 */
declare class HuggingFaceThreadDriver extends BaseModelDriver {
    /**
     * Hugging Face Inference Client
     */
    private client;
    /**
     * Custom endpoint client if provided
     */
    private endpointClient?;
    /**
     * Model to use
     */
    private model;
    /**
     * Temperature for response generation
     */
    private temperature;
    /**
     * Maximum number of tokens to generate
     */
    private maxTokens?;
    /**
     * Whether to cache responses
     */
    private cache;
    /**
     * Traced version of textGeneration
     */
    private textGenerationWithTracing;
    /**
     * Traced version of textGenerationStream
     */
    private textGenerationStreamWithTracing;
    /**
     * Traced version of endpoint textGeneration
     */
    private endpointTextGenerationWithTracing?;
    /**
     * Traced version of endpoint textGenerationStream
     */
    private endpointTextGenerationStreamWithTracing?;
    /**
     * Store provider if specified
     */
    private provider;
    /**
     * Private methods for chat completion with tracing
     */
    private chatCompletionWithTracing;
    private chatCompletionStreamWithTracing;
    private endpointChatCompletionWithTracing?;
    private endpointChatCompletionStreamWithTracing?;
    /**
     * Returns a list of example Hugging Face models
     */
    static getExampleModels(): HuggingFaceModel[];
    /**
     * Create a new Hugging Face driver
     * @param config Configuration options
     */
    constructor(config?: HuggingFaceConfig);
    /**
     * Setup tracing for the Hugging Face client
     */
    private setupTracing;
    /**
     * Send a thread to the LLM and get a response
     * @param thread Thread to send
     * @returns Updated thread with LLM response
     */
    sendThread(thread: Thread): Promise<Thread>;
    /**
     * Execute tool calls for the Hugging Face driver
     * This is needed because the standard isToolCall check isn't detecting our tool calls
     */
    private executeToolCalls;
    /**
     * Stream a thread to the LLM and get a streaming response
     * @param thread Thread to send
     * @returns AsyncGenerator yielding the stream and updated thread
     */
    streamThread(thread: Thread): AsyncGenerator<{
        stream: AsyncGenerator<string, void>;
        message: Message;
    }, Thread>;
    /**
     * Format messages from the Thread object for the Hugging Face API
     * @param thread Thread to format
     * @returns Formatted prompt string
     */
    private formatMessagesForAPI;
    /**
     * Format messages from the Thread object for the Chat API format
     * @param thread Thread to format
     * @returns Array of messages in chat completion format
     */
    private formatMessagesForChatAPI;
    /**
     * Parse tool calls from text
     */
    private parseToolCallsFromText;
    /**
     * Create a stream generator that handles updates to the message
     */
    private createStreamGenerator;
    /**
     * Create a stream generator that handles updates to the message for chat completion
     */
    private createChatStreamGenerator;
}

/**
 * Implement a class that represents a Groq client
 * and provides a set of tools for converting messages to and from the LLM.
 * - sendThread(thread: Thread): Thread - send a message to the LLM
 * - streamThread(thread: Thread): AsyncGenerator<string, Thread> - stream a message to the LLM
 */

/**
 * Available Groq models
 */
type GroqModel = "llama3-8b-8192" | "llama3-70b-8192" | "llama3-8b" | "llama3-70b" | "mixtral-8x7b-32768" | "gemma-7b-it" | "gemma2-9b-it";
/**
 * Configuration options for the Groq driver
 */
interface GroqConfig {
    /**
     * Groq API Key
     */
    apiKey?: string;
    /**
     * Model to use
     * @default "llama3-8b-8192"
     */
    model?: GroqModel | string;
    /**
     * Temperature for response generation
     * @default 0.7
     */
    temperature?: number;
    /**
     * Maximum number of tokens to generate
     */
    maxTokens?: number;
    /**
     * Whether to cache responses
     * @default false
     */
    cache?: boolean;
    /**
     * Whether to enable tracing
     * @default false
     */
    trace?: boolean;
    /**
     * Additional metadata for tracing
     */
    traceMetadata?: Record<string, unknown>;
    /**
     * Disable parallel tool calls
     * Some models don't support parallel tool calls
     * @default true
     */
    disableParallelToolCalls?: boolean;
}
/**
 * Represents a Groq client and provides tools for converting messages to/from the LLM
 */
declare class GroqThreadDriver extends BaseModelDriver {
    /**
     * Groq API Client
     */
    private client;
    /**
     * Groq model to use
     */
    private model;
    /**
     * Temperature for response generation
     */
    private temperature;
    /**
     * Maximum number of tokens to generate
     */
    private maxTokens?;
    /**
     * Whether to cache responses
     */
    private cache;
    /**
     * Whether to disable parallel tool calls
     */
    private disableParallelToolCalls;
    /**
     * Returns a list of available Groq models
     */
    static getAvailableModels(): GroqModel[];
    /**
     * Create a new Groq driver
     * @param config Configuration options
     */
    constructor(config?: GroqConfig);
    /**
     * Send a thread to the LLM and get a response
     * @param thread Thread to send
     * @returns Updated thread with LLM response
     */
    sendThread(thread: Thread): Promise<Thread>;
    /**
     * Stream a thread to the LLM and get a streaming response
     * @param thread Thread to send
     * @returns AsyncGenerator yielding the stream and updated thread
     */
    streamThread(thread: Thread): AsyncGenerator<{
        stream: AsyncGenerator<string, void>;
        message: Message;
    }, Thread>;
    /**
     * Parse failed generation tool calls from error response
     */
    private parseFailedGenerationToolCalls;
    /**
     * Format messages from the Thread object to the Groq API format
     */
    private formatMessagesForAPI;
    /**
     * Create tool definitions for the Groq API
     */
    private createToolDefinitions;
    /**
     * Parse tool calls from the Groq API response
     */
    private parseToolCalls;
    getModels(): Promise<any[]>;
}

/**
 * Implement a class that represents an Anthropic client
 * and provides a set of tools for converting messages to and from the LLM.
 * - sendThread(thread: Thread): Thread - send a message to the LLM
 * - streamThread(thread: Thread): AsyncGenerator<string, Thread> - stream a message to the LLM
 */

/**
 * Available Anthropic models
 */
type AnthropicModel = "claude-3-opus-20240229" | "claude-3-sonnet-20240229" | "claude-3-haiku-20240307" | "claude-3-5-sonnet-20240620" | "claude-3-7-sonnet-20250219" | "claude-2.0" | "claude-2.1" | "claude-3-opus-20240229-v1:0" | "claude-3-sonnet-20240229-v1:0" | "claude-3-haiku-20240307-v1:0";
/**
 * Configuration options for the Anthropic driver
 */
interface AnthropicConfig {
    /**
     * Anthropic API Key
     */
    apiKey?: string;
    /**
     * Model to use
     * @default "claude-3-5-sonnet-20240620"
     */
    model?: AnthropicModel;
    /**
     * Temperature for response generation
     * @default 0.7
     */
    temperature?: number;
    /**
     * Maximum number of tokens to generate
     */
    maxTokens?: number;
    /**
     * Whether to cache responses
     * @default false
     */
    cache?: boolean;
    /**
     * Enable tracing for this driver
     * @default false
     */
    trace?: boolean;
    /**
     * Additional metadata for tracing
     */
    traceMetadata?: Record<string, unknown>;
    /**
     * Tools to use
     */
    tools?: Tool[];
    /**
     * Tool choice mode
     * "auto": Let the model decide when to use tools
     * "any": Always try to use a tool
     * "none": Never use tools
     * @default "auto"
     */
    toolChoice?: "auto" | "any" | "none";
}
/**
 * Represents an Anthropic client and provides tools for converting messages to/from the LLM
 */
declare class AnthropicThreadDriver extends BaseModelDriver {
    /**
     * Anthropic API Client
     */
    private client;
    /**
     * Anthropic model to use
     */
    private model;
    /**
     * Temperature for response generation
     */
    private temperature;
    /**
     * Maximum number of tokens to generate
     */
    private maxTokens?;
    /**
     * Whether to cache responses
     */
    private cache;
    /**
     * Tool choice mode
     */
    private toolChoice?;
    /**
     * Returns a list of available Anthropic models
     */
    static getAvailableModels(): AnthropicModel[];
    /**
     * Create a new Anthropic driver
     * @param config Configuration options
     */
    constructor(config?: AnthropicConfig);
    /**
     * Send a thread to the LLM and get a response
     * @param thread Thread to send
     * @returns Updated thread with LLM response
     */
    sendThread(thread: Thread): Promise<Thread>;
    /**
     * Stream a thread to the LLM and get a streaming response
     * @param thread Thread to send
     * @returns AsyncGenerator yielding the stream and updated thread
     */
    streamThread(thread: Thread): AsyncGenerator<{
        stream: AsyncGenerator<string, void>;
        message: Message;
    }, Thread>;
    /**
     * Create a stream generator that handles updates to the message
     */
    private createStreamGenerator;
    /**
     * Format messages from the Thread object to the Anthropic API format
     */
    private formatMessagesForAPI;
    /**
     * Create tool definitions for the Anthropic API
     */
    private createToolDefinitions;
    /**
     * Parse tool calls from the Anthropic API response
     */
    private parseToolCalls;
}

/**
 * Interface for tracing function executions in Improv
 */
interface Tracer {
    /**
     * Trace a function execution
     * @param fn The function to trace
     * @param metadata Metadata about the trace
     * @returns The wrapped function that will be traced
     */
    traceable<T extends (...args: any[]) => any>(fn: T, metadata: TraceMetadata): T;
}
/**
 * Metadata for a trace
 */
interface TraceMetadata {
    /** The name of the trace */
    name: string;
    /** The type of run (e.g., "tool", "llm", "agent") */
    run_type?: string;
    /** Any additional metadata */
    [key: string]: unknown;
}

/**
 * Configuration for tracing
 */
interface TracingConfig {
    /**
     * Whether tracing is enabled
     */
    enabled: boolean;
    /**
     * Name of the tracer to use (must be registered first)
     */
    tracer?: string;
    /**
     * Global metadata to include with all traces
     */
    metadata?: Record<string, unknown>;
}
/**
 * Initialize tracing with the specified configuration
 *
 * @param config Tracing configuration
 */
declare function initTracing(conf