@recombine-ai/engine 0.5.0 → 0.7.0

package/build/lib/ai.d.ts

@@ -1,362 +1,363 @@
-import { ZodSchema } from 'zod';
+import { ZodTypeAny } from 'zod';
 import { Logger } from './interfaces';
 import { SendAction } from './bosun/action';
-export declare namespace AIEngine {
+import { PromptFile } from './prompt-fs';
+import { StepTracer } from './bosun/stepTracer';
+import { Tracer } from './bosun';
+/**
+ * Represents a basic model name for LLMs.
+ */
+export type BasicModel = 'o3-mini-2025-01-31' | 'o1-preview-2024-09-12' | 'gpt-4o-2024-11-20' | 'o1-2024-12-17' | (string & {});
+export interface ProgrammaticStep<CTX> {
+    /** Step name for debugging */
+    name: string;
+    /** Determines if the step should be run or not */
+    runIf?: (messages: Conversation, ctx: CTX) => boolean | Promise<boolean>;
+    /** Content of the step */
+    execute: (messages: Conversation, ctx: CTX) => Promise<unknown>;
+    /** Error handler called if an error occurred during in `execute` function */
+    onError?: (error: string, ctx: CTX) => Promise<unknown>;
+}
+export interface LLMStep<CTX> {
+    /** Step name for debugging */
+    name: string;
+    /** Determines if the step should be run or not */
+    runIf?: (messages: Conversation, ctx: CTX) => boolean | Promise<boolean>;
+    /** LLM to use. Defaults to gpt-4o */
+    model?: BasicModel;
     /**
-     * Represents a basic model name for LLMs.
+     * Prompt can be a simple string or a link to a file, loaded with `loadFile` function which
+     * takes a path to the file relative to `src/use-cases` directory. Should be Nunjucks-compatible.
      */
-    export type BasicModel = 'o3-mini-2025-01-31' | 'o1-preview-2024-09-12' | 'gpt-4o-2024-11-20' | 'o1-2024-12-17' | (string & {});
-    export interface ProgrammaticStep {
-        /** Step name for debugging */
-        name: string;
-        /** Determines if the step should be run or not */
-        runIf?: (messages: Conversation) => boolean | Promise<boolean>;
-        /** Content of the step */
-        execute: () => Promise<unknown>;
-        /** Error handler called if an error occurred during in `execute` function */
-        onError: (error: string) => Promise<unknown>;
-    }
-    export interface LLMStep {
-        /** Step name for debugging */
-        name: string;
-        /** Determines if the step should be run or not */
-        runIf?: (messages: Conversation) => boolean | Promise<boolean>;
-        /** LLM to use. Defaults to gpt-4o */
-        model?: BasicModel;
-        /**
-         * Prompt can be a simple string or a link to a file, loaded with `loadFile` function which
-         * takes a path to the file relative to `src/use-cases` directory. Should be Nunjucks-compatible.
-         */
-        prompt: string | File;
-        /**
-         * Defines the expected structure of the LLM's output.
-         * Accepts either a boolean (for plain text or JSON responses) or a ZodSchema, which is automatically
-         * converted to a JSON schema. When provided, the LLM's response is validated and parsed according
-         * to this schema ensuring reliable structured output.
-         */
-        json: boolean | ZodSchema;
-        /** Exclude directives from message history passed to the LLM for this step */
-        ignoreDirectives?: boolean;
-        /**
-         * Additional data to be inserted into the prompt. Accessible via Nunjucks variables.
-         * @example
-         * ```
-         * prompt: "Hello {{ name }}, your score is {{ score }}"
-         * context: { name: "John", score: 42 }
-         * ```
-         */
-        context?: Record<string, unknown>;
-        /**
-         * Function to execute with the LLM's response. Use {@link setProposedReply} to use the LLM's output as the proposed reply.
-         * Or use combination of {@link getProposedReply} and {@link setProposedReply} to substitute parts of the string.
-         * @example
-         * ```
-         * // Use LLM output directly as reply
-         * execute: (reply) => messages.setProposedReply(reply)
-         *
-         * // Substitute tokens in LLM output
-         * execute: (reply) => {
-         *   const withLink = reply.replace('<PAYMENT_LINK>', 'https://payment.example.com/123')
-         *   messages.setProposedReply(withLink)
-         * }
-         * ```
-         */
-        execute: (reply: string) => Promise<unknown>;
-        /**
-         * Check a condition, whether the `execute` function should run or not
-         * @deprecated use `runIf` to check if the step should be run, use if in `execute` to check
-         * if it should be executed
-         **/
-        shouldExecute?: (reply: string) => boolean | Promise<boolean>;
-        /**
-         * When provided, throws an error if the step is invoked more times than `maxAttempts`.
-         * Number of attempts taken is reset when `shouldExecute` returns `false`. Useful to limit
-         * rewinds by reviewers. NOTE that it doesn't work on steps without `shouldExecute` method.
-         */
-        maxAttempts?: number;
-        /** Error handler called if an error occurred during LLM API call or in `execute` function */
-        onError: (error: string) => Promise<unknown>;
-    }
+    prompt: string | PromptFile;
     /**
-     * A useful trace of a step execution. It's properties are filled during the execution. There is no guarantee that any of them will be filled.
+     * Do not put messages that were added via {@link Conversation.addMessage} into the prompt.
      */
-    export type StepTrace = {
-        renderedPrompt?: string;
-        receivedContext?: Record<string, unknown>;
-        receivedPrompt?: string;
-        stringifiedConversation?: string;
-    };
+    ignoreAddedMessages?: boolean;
     /**
-     * An AI workflow composed of steps.
+     * When provided, throws an error if the step is invoked more times than `maxAttempts`.
+     * Number of attempts taken is reset when `shouldExecute` returns `false`. Useful to limit
+     * rewinds by reviewers. NOTE that it doesn't work on steps without `shouldExecute` method.
      */
-    export interface Workflow {
-        /**
-         * Terminates the workflow, preventing further steps from being executed.
-         */
-        terminate: () => void;
-        /**
-         * Runs the workflow with a given conversation context.
-         * Executes steps sequentially until completion or termination.
-         * @param messages - The conversation context for the workflow
-         * @returns The proposed reply if workflow completes, or null if terminated
-         */
-        run: (messages: Conversation) => Promise<{
-            reply: string | null;
-            trace: {
-                steps: Record<string, StepTrace>;
-            };
-        }>;
-        /**
-         * Rewinds the workflow execution to a specific step.
-         * @param step - The step to rewind to
-         */
-        rewindTo: (step: LLMStep | ProgrammaticStep) => void;
-        /**
-         * Registers a callback to be executed before each step.
-         * @param callback - Async function to execute before each step
-         */
-        beforeEach: (callback: () => Promise<unknown>) => void;
-    }
+    maxAttempts?: number;
+    /** Error handler called if an error occurred during LLM API call or in `execute` function */
+    onError?: (error: string, ctx: CTX) => Promise<unknown>;
+}
+export interface JsonLLMStep<CTX, Schema extends ZodTypeAny> extends LLMStep<CTX> {
     /**
-     * The main interface for the AI Engine.
-     *
+     * Defines the expected structure of the LLM's output. Accepts ZodSchema. When provided, the
+     * LLM's response is validated and parsed according to this schema ensuring reliable structured
+     * output.
+     */
+    schema: Schema;
+    /**
+     * Function to execute with the LLM's response. Use {@link setProposedReply} to use the LLM's output as the proposed reply.
+     * Or use combination of {@link getProposedReply} and {@link setProposedReply} to substitute parts of the string.
      * @example
-     * ```typescript
-     * import { AIEngine } from './lib/ai'
-     *
-     * // Create a new AI engine instance
-     * const ai = AIEngine.createAIEngine()
-     *
-     * // Create a conversation
-     * const conversation = ai.createConversation()
-     * conversation.addMessage('user', 'I need help with my order')
-     *
-     * // Define workflow steps
-     * const killswitch = ai.createStep({
-     *   name: 'killswitch',
-     *   prompt: ai.loadFile('prompts/killswitch.njk'),
-     *   execute: async (reply) => {
-     *     const result = JSON.parse(reply)
-     *     if (result.terminate) {
-     *       conversation.addDirective(`Terminating workflow: ${result.reason}`)
-     *       return workflow.terminate()
-     *     }
-     *   },
-     *   onError: async (error) => conversation.addDirective(`Error in killswitch: ${error}`)
-     * })
-     *
-     * const analyzeIntent = ai.createStep({
-     *   name: 'analyze-intent',
-     *   prompt: ai.loadFile('prompts/analyze-intent.njk'),
-     *   execute: async (reply) => {
-     *     const intent = JSON.parse(reply)
-     *     conversation.addDirective(`User intent is: ${intent.category}`)
-     *   },
-     *   onError: async (error) => conversation.addDirective(`Error analyzing intent: ${error}`)
-     * })
-     *
-     * const mainReply = ai.createStep({
-     *   name: 'main-reply',
-     *   prompt: ai.loadFile('prompts/generate-response.njk'),
-     *   execute: async (reply) => conversation.setProposedReply(reply),
-     *   onError: async (error) => conversation.setProposedReply(`I'm sorry, I'm having trouble right now.`)
-     * })
+     * ```
+     * // Use LLM output directly as reply
+     * execute: (reply) => messages.setProposedReply(reply)
      *
-     * // Create and run the workflow
-     * const workflow = await ai.createWorkflow(killswitch, analyzeIntent, mainReply)
-     * const response = await workflow.run(conversation)
-     * console.log(response)
+     * // Substitute tokens in LLM output
+     * execute: (reply) => {
+     *   const withLink = reply.replace('<PAYMENT_LINK>', 'https://payment.example.com/123')
+     *   messages.setProposedReply(withLink)
+     * }
      * ```
      */
-    export interface AIEngine {
-        /**
-         * Creates a workflow from a sequence of steps.
-         * @param steps - An array of LLM or programmatic steps to be executed in order.
-         * @returns A Promise that resolves to the created Workflow.
-         */
-        createWorkflow: (...steps: Array<LLMStep | ProgrammaticStep>) => Promise<Workflow>;
-        /**
-         * Creates a step that can be used in a workflow.
-         * @param step - The LLM or programmatic step to create.
-         * @returns The created step of the same type as the input.
-         */
-        createStep: <T extends LLMStep | ProgrammaticStep>(step: T) => T;
-        /**
-         * Loads a file from the specified path.
-         * @param path - The path to the file to load.
-         * @returns The loaded File object.
-         */
-        loadFile: (path: string) => File;
-        /**
-         * Creates a new conversation instance.
-         * @param messages - Optional initial messages for the conversation.
-         * @returns A new Conversation object.
-         */
-        createConversation: (messages?: Message[]) => Conversation;
-        /**
-         * Renders a prompt string using Nunjucks templating engine.
-         * @param prompt - The prompt string to render.
-         * @param context - Optional context object to use for rendering the prompt.
-         * @returns The rendered prompt string.
-         */
-        renderPrompt: typeof renderPrompt;
-    }
+    execute: (reply: Zod.infer<Schema>, conversation: Conversation, ctx: CTX) => Promise<unknown>;
     /**
-     * Represents a conversation between a user and an AI agent.
-     * Provides methods to manage the conversation flow, format messages, and convert the conversation to a string representation.
-     *
+     * Check a condition, whether the `execute` function should run or not
+     * @deprecated use `runIf` to check if the step should be run, use if in `execute` to check
+     * if it should be executed
+     **/
+    shouldExecute?: (reply: Schema, ctx: CTX) => boolean | Promise<boolean>;
+}
+export interface StringLLMStep<CTX> extends LLMStep<CTX> {
+    /**
+     * Function to execute with the LLM's response. Use {@link setProposedReply} to use the LLM's output as the proposed reply.
+     * Or use combination of {@link getProposedReply} and {@link setProposedReply} to substitute parts of the string.
      * @example
-     * ```typescript
-     * // Create a new conversation instance
-     * const conversation = new Conversation();
-     *
-     * // Set names for the participants
-     * conversation.setUserName("Client");
-     * conversation.setAgentName("Support");
-     *
-     * // Add messages to the conversation
-     * conversation.addMessage("user", "I need help with my account");
-     * conversation.addDirective("Ask for account details");
+     * ```
+     * // Use LLM output directly as reply
+     * execute: (reply) => messages.setProposedReply(reply)
      *
-     * // Get the conversation as a string to feed to an LLM
-     * const conversationText = conversation.toString();
-     * // Output:
-     * // Client: I need help with my account
-     * // System: Ask for account details
+     * // Substitute tokens in LLM output
+     * execute: (reply) => {
+     *   const withLink = reply.replace('<PAYMENT_LINK>', 'https://payment.example.com/123')
+     *   messages.setProposedReply(withLink)
+     * }
      * ```
      */
-    export interface Conversation {
-        /**
-         * Sets the name of the user in the conversation to be used in {@link toString}.
-         * @param name - The name to set for the user.
-         */
-        setUserName(name: string): void;
-        /**
-         * Sets the name of the AI agent in the conversation to be used in {@link toString}.
-         * @param name - The name to set for the agent.
-         */
-        setAgentName(name: string): void;
-        /**
-         * Converts the conversation to a string representation to be fed to an LLM.
-         * @param ignoreDirectives - Whether to ignore directives in the string output.
-         * @returns The string representation of the conversation.
-         */
-        toString: (ignoreDirectives?: boolean) => string;
-        /**
-         * Adds a directive message to the conversation.
-         * @param message - The directive message to add.
-         * @example
-         * ```
-         * // Add a directive to guide the LLM response
-         * conversation.addDirective("Ask the user for their preferred date and time for the reservation");
-         *
-         * // The resulting conversation string might look like:
-         * // User: I'd like to book a table at your restaurant.
-         * // System: Ask the user for their preferred date and time for the reservation
-         * ```
-         */
-        addDirective: (message: string, formatter?: (message: Message) => string) => void;
-        /**
-         * Adds a message from a specified sender to the conversation.
-         * @param name - The sender of the message.
-         * @param message - The content of the message.
-         */
-        addMessage: (name: Message['sender'], message: string) => void;
-        /**
-         * Sets a custom formatter for directive messages.
-         * @param formatter - A function that takes a Message and returns a formatted string.
-         */
-        setDefaultDirectiveFormatter: (formatter: (message: Message) => string) => void;
-        /**
-         * Sets a custom formatter for proposed messages.
-         * @param formatter - A function that takes a message string and returns a formatted string.
-         */
-        setProposedMessageFormatter: (formatter: (message: string) => string) => void;
-        /**
-         * Sets a proposed reply message.
-         * @param message - The proposed reply message.
-         */
-        setProposedReply: (message: string) => void;
-        /**
-         * Gets the current proposed reply message.
-         * @returns The proposed reply message, or null if none exists.
-         */
-        getProposedReply: () => string | null;
-        /**
-         * Gets the history of all messages in the conversation.
-         * @returns An array of Message objects representing the conversation history.
-         */
-        getHistory: () => Message[];
-    }
+    execute: (reply: string, conversation: Conversation, ctx: CTX) => Promise<unknown>;
     /**
-     * Represents a message in a conversation between a user and an agent, or a system message.
-     * Messages can contain text and optionally an image URL. To be used in the {@link Conversation} interface.
+     * Check a condition, whether the `execute` function should run or not
+     * @deprecated use `runIf` to check if the step should be run, use if in `execute` to check
+     * if it should be executed
+     **/
+    shouldExecute?: (reply: string, ctx: CTX) => boolean | Promise<boolean>;
+}
+/**
+ * An AI workflow composed of steps.
+ */
+export interface Workflow<CTX> {
+    /**
+     * Terminates the workflow, preventing further steps from being executed.
      */
-    export interface Message {
-        /** The sender of the message, which can be one of the following: 'user', 'agent', or 'system' */
-        sender: 'user' | 'agent' | 'system';
-        /** The text content of the message */
-        text: string;
-        /** Optional URL of an image associated with the message */
-        imageUrl?: string;
-        formatter?: (message: Message) => string;
-    }
-    export interface File {
-        content: () => Promise<string>;
-    }
+    terminate: () => void;
     /**
-     * Configuration options for the Engine.
+     * Runs the workflow with a given conversation context.
+     * Executes steps sequentially until completion or termination.
+     * @param messages - The conversation context for the workflow
+     * @returns The proposed reply if workflow completes, or null if terminated
      */
-    export interface EngineConfig {
-        /**
-         * Optional token storage object that provides access to authentication tokens.
-         * @property {object} tokenStorage - Object containing method to retrieve token.
-         * @property {() => Promise<string | null>} tokenStorage.getToken - Function that returns a promise resolving to an authentication token or null.
-         */
-        tokenStorage?: {
-            getToken: () => Promise<string | null>;
-        };
-        /**
-         * Optional base URL path for resolving paths to prompts.
-         */
-        basePath?: string;
-        /**
-         * Optional logger instance for handling log messages.
-         */
-        logger?: Logger;
-        /**
-         * Optional function for sending actions.
-         */
-        sendAction?: SendAction;
-    }
+    run: (messages: Conversation, ctx?: CTX) => Promise<string | null>;
     /**
-     * Creates an AI Engine with the given configuration.
-     *
-     * The AI Engine provides utilities for creating and running conversational workflows
-     * with large language models, specifically OpenAI GPT models.
-     *
-     * @returns An AIEngine instance.
-     *
+     * Rewinds the workflow execution to a specific step.
+     * @param step - The step to rewind to
+     */
+    rewindTo: (step: LLMStep<CTX> | ProgrammaticStep<CTX>) => void;
+    /**
+     * Registers a callback to be executed before each step.
+     * @param callback - Async function to execute before each step
+     */
+    beforeEach: (callback: () => Promise<unknown>) => void;
+    /**
+     * Add a step to workflow
+     */
+    addStep<Schema extends ZodTypeAny>(step: JsonLLMStep<CTX, Schema>): void;
+    addStep(step: StringLLMStep<CTX>): void;
+    addStep(step: ProgrammaticStep<CTX>): void;
+}
+export interface WorkflowConfig<CTX> {
+    onError: (error: string, ctx: CTX) => Promise<unknown>;
+}
+interface StepBuilder<CTX> {
+    <Schema extends ZodTypeAny>(step: JsonLLMStep<CTX, Schema>): JsonLLMStep<CTX, Schema>;
+    (step: StringLLMStep<CTX>): StringLLMStep<CTX>;
+    (step: ProgrammaticStep<CTX>): ProgrammaticStep<CTX>;
+}
+/**
+ * The main interface for the AI Engine.
+ *
+ * @example
+ * ```typescript
+ * import { AIEngine } from './lib/ai'
+ *
+ * // Create a new AI engine instance
+ * const ai = AIEngine.createAIEngine()
+ *
+ * // Create a conversation
+ * const conversation = ai.createConversation()
+ * conversation.addMessage('user', 'I need help with my order')
+ *
+ * // Define workflow steps
+ * const killswitch = ai.createStep({
+ *   name: 'killswitch',
+ *   prompt: ai.loadFile('prompts/killswitch.njk'),
+ *   execute: async (reply) => {
+ *     const result = JSON.parse(reply)
+ *     if (result.terminate) {
+ *       conversation.addDirective(`Terminating workflow: ${result.reason}`)
+ *       return workflow.terminate()
+ *     }
+ *   },
+ *   onError: async (error) => conversation.addDirective(`Error in killswitch: ${error}`)
+ * })
+ *
+ * const analyzeIntent = ai.createStep({
+ *   name: 'analyze-intent',
+ *   prompt: ai.loadFile('prompts/analyze-intent.njk'),
+ *   execute: async (reply) => {
+ *     const intent = JSON.parse(reply)
+ *     conversation.addDirective(`User intent is: ${intent.category}`)
+ *   },
+ *   onError: async (error) => conversation.addDirective(`Error analyzing intent: ${error}`)
+ * })
+ *
+ * const mainReply = ai.createStep({
+ *   name: 'main-reply',
+ *   prompt: ai.loadFile('prompts/generate-response.njk'),
+ *   execute: async (reply) => conversation.setProposedReply(reply),
+ *   onError: async (error) => conversation.setProposedReply(`I'm sorry, I'm having trouble right now.`)
+ * })
+ *
+ * // Create and run the workflow
+ * const workflow = await ai.createWorkflow(killswitch, analyzeIntent, mainReply)
+ * const response = await workflow.run(conversation)
+ * console.log(response)
+ * ```
+ */
+export interface AIEngine {
+    /**
+     * Creates a workflow from a sequence of steps.
+     * @param config - common parameters for a workflow
+     * @returns A Promise that resolves to the created Workflow.
+     */
+    createWorkflow: <CTX>(config: WorkflowConfig<CTX>) => Workflow<CTX>;
+    /**
+     * Creates a new conversation instance.
+     * @param messages - Optional initial messages for the conversation.
+     * @returns A new Conversation object.
+     */
+    createConversation: (messages?: Message[]) => Conversation;
+    /**
+     * Get the function to create steps to use with workflow.addStep(step)
+     * if you want to define steps outside of workflow.
+     */
+    getStepBuilder<CTX>(): StepBuilder<CTX>;
+    /**
+     * Renders a prompt string using Nunjucks templating engine.
+     * @param prompt - The prompt string to render.
+     * @param context - Optional context object to use for rendering the prompt.
+     * @returns The rendered prompt string.
+     */
+    renderPrompt: typeof renderPrompt;
+}
+/**
+ * Represents a conversation between a user and an AI agent.
+ * Provides methods to manage the conversation flow, format messages, and convert the conversation to a string representation.
+ *
+ * @example
+ * ```typescript
+ * // Create a new conversation instance
+ * const conversation = new Conversation();
+ *
+ * // Set names for the participants
+ * conversation.setUserName("Client");
+ * conversation.setAgentName("Support");
+ *
+ * // Add messages to the conversation
+ * conversation.addMessage("user", "I need help with my account");
+ * conversation.addDirective("Ask for account details");
+ *
+ * // Get the conversation as a string to feed to an LLM
+ * const conversationText = conversation.toString();
+ * // Output:
+ * // Client: I need help with my account
+ * // System: Ask for account details
+ * ```
+ */
+export interface Conversation {
+    /**
+     * Sets the name of the user in the conversation to be used in {@link toString}.
+     * @param name - The name to set for the user.
+     */
+    setUserName(name: string): void;
+    /**
+     * Sets the name of the AI agent in the conversation to be used in {@link toString}.
+     * @param name - The name to set for the agent.
+     */
+    setAgentName(name: string): void;
+    /**
+     * Sets the default formatter for stringifying messages when toString is called.
+     * @param formatter - A function that takes a message and returns a formatted string.
+     */
+    setDefaultFormatter: (formatter: (message: Message) => string) => void;
+    /**
+     * Converts the conversation to a string representation to be fed to an LLM.
+     * @param filter - A function that filters messages based on certain criteria.
      * @example
-     * ```ts
-     * const engine = createAIEngine({
-     *   logger: customLogger,
-     *   basePath: '/path/to/prompts'
-     * });
-     *
-     * const workflow = await engine.createWorkflow(
-     *   engine.createStep({
-     *     name: 'generate-response',
-     *     prompt: engine.loadFile('prompts/response.txt'),
-     *     execute: (response) => conversation.setProposedReply(response)
-     *   })
-     * );
-     *
-     * const reply = await workflow.run(conversation);
-     * ```
+     * @returns The string representation of the conversation.
+     */
+    toString: (options?: {
+        ignoreAddedMessages?: boolean;
+    }) => string;
+    /**
+     * Adds a message from a specified sender to the conversation.
+     * @param message - The message to add to the conversation.
+     */
+    addMessage: (message: Message, opts?: {
+        formatter?: (message: Message) => string;
+    }) => void;
+    /**
+     * Sets a custom formatter for proposed messages.
+     * @param formatter - A function that takes a message string and returns a formatted string.
+     */
+    setProposedMessageFormatter: (formatter: (message: string) => string) => void;
+    /**
+     * Sets a proposed reply message.
+     * @param message - The proposed reply message.
+     */
+    setProposedReply: (message: string) => void;
+    /**
+     * Gets the current proposed reply message.
+     * @returns The proposed reply message, or null if none exists.
+     */
+    getProposedReply: () => string | null;
+    /**
+     * Gets the history of all messages in the conversation.
+     * Returns {@link Message} rather than {@link ConversationMessage} because none of the {@link ConversationMessage} properties should be accessed outside of the {@link Conversation} context.
+     * @returns An array of Message objects representing the conversation history.
+     */
+    getHistory: () => Message[];
+}
+/**
+ * Represents a message in a conversation between a user and an agent, or a system message.
+ * Messages can contain text and optionally an image URL. To be used in the {@link Conversation} interface.
+ */
+export interface Message {
+    /** The sender of the message, which can be one of the following: 'user', 'agent', or 'system' */
+    sender: 'user' | 'agent' | 'system';
+    /** The text content of the message */
+    text: string;
+    /** Optional URL of an image associated with the message */
+    imageUrl?: string;
+}
+/**
+ * Configuration options for the Engine.
+ */
+export interface EngineConfig {
+    /**
+     * Optional token storage object that provides access to authentication tokens.
+     * @property {object} tokenStorage - Object containing method to retrieve token.
+     * @property {() => Promise<string | null>} tokenStorage.getToken - Function that returns a promise resolving to an authentication token or null.
+     */
+    tokenStorage?: {
+        getToken: () => Promise<string | null>;
+    };
+    /**
+     * Optional logger instance for handling log messages.
+     */
+    logger?: Logger;
+    /**
+     * Optional function for sending actions.
      */
-    export function createAIEngine(cfg?: EngineConfig): AIEngine;
-    function renderPrompt(prompt: string, context?: Record<string, unknown>): string;
-    export {};
+    sendAction?: SendAction;
+    /** traces received prompt, rendered prompt, context and other useful info about LLM execution */
+    stepTracer?: StepTracer;
+    /** registers steps in workflow */
+    tracer?: Tracer;
 }
+/**
+ * Creates an AI Engine with the given configuration.
+ *
+ * The AI Engine provides utilities for creating and running conversational workflows
+ * with large language models, specifically OpenAI GPT models.
+ *
+ * @returns An AIEngine instance.
+ *
+ * @example
+ * ```ts
+ * const engine = createAIEngine({
+ *   logger: customLogger,
+ *   basePath: '/path/to/prompts'
+ * });
+ *
+ * const workflow = await engine.createWorkflow(
+ *   engine.createStep({
+ *     name: 'generate-response',
+ *     prompt: engine.loadFile('prompts/response.txt'),
+ *     execute: (response) => conversation.setProposedReply(response)
+ *   })
+ * );
+ *
+ * const reply = await workflow.run(conversation);
+ * ```
+ */
+export declare function createAIEngine(cfg?: EngineConfig): AIEngine;
+declare function renderPrompt(prompt: string, context?: Record<string, unknown>): string;
+export declare function createConversation(initialMessages?: Message[]): Conversation;
+export declare function getStepBuilder<CTX = unknown>(): StepBuilder<CTX>;
+export {};
 //# sourceMappingURL=ai.d.ts.map