@recombine-ai/engine 0.4.0 → 0.6.0

package/build/lib/ai.d.ts

@@ -5,8 +5,8 @@ export declare namespace AIEngine {
     /**
      * Represents a basic model name for LLMs.
      */
-    type BasicModel = 'o3-mini-2025-01-31' | 'o1-preview-2024-09-12' | 'gpt-4o-2024-11-20' | 'o1-2024-12-17' | (string & {});
-    interface ProgrammaticStep {
+    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 */
@@ -16,7 +16,7 @@ export declare namespace AIEngine {
         /** Error handler called if an error occurred during in `execute` function */
         onError: (error: string) => Promise<unknown>;
     }
-    interface LLMStep {
+    export interface LLMStep {
         /** Step name for debugging */
         name: string;
         /** Determines if the step should be run or not */
@@ -29,12 +29,16 @@ export declare namespace AIEngine {
          */
         prompt: string | File;
         /**
-         * Schema for structured LLM output using {@link zod https://zod.dev/}
-         * library.
+         * 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.
          */
-        schema?: ZodSchema;
-        /** Exclude directives from message history passed to the LLM for this step */
-        ignoreDirectives?: boolean;
+        json: boolean | ZodSchema;
+        /**
+         * Do not put messages that were added via {@link Conversation.addMessage} into the prompt.
+         */
+        ignoreAddedMessages?: boolean;
         /**
          * Additional data to be inserted into the prompt. Accessible via Nunjucks variables.
          * @example
@@ -78,15 +82,16 @@ export declare namespace AIEngine {
     /**
      * 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.
      */
-    type StepTrace = {
+    export type StepTrace = {
         renderedPrompt?: string;
         receivedContext?: Record<string, unknown>;
         receivedPrompt?: string;
+        stringifiedConversation?: string;
     };
     /**
      * An AI workflow composed of steps.
      */
-    interface Workflow {
+    export interface Workflow {
         /**
          * Terminates the workflow, preventing further steps from being executed.
          */
@@ -165,7 +170,7 @@ export declare namespace AIEngine {
      * console.log(response)
      * ```
      */
-    interface AIEngine {
+    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.
@@ -190,6 +195,13 @@ export declare namespace AIEngine {
          * @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;
     }
     /**
      * Represents a conversation between a user and an AI agent.
@@ -215,7 +227,7 @@ export declare namespace AIEngine {
      * // System: Ask for account details
      * ```
      */
-    interface Conversation {
+    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.
@@ -227,36 +239,26 @@ export declare namespace AIEngine {
          */
         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.
+         * Sets the default formatter for stringifying messages when toString is called.
+         * @param formatter - A function that takes a message and returns a formatted string.
          */
-        toString: (ignoreDirectives?: boolean) => string;
+        setDefaultFormatter: (formatter: (message: Message) => string) => void;
         /**
-         * Adds a directive message to the conversation.
-         * @param message - The directive message to add.
+         * 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
-         * ```
-         * // 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
-         * ```
+         * @returns The string representation of the conversation.
          */
-        addDirective: (message: string) => void;
+        toString: (options?: {
+            ignoreAddedMessages?: boolean;
+        }) => string;
         /**
          * 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.
+         * @param message - The message to add to the conversation.
          */
-        setDirectiveFormatter: (formatter: (message: Message) => string) => void;
+        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.
@@ -274,6 +276,7 @@ export declare namespace AIEngine {
         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[];
@@ -282,7 +285,7 @@ export declare namespace AIEngine {
      * 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 {
+    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 */
@@ -290,13 +293,13 @@ export declare namespace AIEngine {
         /** Optional URL of an image associated with the message */
         imageUrl?: string;
     }
-    interface File {
+    export interface File {
         content: () => Promise<string>;
     }
     /**
      * Configuration options for the Engine.
      */
-    interface EngineConfig {
+    export interface EngineConfig {
         /**
          * Optional token storage object that provides access to authentication tokens.
          * @property {object} tokenStorage - Object containing method to retrieve token.
@@ -344,6 +347,9 @@ export declare namespace AIEngine {
      * const reply = await workflow.run(conversation);
      * ```
      */
-    function createAIEngine(cfg?: EngineConfig): AIEngine;
+    export function createAIEngine(cfg?: EngineConfig): AIEngine;
+    function renderPrompt(prompt: string, context?: Record<string, unknown>): string;
+    export function createConversation(initialMessages?: Message[]): Conversation;
+    export {};
 }
 //# 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":"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"}
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/lib/ai.ts"],"names":[],"mappings":"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"}

package/build/lib/ai.js

@@ -54,48 +54,6 @@ var AIEngine;
         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);
-                    }
-                    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;
@@ -164,15 +122,12 @@ var AIEngine;
                     let prompt = typeof step.prompt === 'string' ? step.prompt : await step.prompt.content();
                     stepTrace.receivedPrompt = prompt;
                     logger.debug('AI Engine: context', step.context);
-                    logger.debug('AI Engine: messages', messages.toString(step.ignoreDirectives || false));
-                    nunjucks_1.default.configure({
-                        autoescape: true,
-                        trimBlocks: true,
-                        lstripBlocks: true,
-                    });
-                    prompt = nunjucks_1.default.renderString(prompt, step.context || {});
+                    logger.debug('AI Engine: messages', messages.toString({ ignoreAddedMessages: step.ignoreAddedMessages }));
+                    prompt = renderPrompt(prompt, step.context);
                     stepTrace.renderedPrompt = prompt;
-                    response = await runLLM(apiKey, prompt, messages.toString(step.ignoreDirectives || false), step.schema, step.model);
+                    const stringifiedMessages = messages.toString({ ignoreAddedMessages: step.ignoreAddedMessages });
+                    stepTrace.stringifiedConversation = stringifiedMessages;
+                    response = await runLLM(apiKey, prompt, stringifiedMessages, step.json, step.model);
                     if (!response) {
                         throw new Error('No response from OpenAI');
                     }
@@ -228,16 +183,17 @@ var AIEngine;
                 attempts.set(step, 0);
             }
         }
-        async function runLLM(apiKey, systemPrompt, messages, schema, model = 'gpt-4o-2024-08-06') {
+        async function runLLM(apiKey, systemPrompt, messages, json, model = 'gpt-4o-2024-08-06') {
             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';
+                if (typeof json === 'boolean') {
+                    return json ? JSON.stringify({ message: 'canned response', reasons: [] }) : 'canned response';
+                }
+                return JSON.stringify({ message: 'canned response', reasons: [] });
             }
             const client = new openai_1.default({ apiKey });
             const response = await client.chat.completions.create({
@@ -245,7 +201,7 @@ var AIEngine;
                     { role: 'system', content: systemPrompt },
                     { role: 'user', content: messages },
                 ],
-                ...getOpenAiOptions(model, schema),
+                ...getOpenAiOptions(model, json),
             });
             if (!response.choices[0].message.content) {
                 throw new Error('No response from OpenAI');
@@ -265,11 +221,12 @@ var AIEngine;
             createWorkflow: createWorkflow,
             createStep,
             loadFile,
-            createConversation: getConversation,
+            createConversation,
+            renderPrompt
         };
     }
     AIEngine.createAIEngine = createAIEngine;
-    function getOpenAiOptions(model, schema) {
+    function getOpenAiOptions(model, json) {
         const options = {
             model,
         };
@@ -282,18 +239,79 @@ var AIEngine;
         else {
             options.temperature = 0.1;
         }
-        if (schema) {
+        if (typeof json !== 'boolean') {
             options.response_format = {
                 type: 'json_schema',
                 json_schema: {
                     name: 'detector_response',
-                    schema: (0, zod_to_json_schema_1.zodToJsonSchema)(schema),
+                    schema: (0, zod_to_json_schema_1.zodToJsonSchema)(json),
                 },
             };
         }
+        else if (json) {
+            options.response_format = { type: 'json_object' };
+        }
         else {
             options.response_format = { type: 'text' };
         }
         return options;
     }
+    function renderPrompt(prompt, context) {
+        nunjucks_1.default.configure({
+            autoescape: false,
+            trimBlocks: true,
+            lstripBlocks: true,
+        });
+        return nunjucks_1.default.renderString(prompt, context || {});
+    }
+    function createConversation(initialMessages = []) {
+        const messages = initialMessages.map((msg) => ({
+            ...msg,
+            isAddedMessage: false,
+            formatter: undefined
+        }));
+        const names = {
+            agent: 'Agent',
+            user: 'User',
+            system: 'System',
+        };
+        let defaultFormatter = (message) => `${names[message.sender]}: ${message.text}`;
+        let proposedFormatter = (message) => `Proposed reply: ${message}`;
+        let proposedReply = null;
+        return {
+            toString: (options) => {
+                return messages
+                    .filter((msg) => !options?.ignoreAddedMessages || !msg.isAddedMessage)
+                    .map((msg) => {
+                    return msg.formatter ? msg.formatter(msg) : defaultFormatter(msg);
+                })
+                    .filter((msg) => msg !== null)
+                    .join('\n') +
+                    (proposedReply ? `\n${proposedFormatter(proposedReply)}` : '');
+            },
+            addMessage: (message, opts) => {
+                messages.push({
+                    ...message,
+                    isAddedMessage: true,
+                    formatter: opts?.formatter ?? defaultFormatter,
+                });
+            },
+            setDefaultFormatter: (formatter) => {
+                defaultFormatter = formatter;
+            },
+            setProposedMessageFormatter: (formatter) => {
+                proposedFormatter = formatter;
+            },
+            setProposedReply: (message) => (proposedReply = message),
+            getProposedReply: () => proposedReply,
+            getHistory: () => messages,
+            setUserName: (name) => {
+                names.user = name;
+            },
+            setAgentName: (name) => {
+                names.agent = name;
+            }
+        };
+    }
+    AIEngine.createConversation = createConversation;
 })(AIEngine || (exports.AIEngine = AIEngine = {}));

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

@@ -28,7 +28,7 @@ export declare namespace Bosun {
         scheduler: Scheduler.Scheduler;
         ai: AIEngine.AIEngine;
         getMessages: () => AIEngine.Message[];
-        sendMessage: (message: string) => Promise<void>;
+        sendMessage: (message: string | AIEngine.Message) => Promise<void>;
         sendAction: SendAction;
         ctx: Context<CTX>;
     }

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,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"}
+{"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,GAAG,QAAQ,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QAClE,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/changelog.md

@@ -1,6 +1,30 @@
 # Changelog
 
-### 0.3.2 → 0.4.o (unstable)
+### 0.5.0 → 0.6.0 (unstable)
+
+Breaking changes:
+
+-   addDirective is removed. Use addMessage with role: 'system' instead.
+-   ignoreDirectives → ignoreAddedMessages
+
+Other changes:
+
+-   AIEngine.sendMessage now accepts "Message" rather than a string
+
+### 0.4.0 → 0.5.0 (unstable)
+
+Breaking changes:
+
+-   `schema` property replaced with `json` which can be boolean,
+-   `setDirectiveFormatter` →
+
+Other changes:
+
+-   `renderPrompt` method added
+-   `addDirective` accepts optional formatter function
+-   `formatter` optional method added to `Message`
+
+### 0.3.2 → 0.4.0 (unstable)
 
 Breaking changes:
 
@@ -22,7 +46,7 @@ Breaking changes:
 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)
+-   `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.4.0",
+    "version": "0.6.0",
     "description": "Recombine AI engine for creating conversational AI agents",
     "main": "build/index.js",
     "types": "build/index.d.ts",
@@ -18,13 +18,13 @@
         "@types/node": "^22.8.1",
         "@types/nunjucks": "^3.2.6",
         "prettier": "^3.3.3",
-        "typescript": "^5.7.3",
+        "typescript": "^5.8.3",
         "vitest": "^3.0.6"
     },
     "dependencies": {
         "nunjucks": "^3.2.4",
         "openai": "^4.68.4",
         "zod": "3.23.8",
-        "zod-to-json-schema": "^3.23.5"
+        "zod-to-json-schema": "^3.24.6"
     }
 }