@recombine-ai/engine 0.3.2 → 0.5.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,10 +29,12 @@ 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;
+        json: boolean | ZodSchema;
         /** Exclude directives from message history passed to the LLM for this step */
         ignoreDirectives?: boolean;
         /**
@@ -75,10 +77,19 @@ export declare namespace AIEngine {
         /** Error handler called if an error occurred during LLM API call or in `execute` function */
         onError: (error: string) => Promise<unknown>;
     }
+    /**
+     * 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.
+     */
+    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.
          */
@@ -89,7 +100,12 @@ export declare namespace AIEngine {
          * @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>;
+        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
@@ -152,7 +168,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.
@@ -177,6 +193,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.
@@ -202,7 +225,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.
@@ -232,7 +255,7 @@ export declare namespace AIEngine {
          * // System: Ask the user for their preferred date and time for the reservation
          * ```
          */
-        addDirective: (message: string) => void;
+        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.
@@ -243,7 +266,7 @@ export declare namespace AIEngine {
          * 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;
+        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.
@@ -269,21 +292,22 @@ 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 */
         text: string;
         /** Optional URL of an image associated with the message */
         imageUrl?: string;
+        formatter?: (message: Message) => 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.
@@ -331,6 +355,8 @@ 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 {};
 }
 //# 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

@@ -55,7 +55,7 @@ var AIEngine;
             return step;
         }
         function getConversation(messages = []) {
-            let directivesFormatter = (message) => `${message.sender}: ${message.text}`;
+            let defaultDirectivesFormatter = (message) => `${message.sender}: ${message.text}`;
             let proposedFormatter = (message) => `Proposed reply: ${message}`;
             let proposedReply = null;
             const names = {
@@ -67,7 +67,8 @@ var AIEngine;
                 toString: (ignoreDirectives = false) => messages
                     .map((msg) => {
                     if (msg.sender === 'system') {
-                        return ignoreDirectives ? null : directivesFormatter(msg);
+                        logger.debug('formatter', msg.formatter);
+                        return ignoreDirectives ? null : (msg.formatter ? msg.formatter(msg) : defaultDirectivesFormatter(msg));
                     }
                     return `${names[msg.sender]}: ${msg.text}`;
                 })
@@ -75,12 +76,12 @@ var AIEngine;
                     .join('\n') +
                     (proposedReply ? `\n${proposedFormatter(proposedReply)}` : ''),
                 addMessage: (sender, text) => messages.push({ sender, text }),
-                addDirective: (message) => {
+                addDirective: (message, formatter) => {
                     logger.debug(`AI Engine: add directive: ${message}`);
-                    messages.push({ sender: 'system', text: message });
+                    messages.push({ sender: 'system', text: message, formatter });
                 },
-                setDirectiveFormatter: (formatter) => {
-                    directivesFormatter = formatter;
+                setDefaultDirectiveFormatter: (formatter) => {
+                    defaultDirectivesFormatter = formatter;
                 },
                 setProposedMessageFormatter: (formatter) => {
                     proposedFormatter = formatter;
@@ -102,6 +103,12 @@ var AIEngine;
             let currentStep = 0;
             let beforeEachCallback = async () => Promise.resolve(null);
             const attempts = new Map();
+            const trace = {
+                steps: steps.reduce((acc, step) => {
+                    acc[step.name] = {};
+                    return acc;
+                }, {})
+            };
             return {
                 terminate: () => {
                     logger.debug('AI Engine: Terminating conversation...');
@@ -119,7 +126,8 @@ var AIEngine;
                             await action('started');
                             logger.debug(`AI Engine: Step: ${step.name}`);
                             if ('prompt' in step) {
-                                await runStep(step, messages);
+                                const stepTrace = await runStep(step, messages);
+                                trace.steps[step.name] = stepTrace;
                             }
                             else {
                                 await runDumbStep(step, messages);
@@ -127,7 +135,10 @@ var AIEngine;
                             await action('completed');
                         }
                     }
-                    return shouldRun ? messages.getProposedReply() : null;
+                    return {
+                        reply: shouldRun ? messages.getProposedReply() : null,
+                        trace
+                    };
                 },
                 rewindTo: (step) => {
                     const index = steps.indexOf(step);
@@ -147,20 +158,19 @@ var AIEngine;
                 if (!apiKey) {
                     throw new Error('OpenAI API key is not set');
                 }
+                const stepTrace = {};
                 try {
+                    stepTrace.receivedContext = step.context;
                     let response = null;
                     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));
-                    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);
+                    prompt = renderPrompt(prompt, step.context);
+                    stepTrace.renderedPrompt = prompt;
+                    const stringifiedMessages = messages.toString(step.ignoreDirectives || false);
+                    stepTrace.stringifiedConversation = stringifiedMessages;
+                    response = await runLLM(apiKey, prompt, stringifiedMessages, step.json, step.model);
                     if (!response) {
                         throw new Error('No response from OpenAI');
                     }
@@ -180,11 +190,13 @@ var AIEngine;
                         logger.debug(`AI Engine: replying`);
                         await step.execute(response);
                     }
+                    return stepTrace;
                 }
                 catch (error) {
                     // FIXME: this doesn't terminate the workflow
                     await step.onError(error.message);
                     shouldRun = false;
+                    return stepTrace;
                 }
             }
             async function runDumbStep(step, messages) {
@@ -214,16 +226,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({
@@ -231,7 +244,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');
@@ -252,10 +265,11 @@ var AIEngine;
             createStep,
             loadFile,
             createConversation: getConversation,
+            renderPrompt
         };
     }
     AIEngine.createAIEngine = createAIEngine;
-    function getOpenAiOptions(model, schema) {
+    function getOpenAiOptions(model, json) {
         const options = {
             model,
         };
@@ -268,18 +282,29 @@ 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 || {});
+    }
 })(AIEngine || (exports.AIEngine = AIEngine = {}));

package/changelog.md

@@ -1,5 +1,24 @@
 # Changelog
 
+### 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:
+
+-   `await workflow.run()` now returns an object with `reply: string` and `trace` object
+
 ### 0.3.1 → 0.3.2 (unstable)
 
 -   add `ScheduleQuery` class that provides three additional capabilities compared to `delayFactory`:
@@ -16,7 +35,7 @@
 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.3.2",
+    "version": "0.5.0",
     "description": "Recombine AI engine for creating conversational AI agents",
     "main": "build/index.js",
     "types": "build/index.d.ts",

package/readme.md

@@ -60,7 +60,7 @@ const myCoordinator = engine.createStep({
 
 // Create and run workflow
 const workflow = await engine.createWorkflow(mainStep, myReviewer, myCoordinator)
-const response = await workflow.run(messages)
+const { reply, trace } = await workflow.run(messages)
 ```
 
 ## Main concepts