@recombine-ai/engine 0.1.1 → 0.3.0

package/build/index.d.ts

@@ -1,5 +1,7 @@
-export { type AiEngine, createAIEngine } from './lib/ai';
-export { delayFactory, type Schedule } from './lib/schedule';
-export * from './lib/interfaces';
+import { AIEngine } from './lib/ai';
+export { AIEngine } from './lib/ai';
+export declare const createAIEngine: typeof AIEngine.createAIEngine;
+export { delayFactory, Schedule } from './lib/schedule';
+export { Scheduler, Logger } from './lib/interfaces';
 export * from './lib/bosun';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAExD,OAAO,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAE5D,cAAc,kBAAkB,CAAA;AAEhC,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC,eAAO,MAAM,cAAc,gCAA0B,CAAA;AAErD,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEvD,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAEpD,cAAc,aAAa,CAAA"}

package/build/index.js

@@ -14,10 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.delayFactory = exports.createAIEngine = void 0;
-var ai_1 = require("./lib/ai");
-Object.defineProperty(exports, "createAIEngine", { enumerable: true, get: function () { return ai_1.createAIEngine; } });
+exports.delayFactory = exports.createAIEngine = exports.AIEngine = void 0;
+const ai_1 = require("./lib/ai");
+var ai_2 = require("./lib/ai");
+Object.defineProperty(exports, "AIEngine", { enumerable: true, get: function () { return ai_2.AIEngine; } });
+exports.createAIEngine = ai_1.AIEngine.createAIEngine;
 var schedule_1 = require("./lib/schedule");
 Object.defineProperty(exports, "delayFactory", { enumerable: true, get: function () { return schedule_1.delayFactory; } });
-__exportStar(require("./lib/interfaces"), exports);
 __exportStar(require("./lib/bosun"), exports);

package/build/lib/ai.d.ts

@@ -1,88 +1,333 @@
 import { ZodSchema } from 'zod';
-import { Logger, Message } from './interfaces';
+import { Logger } from './interfaces';
 import { SendAction } from './bosun/action';
-export interface Step {
-    /** Step name (used mainly for debugging) */
-    name: string;
+export declare namespace AIEngine {
+    type BasicModel = 'o3-mini-2025-01-31' | 'o1-preview-2024-09-12' | 'gpt-4o-2024-11-20' | 'o1-2024-12-17';
+    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>;
+    }
+    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;
+        /**
+         * Schema for structured LLM output using {@link zod https://zod.dev/}
+         * library.
+         */
+        schema?: 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 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.
+     * An AI workflow composed of steps.
      */
-    prompt: string | File;
+    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<string | null>;
+        /**
+         * 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;
+    }
     /**
-     * In case you want a structured from LLM, define a schema using {@link zod https://zod.dev/}
-     * library.
+     * 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)
+     * ```
      */
-    schema?: ZodSchema;
-    /** Exclude directives from message history for this step */
-    ignoreDirectives?: boolean;
-    /** Additional data to be inserted into prompt */
-    context?: Record<string, unknown>;
-    /** Check a condition, whether the `execute` function should run or not */
-    shouldExecute?: (reply: string) => boolean | Promise<boolean>;
-    /** Check a condition, whether the whole step should be run or not */
-    runIf?: (messages: Messages) => boolean | Promise<boolean>;
-    /** Use when you need to do some action when LLM's response received */
-    execute: (reply: string) => Promise<unknown>;
-    /** Error handler called if an error occurred during LLM API call or in `execute` function */
-    onError: (error: string) => Promise<unknown>;
+    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;
+    }
     /**
-     * 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.
+     * 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
+     * ```
      */
-    maxAttempts?: number;
-}
-export interface DumbStep {
-    name: string;
-    runIf?: () => boolean | Promise<boolean>;
-    execute: () => Promise<unknown>;
-    onError: (error: string) => Promise<unknown>;
-}
-export type CreateStep = ReturnType<typeof createAIEngine>['createStep'];
-export type CreateWorkflow = ReturnType<typeof createAIEngine>['createWorkflow'];
-export type LoadFile = ReturnType<typeof createAIEngine>['loadFile'];
-export type MakeMessagesList = ReturnType<typeof createAIEngine>['makeMessagesList'];
-export type AiEngine = {
-    createWorkflow: CreateWorkflow;
-    createStep: CreateStep;
-    loadFile: LoadFile;
-    makeMessagesList: MakeMessagesList;
-};
-export interface Messages {
-    setUserName(name: string): void;
-    setAgentName(name: string): void;
-    toString: (ignoreDirectives?: boolean) => string;
-    addDirective: (message: string) => void;
-    addMessage: (name: Message['sender'], message: string) => void;
-    directiveFormat: (formatter: (message: Message) => string) => void;
-    proposedMessageFormat: (formatter: (message: string) => string) => void;
-    setProposedReply: (message: string) => void;
-    getProposedReply: () => string | null;
-    getHistory: () => Message[];
-}
-export interface File {
-    content: () => Promise<string>;
-}
-export interface EngineConfig {
-    tokenStorage?: {
-        getToken: () => Promise<string | null>;
-    };
-    basePath?: string;
-    logger?: Logger;
-    sendAction?: SendAction;
-}
-export declare function createAIEngine(cfg?: EngineConfig): {
-    createWorkflow: (...steps: Array<Step | DumbStep>) => Promise<{
-        terminate: () => void;
-        run: (messages: Messages) => Promise<string | null>;
-        rewindTo: (step: Step) => void;
-        beforeEach(callback: () => Promise<unknown>): void;
-    }>;
-    createStep: <T extends Step | DumbStep>(step: T) => T;
-    loadFile: (path: string) => {
+    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) => 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.
+         */
+        setDirectiveFormatter: (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[];
+    }
+    /**
+     * 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.
+     */
+    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;
+    }
+    interface File {
         content: () => Promise<string>;
-    };
-    makeMessagesList: (messages?: Message[]) => Messages;
-};
+    }
+    /**
+     * Configuration options for the Engine.
+     */
+    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;
+    }
+    /**
+     * 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);
+     * ```
+     */
+    function createAIEngine(cfg?: EngineConfig): AIEngine;
+}
 //# sourceMappingURL=ai.d.ts.map

package/build/lib/ai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/lib/ai.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,CAAA;AAE/B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,EAAc,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAGvD,MAAM,WAAW,IAAI;IACjB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;IAEZ;;;OAGG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAErB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAElB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAE1B,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAEjC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE7D,qEAAqE;IACrE,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE1D,uEAAuE;IACvE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAE5C,6FAA6F;IAC7F,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAE5C;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,QAAQ;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACxC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC/C;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,YAAY,CAAC,CAAA;AAExE,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,gBAAgB,CAAC,CAAA;AAEhF,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,UAAU,CAAC,CAAA;AAEpE,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,kBAAkB,CAAC,CAAA;AAEpF,MAAM,MAAM,QAAQ,GAAG;IACnB,cAAc,EAAE,cAAc,CAAA;IAC9B,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,EAAE,QAAQ,CAAA;IAClB,gBAAgB,EAAE,gBAAgB,CAAA;CACrC,CAAA;AAED,MAAM,WAAW,QAAQ;IACrB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,QAAQ,EAAE,CAAC,gBAAgB,CAAC,EAAE,OAAO,KAAK,MAAM,CAAA;IAChD,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,UAAU,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9D,eAAe,EAAE,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,KAAK,IAAI,CAAA;IAClE,qBAAqB,EAAE,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,KAAK,IAAI,CAAA;IACvE,gBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3C,gBAAgB,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACrC,UAAU,EAAE,MAAM,OAAO,EAAE,CAAA;CAC9B;AACD,MAAM,WAAW,IAAI;IACjB,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,YAAY;IACzB,YAAY,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;KAAE,CAAA;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,UAAU,CAAA;CAC1B;AAED,wBAAgB,cAAc,CAAC,GAAG,GAAE,YAAiB;+BA2DT,KAAK,CAAC,IAAI,GAAG,QAAQ,CAAC;;wBAWhC,QAAQ;yBAqBb,IAAI;6BAWA,MAAM,OAAO,CAAC,OAAO,CAAC;;iBA3F/B,CAAC,SAAS,IAAI,GAAG,QAAQ,QAAQ,CAAC,KAAG,CAAC;qBAwNlC,MAAM;;;kCApNM,OAAO,EAAE,KAAQ,QAAQ;EAqOhE"}
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/lib/ai.ts"],"names":[],"mappings":"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"}

package/build/lib/ai.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createAIEngine = createAIEngine;
+exports.AIEngine = void 0;
 // cspell:words lstripBlocks
 const fs_1 = __importDefault(require("fs"));
 const openai_1 = __importDefault(require("openai"));
@@ -12,189 +12,264 @@ const nunjucks_1 = __importDefault(require("nunjucks"));
 const zod_to_json_schema_1 = require("zod-to-json-schema");
 const action_1 = require("./bosun/action");
 const core_1 = require("openai/core");
-function createAIEngine(cfg = {}) {
-    const logger = cfg.logger || globalThis.console;
-    const basePath = cfg.basePath || process.cwd();
-    const tokenStorage = cfg.tokenStorage || {
-        async getToken() {
-            if (process.env.OPENAI_API_KEY) {
-                return process.env.OPENAI_API_KEY;
-            }
-            throw new Error('OpenAI API key is not set');
-        },
-    };
-    function createStep(step) {
-        return step;
-    }
-    function makeMessagesList(messages = []) {
-        let directivesFormatter = (message) => `${message.sender}: ${message.text}`;
-        let proposedFormatter = (message) => `Proposed reply: ${message}`;
-        let proposedReply = null;
-        const names = {
-            agent: 'Agent',
-            user: 'User',
-            system: 'System',
-        };
-        return {
-            toString: (ignoreDirectives = false) => messages
-                .map((msg) => {
-                if (msg.sender === 'system') {
-                    return ignoreDirectives ? null : directivesFormatter(msg);
+var AIEngine;
+(function (AIEngine) {
+    /**
+     * 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);
+     * ```
+     */
+    function createAIEngine(cfg = {}) {
+        const logger = cfg.logger || globalThis.console;
+        const basePath = cfg.basePath || process.cwd();
+        const tokenStorage = cfg.tokenStorage || {
+            async getToken() {
+                if (process.env.OPENAI_API_KEY) {
+                    return process.env.OPENAI_API_KEY;
                 }
-                return `${names[msg.sender]}: ${msg.text}`;
-            })
-                .filter((msg) => msg !== null)
-                .join('\n') + (proposedReply ? `\n${proposedFormatter(proposedReply)}` : ''),
-            addMessage: (sender, text) => messages.push({ sender, text }),
-            addDirective: (message) => {
-                logger.debug(`AI Core: add directive: ${message}`);
-                messages.push({ sender: 'system', text: message });
-            },
-            directiveFormat: (formatter) => {
-                directivesFormatter = formatter;
-            },
-            proposedMessageFormat: (formatter) => {
-                proposedFormatter = formatter;
-            },
-            setProposedReply: (message) => (proposedReply = message),
-            getProposedReply: () => proposedReply,
-            getHistory: () => messages,
-            setUserName: (name) => {
-                names.user = name;
-            },
-            setAgentName: (name) => {
-                names.agent = name;
+                throw new Error('OpenAI API key is not set');
             },
         };
-    }
-    async function createWorkflow(...steps) {
-        const apiKey = await tokenStorage.getToken();
-        let shouldRun = true;
-        let currentStep = 0;
-        let beforeEachCallback = async () => Promise.resolve(null);
-        const attempts = new Map();
-        return {
-            terminate: () => {
-                logger.debug('AI Core: Terminating conversation...');
-                shouldRun = false;
-            },
-            run: async (messages) => {
-                for (; currentStep < steps.length; currentStep++) {
-                    await beforeEachCallback();
-                    const step = steps[currentStep];
-                    if (!shouldRun) {
-                        break;
+        function createStep(step) {
+            return step;
+        }
+        function getConversation(messages = []) {
+            let directivesFormatter = (message) => `${message.sender}: ${message.text}`;
+            let proposedFormatter = (message) => `Proposed reply: ${message}`;
+            let proposedReply = null;
+            const names = {
+                agent: 'Agent',
+                user: 'User',
+                system: 'System',
+            };
+            return {
+                toString: (ignoreDirectives = false) => messages
+                    .map((msg) => {
+                    if (msg.sender === 'system') {
+                        return ignoreDirectives ? null : directivesFormatter(msg);
                     }
-                    if (!step.runIf || (await step.runIf(messages))) {
-                        const action = (0, action_1.makeAction)(cfg.sendAction, 'AI', step.name);
-                        await action('started');
-                        logger.debug(`AI Core: Step: ${step.name}`);
-                        if ('prompt' in step) {
-                            await runStep(step, messages);
+                    return `${names[msg.sender]}: ${msg.text}`;
+                })
+                    .filter((msg) => msg !== null)
+                    .join('\n') +
+                    (proposedReply ? `\n${proposedFormatter(proposedReply)}` : ''),
+                addMessage: (sender, text) => messages.push({ sender, text }),
+                addDirective: (message) => {
+                    logger.debug(`AI Engine: add directive: ${message}`);
+                    messages.push({ sender: 'system', text: message });
+                },
+                setDirectiveFormatter: (formatter) => {
+                    directivesFormatter = formatter;
+                },
+                setProposedMessageFormatter: (formatter) => {
+                    proposedFormatter = formatter;
+                },
+                setProposedReply: (message) => (proposedReply = message),
+                getProposedReply: () => proposedReply,
+                getHistory: () => messages,
+                setUserName: (name) => {
+                    names.user = name;
+                },
+                setAgentName: (name) => {
+                    names.agent = name;
+                },
+            };
+        }
+        async function createWorkflow(...steps) {
+            const apiKey = await tokenStorage.getToken();
+            let shouldRun = true;
+            let currentStep = 0;
+            let beforeEachCallback = async () => Promise.resolve(null);
+            const attempts = new Map();
+            return {
+                terminate: () => {
+                    logger.debug('AI Engine: Terminating conversation...');
+                    shouldRun = false;
+                },
+                run: async (messages) => {
+                    for (; currentStep < steps.length; currentStep++) {
+                        await beforeEachCallback();
+                        const step = steps[currentStep];
+                        if (!shouldRun) {
+                            break;
                         }
-                        else {
-                            await runDumbStep(step);
+                        if (!step.runIf || (await step.runIf(messages))) {
+                            const action = (0, action_1.makeAction)(cfg.sendAction, 'AI', step.name);
+                            await action('started');
+                            logger.debug(`AI Engine: Step: ${step.name}`);
+                            if ('prompt' in step) {
+                                await runStep(step, messages);
+                            }
+                            else {
+                                await runDumbStep(step, messages);
+                            }
+                            await action('completed');
                         }
-                        await action('completed');
                     }
+                    return shouldRun ? messages.getProposedReply() : null;
+                },
+                rewindTo: (step) => {
+                    const index = steps.indexOf(step);
+                    if (index === -1) {
+                        throw new Error(`Step ${step.name} not found`);
+                    }
+                    if (index > currentStep) {
+                        throw new Error(`Cannot rewind to a step ahead of the current step`);
+                    }
+                    currentStep = index - 1; // -1 because it will be incremented in the loop definition
+                },
+                beforeEach(callback) {
+                    beforeEachCallback = callback;
+                },
+            };
+            async function runStep(step, messages) {
+                if (!apiKey) {
+                    throw new Error('OpenAI API key is not set');
                 }
-                return shouldRun ? messages.getProposedReply() : null;
-            },
-            rewindTo: (step) => {
-                const index = steps.indexOf(step);
-                if (index === -1) {
-                    throw new Error(`Step ${step.name} not found`);
+                try {
+                    let response = null;
+                    let prompt = typeof step.prompt === 'string' ? step.prompt : await step.prompt.content();
+                    logger.debug('AI Engine: context', step.context);
+                    logger.debug('AI Engine: messages', messages.toString(step.ignoreDirectives || false));
+                    if (step.context) {
+                        nunjucks_1.default.configure({
+                            autoescape: true,
+                            trimBlocks: true,
+                            lstripBlocks: true,
+                        });
+                        prompt = nunjucks_1.default.renderString(prompt, step.context);
+                    }
+                    response = await runLLM(apiKey, prompt, messages.toString(step.ignoreDirectives || false), step.schema, step.model);
+                    if (!response) {
+                        throw new Error('No response from OpenAI');
+                    }
+                    logger.debug(`AI Engine: response: ${response}`);
+                    if (typeof step.shouldExecute === 'function') {
+                        if (await step.shouldExecute(response)) {
+                            logger.debug(`AI Engine: executing`);
+                            checkAttempts(step);
+                            await step.execute(response);
+                        }
+                        else {
+                            resetAttempts(step);
+                            logger.debug(`AI Engine: skipping`);
+                        }
+                    }
+                    else {
+                        logger.debug(`AI Engine: replying`);
+                        await step.execute(response);
+                    }
                 }
-                if (index > currentStep) {
-                    throw new Error(`Cannot rewind to a step ahead of the current step`);
+                catch (error) {
+                    // FIXME: this doesn't terminate the workflow
+                    await step.onError(error.message);
+                    shouldRun = false;
                 }
-                currentStep = index - 1; // -1 because it will be incremented in the loop definition
-            },
-            beforeEach(callback) {
-                beforeEachCallback = callback;
-            },
-        };
-        async function runStep(step, messages) {
-            if (!apiKey) {
-                throw new Error('OpenAI API key is not set');
             }
-            try {
-                let response = null;
-                let prompt = typeof step.prompt === 'string' ? step.prompt : await step.prompt.content();
-                logger.debug('AI Core: context', step.context);
-                logger.debug('AI Core: messages', messages.toString(step.ignoreDirectives || false));
-                if (step.context) {
-                    nunjucks_1.default.configure({ autoescape: true, trimBlocks: true, lstripBlocks: true });
-                    prompt = nunjucks_1.default.renderString(prompt, step.context);
+            async function runDumbStep(step, messages) {
+                try {
+                    if (!step.runIf || (await step.runIf(messages))) {
+                        await step.execute();
+                    }
                 }
-                response = await runLLM(apiKey, prompt, messages.toString(step.ignoreDirectives || false), step.schema);
-                if (!response) {
-                    throw new Error('No response from OpenAI');
+                catch (error) {
+                    console.error(`AI Engine: error in dumb step ${step.name}: ${error.message}`);
+                    await step.onError(error.message);
+                    shouldRun = false;
                 }
-                logger.debug(`AI Core: response: ${response}`);
-                if (typeof step.shouldExecute === 'function') {
-                    if (await step.shouldExecute(response)) {
-                        logger.debug(`AI Core: executing`);
-                        checkAttempts(step);
-                        await step.execute(response);
+            }
+            function checkAttempts(step) {
+                if (step.maxAttempts) {
+                    if (!attempts.has(step)) {
+                        attempts.set(step, 0);
                     }
-                    else {
-                        resetAttempts(step);
-                        logger.debug(`AI Core: skipping`);
+                    attempts.set(step, attempts.get(step) + 1);
+                    if (attempts.get(step) > step.maxAttempts) {
+                        throw new Error(`Max attempts reached for step ${step.name}`);
                     }
                 }
-                else {
-                    logger.debug(`AI Core: replying`);
-                    await step.execute(response);
-                }
             }
-            catch (error) {
-                // FIXME: this doesn't terminate the workflow
-                await step.onError(error.message);
-                shouldRun = false;
+            function resetAttempts(step) {
+                attempts.set(step, 0);
             }
         }
-        async function runDumbStep(step) {
-            try {
-                if (!step.runIf || (await step.runIf())) {
-                    await step.execute();
-                }
-            }
-            catch (error) {
-                console.error(`AI Core: error in dumb step ${step.name}: ${error.message}`);
-                await step.onError(error.message);
-                shouldRun = false;
+        async function runLLM(apiKey, systemPrompt, messages, schema, model = 'gpt-4o-2024-11-20') {
+            logger.debug('AI Engine: model:', model);
+            logger.debug('----------- RENDERED PROMPT ---------------');
+            logger.debug(systemPrompt);
+            logger.debug('-------------------------------------------');
+            if (apiKey === '__TESTING__') {
+                await (0, core_1.sleep)(100);
+                return schema
+                    ? JSON.stringify({ message: 'canned response', reasons: [] })
+                    : 'canned response';
             }
-        }
-        function checkAttempts(step) {
-            if (step.maxAttempts) {
-                if (!attempts.has(step)) {
-                    attempts.set(step, 0);
-                }
-                attempts.set(step, attempts.get(step) + 1);
-                if (attempts.get(step) > step.maxAttempts) {
-                    throw new Error(`Max attempts reached for step ${step.name}`);
-                }
+            const client = new openai_1.default({ apiKey });
+            const response = await client.chat.completions.create({
+                messages: [
+                    { role: 'system', content: systemPrompt },
+                    { role: 'user', content: messages },
+                ],
+                ...getOpenAiOptions(model, schema),
+            });
+            if (!response.choices[0].message.content) {
+                throw new Error('No response from OpenAI');
             }
+            return response.choices[0].message.content;
         }
-        function resetAttempts(step) {
-            attempts.set(step, 0);
+        function loadFile(path) {
+            // NOTE: there probably will be S3 loading stuff here
+            return {
+                content: async () => {
+                    logger.debug('AI Engine: loading prompt:', path);
+                    return fs_1.default.promises.readFile((0, path_1.join)(basePath, path), 'utf-8');
+                },
+            };
         }
+        return {
+            createWorkflow: createWorkflow,
+            createStep,
+            loadFile,
+            createConversation: getConversation,
+        };
     }
-    async function runLLM(apiKey, systemPrompt, messages, schema) {
-        if (apiKey === '__TESTING__') {
-            await (0, core_1.sleep)(100);
-            return schema
-                ? JSON.stringify({ message: 'canned response', reasons: [] })
-                : 'canned response';
+    AIEngine.createAIEngine = createAIEngine;
+    function getOpenAiOptions(model, schema) {
+        const options = {
+            model,
+        };
+        const isReasoningModel = ['o3-', 'o1-', 'o1-preview-'].some((m) => model.startsWith(m));
+        if (isReasoningModel) {
+            if (!model.startsWith('o1-preview-')) {
+                options.reasoning_effort = 'high';
+            }
+        }
+        else {
+            options.temperature = 0.1;
         }
-        const client = new openai_1.default({ apiKey });
-        logger.log('----------- RENDERED PROMPT ---------------');
-        logger.log(systemPrompt);
-        logger.log('---------------------------------------');
-        let format = { type: 'text' };
         if (schema) {
-            format = {
+            options.response_format = {
                 type: 'json_schema',
                 json_schema: {
                     name: 'detector_response',
@@ -202,33 +277,9 @@ function createAIEngine(cfg = {}) {
                 },
             };
         }
-        const response = await client.chat.completions.create({
-            messages: [
-                { role: 'system', content: systemPrompt },
-                { role: 'user', content: messages },
-            ],
-            model: 'gpt-4o',
-            response_format: format,
-            temperature: 0.1,
-        });
-        if (!response.choices[0].message.content) {
-            throw new Error('No response from OpenAI');
+        else {
+            options.response_format = { type: 'text' };
         }
-        return response.choices[0].message.content;
-    }
-    function loadFile(path) {
-        // NOTE: there probably will be S3 loading stuff here
-        return {
-            content: async () => {
-                logger.debug('AI Core: loading prompt:', path);
-                return fs_1.default.promises.readFile((0, path_1.join)(basePath, path), 'utf-8');
-            },
-        };
+        return options;
     }
-    return {
-        createWorkflow: createWorkflow,
-        createStep,
-        loadFile,
-        makeMessagesList,
-    };
-}
+})(AIEngine || (exports.AIEngine = AIEngine = {}));

package/build/lib/bosun/agent.d.ts

@@ -1,25 +1,46 @@
-import { AiEngine } from '../ai';
-import { Logger, Message, Scheduler } from '../interfaces';
+import { AIEngine } from '../ai';
+import { Logger, Scheduler } from '../interfaces';
 import { SendAction } from './action';
 import { Context } from './context';
-type DefaultContext = Record<string, any>;
-export interface TesAgentFactoryProps<CTX extends DefaultContext = DefaultContext> {
-    logger: Logger;
-    scheduler: Scheduler;
-    ai: AiEngine;
-    getMessages: () => Message[];
-    sendMessage: (message: string) => Promise<void>;
-    sendAction: SendAction;
-    ctx: Context<CTX>;
+/**
+ * Bosun is a UI for testing Recombine AI agents. It enables testing complex agent interactions with multiple steps, error handling, and state management.
+ *
+ * @example
+ * ```typescript
+ * // In workflows.ts
+ * const agents = {
+ *     "testbot": createTestAgentFactory((props) => {
+ *         return {
+ *             start: async () => { ... },
+ *             reactOnMessage: async () => { ... },
+ *             respondToMessage: async () => { ... }
+ *         }
+ *     })
+ * }
+ *
+ * export agents;
+ * ```
+ */
+export declare namespace Bosun {
+    type DefaultContext = Record<string, any>;
+    export interface TesAgentFactoryProps<CTX extends DefaultContext = DefaultContext> {
+        logger: Logger;
+        scheduler: Scheduler.Scheduler;
+        ai: AIEngine.AIEngine;
+        getMessages: () => AIEngine.Message[];
+        sendMessage: (message: string) => Promise<void>;
+        sendAction: SendAction;
+        ctx: Context<CTX>;
+    }
+    export interface TestAgent {
+        start: () => Promise<unknown>;
+        reactOnMessage: () => Promise<unknown>;
+        respondToMessage: () => Promise<unknown>;
+        isAssigned: () => Promise<boolean>;
+        onFatalError: (error: Error) => Promise<unknown>;
+    }
+    export type TestAgentFactory<T extends DefaultContext = DefaultContext> = (props: TesAgentFactoryProps<T>) => TestAgent;
+    export function createTestAgentFactory<T extends DefaultContext>(creator: TestAgentFactory<T>): TestAgentFactory<T>;
+    export {};
 }
-export interface TestAgent {
-    start: () => Promise<unknown>;
-    reactOnMessage: () => Promise<unknown>;
-    respondToMessage: () => Promise<unknown>;
-    isAssigned: () => Promise<boolean>;
-    onFatalError: (error: Error) => Promise<unknown>;
-}
-export type TestAgentFactory<T extends DefaultContext = DefaultContext> = (props: TesAgentFactoryProps<T>) => TestAgent;
-export declare function createTestAgentFactory<T extends DefaultContext>(creator: TestAgentFactory<T>): TestAgentFactory<T>;
-export {};
 //# sourceMappingURL=agent.d.ts.map

package/build/lib/bosun/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/lib/bosun/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AACzC,MAAM,WAAW,oBAAoB,CAAC,GAAG,SAAS,cAAc,GAAG,cAAc;IAC7E,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,SAAS,CAAA;IACpB,EAAE,EAAE,QAAQ,CAAA;IACZ,WAAW,EAAE,MAAM,OAAO,EAAE,CAAA;IAC5B,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,UAAU,EAAE,UAAU,CAAA;IACtB,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAA;CACpB;AAED,MAAM,WAAW,SAAS;IACtB,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IAC7B,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACtC,gBAAgB,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACxC,UAAU,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IAClC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACnD;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI,CACtE,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAC7B,SAAS,CAAA;AAEd,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,cAAc,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,uBAE5F"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/lib/bosun/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC;;;;;;;;;;;;;;;;;;GAkBG;AACH,yBAAiB,KAAK,CAAA;IAClB,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACzC,MAAM,WAAW,oBAAoB,CAAC,GAAG,SAAS,cAAc,GAAG,cAAc;QAC7E,MAAM,EAAE,MAAM,CAAA;QACd,SAAS,EAAE,SAAS,CAAC,SAAS,CAAA;QAC9B,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAA;QACrB,WAAW,EAAE,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAA;QACrC,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QAC/C,UAAU,EAAE,UAAU,CAAA;QACtB,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAA;KACpB;IAED,MAAM,WAAW,SAAS;QACtB,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;QAC7B,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;QACtC,gBAAgB,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;QACxC,UAAU,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;QAClC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;KACnD;IAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI,CACtE,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAC7B,SAAS,CAAA;IAEd,MAAM,UAAU,sBAAsB,CAAC,CAAC,SAAS,cAAc,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,uBAE5F;;CAEJ"}

package/build/lib/bosun/agent.js

@@ -1,6 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTestAgentFactory = createTestAgentFactory;
-function createTestAgentFactory(creator) {
-    return creator;
-}
+exports.Bosun = void 0;
+/**
+ * Bosun is a UI for testing Recombine AI agents. It enables testing complex agent interactions with multiple steps, error handling, and state management.
+ *
+ * @example
+ * ```typescript
+ * // In workflows.ts
+ * const agents = {
+ *     "testbot": createTestAgentFactory((props) => {
+ *         return {
+ *             start: async () => { ... },
+ *             reactOnMessage: async () => { ... },
+ *             respondToMessage: async () => { ... }
+ *         }
+ *     })
+ * }
+ *
+ * export agents;
+ * ```
+ */
+var Bosun;
+(function (Bosun) {
+    function createTestAgentFactory(creator) {
+        return creator;
+    }
+    Bosun.createTestAgentFactory = createTestAgentFactory;
+})(Bosun || (exports.Bosun = Bosun = {}));

package/build/lib/interfaces.d.ts

@@ -3,30 +3,26 @@ export interface Logger {
     debug: (...args: any[]) => void;
     error: (...args: any[]) => void;
 }
-/**
- * A function that schedules an action to be executed in the future
- * @param delay – a date when the action should be executed use {@link delayFactory} to create a
- * date
- * @param phone – user's phone
- */
-type ScheduleAction = (delay: Date, phone: string) => Promise<void>;
-export interface Scheduler {
+export declare namespace Scheduler {
     /**
-     * Register a delayed action handler.
-     * @param actionName – a unique (inside one use-case) name for the action
-     * @param action – a function that will be called when the action is triggered
-     * @returns a function to schedule the action
+     * A function that schedules an action to be executed in the future
+     * @param delay – a date when the action should be executed use {@link delayFactory} to create a
+     * date
+     * @param phone – user's phone
      */
-    registerAction: (actionName: string, action: (phone: string) => Promise<unknown>) => ScheduleAction;
-    /**
-     * Removes all actions for the given phone that were not executed yet.
-     */
-    clearAllPendingActions: (phone: string) => Promise<unknown>;
-}
-export interface Message {
-    sender: 'user' | 'agent' | 'system';
-    text: string;
-    imageUrl?: string;
+    type ScheduleAction = (delay: Date, phone: string) => Promise<void>;
+    interface Scheduler {
+        /**
+         * Register a delayed action handler.
+         * @param actionName – a unique (inside one use-case) name for the action
+         * @param action – a function that will be called when the action is triggered
+         * @returns a function to schedule the action
+         */
+        registerAction: (actionName: string, action: (phone: string) => Promise<unknown>) => ScheduleAction;
+        /**
+         * Removes all actions for the given phone that were not executed yet.
+         */
+        clearAllPendingActions: (phone: string) => Promise<unknown>;
+    }
 }
-export {};
 //# sourceMappingURL=interfaces.d.ts.map

package/build/lib/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/lib/interfaces.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACnB,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC7B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC/B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;CAClC;AAED;;;;;GAKG;AACH,KAAK,cAAc,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAEnE,MAAM,WAAW,SAAS;IACtB;;;;;OAKG;IACH,cAAc,EAAE,CACZ,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,KAC1C,cAAc,CAAA;IAEnB;;OAEG;IACH,sBAAsB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC9D;AAED,MAAM,WAAW,OAAO;IACpB,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/lib/interfaces.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACnB,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC7B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC/B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;CAClC;AAED,yBAAiB,SAAS,CAAC;IACvB;;;;;OAKG;IACH,KAAY,cAAc,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1E,UAAiB,SAAS;QACtB;;;;;WAKG;QACH,cAAc,EAAE,CACZ,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,KAC1C,cAAc,CAAA;QAEnB;;WAEG;QACH,sBAAsB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;KAC9D;CACJ"}

package/changelog.md

@@ -0,0 +1,11 @@
+# Changelog
+
+### 0.2.0 → 0.3.0 (unstable)
+
+Breaking changes:
+
+-   Break down the library into namespace: AIEngine, Scheduler
+-   Models → BasicModel
+-   Step → LLMStep & ProgrammaticStep
+-   makeMessagesList → getConversation
+-   Deprecation of shouldExecute (discouraged to use if there's no `maxAttempts` in a step)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@recombine-ai/engine",
-    "version": "0.1.1",
+    "version": "0.3.0",
     "description": "Recombine AI engine for creating conversational AI agents",
     "main": "build/index.js",
     "types": "build/index.d.ts",
@@ -11,7 +11,8 @@
         "dev": "tsc -w",
         "build": "tsc",
         "prepublishOnly": "npm run build",
-        "test": "vitest"
+        "test": "vitest",
+        "docs": "cd docusaurus && yarn build --out-dir ../docs && cd .."
     },
     "devDependencies": {
         "@types/node": "^22.8.1",
@@ -23,7 +24,7 @@
     "dependencies": {
         "nunjucks": "^3.2.4",
         "openai": "^4.68.4",
-        "zod": "^3.23.8",
+        "zod": "3.23.8",
         "zod-to-json-schema": "^3.23.5"
     }
 }

package/readme.md

@@ -17,7 +17,7 @@ A TypeScript library for building agentic workflows for conversational AI.
 ## Installation
 
 ```sh
-npm install @recombine/ai-engine
+npm install @recombine-ai/engine
 ```
 
 ## Basic Usage