@recombine-ai/engine 1.0.0-beta-1 → 1.0.0-beta-3

package/.github/workflows/linting.yml

@@ -1,4 +1,4 @@
-name: lint & typecheck
+name: lint & test
 
 on:
     push:
@@ -20,7 +20,7 @@ jobs:
                   cache: 'npm'
 
             - name: Install dependencies
-              run: npm ci --legacy-peer-deps
+              run: npm ci
 
             - name: Run lint
               run: npm run lint --silent

package/.github/workflows/publish.yml

@@ -33,8 +33,7 @@ jobs:
               run: npm install -g npm@latest
 
             - name: 'Install dependencies'
-              # TODO rm --legacy-peer-deps as soon as zod stuff fixed
-              run: npm ci --legacy-peer-deps
+              run: npm ci
 
             - name: 'Build'
               run: npm run build

package/build/index.d.ts

@@ -1,7 +1,7 @@
-export * from './lib/ai';
+export * from './lib/interfaces/index';
+export * from './lib/engine';
 export * from './lib/stream';
 export * from './lib/schedule';
-export * from './lib/interfaces';
 export * from './lib/bosun';
 export * from './lib/prompt-fs';
 export * from './lib/llm-adapters';

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA;AAExB,cAAc,cAAc,CAAA;AAE5B,cAAc,gBAAgB,CAAA;AAE9B,cAAc,kBAAkB,CAAA;AAEhC,cAAc,aAAa,CAAA;AAE3B,cAAc,iBAAiB,CAAA;AAE/B,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,wBAAwB,CAAA;AAEtC,cAAc,cAAc,CAAA;AAE5B,cAAc,cAAc,CAAA;AAE5B,cAAc,gBAAgB,CAAA;AAE9B,cAAc,aAAa,CAAA;AAE3B,cAAc,iBAAiB,CAAA;AAE/B,cAAc,oBAAoB,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 });
-__exportStar(require("./lib/ai"), exports);
+// Hmm.. why it should be /index explicitly?
+__exportStar(require("./lib/interfaces/index"), exports);
+__exportStar(require("./lib/engine"), exports);
 __exportStar(require("./lib/stream"), exports);
 __exportStar(require("./lib/schedule"), exports);
-__exportStar(require("./lib/interfaces"), exports);
 __exportStar(require("./lib/bosun"), exports);
 __exportStar(require("./lib/prompt-fs"), exports);
 __exportStar(require("./lib/llm-adapters"), exports);

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

@@ -1 +1 @@
-{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../../src/lib/bosun/action.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACnB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAA;IACzC,OAAO,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE1D,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,IAEhD,SAAS,MAAM,EACf,MAAM,MAAM,EACZ,QAAQ,MAAM,OAAO,CAAC,OAAO,CAAC,mBAiBrC;AAED,wBAAgB,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAM1D,MAAM,CAAC,OAAO,CAAC,mBAQhD"}
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../../src/lib/bosun/action.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,MAAM;IACnB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAA;IACzC,OAAO,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE1D,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,IAEhD,SAAS,MAAM,EACf,MAAM,MAAM,EACZ,QAAQ,MAAM,OAAO,CAAC,OAAO,CAAC,mBAiBrC;AAED,wBAAgB,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAM1D,MAAM,CAAC,OAAO,CAAC,mBAQhD"}

package/build/lib/bosun/action.js

@@ -1,4 +1,5 @@
 "use strict";
+// TODO drop this!
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeActionWrapper = makeActionWrapper;
 exports.makeAction = makeAction;

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

@@ -1,6 +1,4 @@
-import { Message } from '../ai';
-import { Logger, Scheduler } from '../interfaces';
-import { SendAction } from './action';
+import { Logger, Message, Scheduler } from '../interfaces';
 import { Context } from './context';
 import { StepRegistry } from './step-registry';
 import { StepTracer } from './step-tracer';
@@ -46,7 +44,6 @@ export interface TestAgentFactoryProps<CTX extends DefaultContext = DefaultConte
     scheduler: Scheduler;
     getMessages: () => Message[];
     sendMessage: (message: string | Message) => Promise<void>;
-    sendAction: SendAction;
     ctx: Context<CTX>;
 }
 export interface TestTextAgent {

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,OAAO,EAAE,MAAM,OAAO,CAAA;AAC/B,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;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAA;AAE9D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AACzC,MAAM,WAAW,qBAAqB,CAAC,GAAG,SAAS,cAAc,GAAG,cAAc;IAC9E,YAAY,EAAE,YAAY,CAAA;IAC1B;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAA;IAC3C,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,SAAS,CAAA;IACpB,WAAW,EAAE,MAAM,OAAO,EAAE,CAAA;IAC5B,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACzD,UAAU,EAAE,UAAU,CAAA;IACtB,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAA;CACpB;AAED,MAAM,WAAW,aAAa;IAC1B,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;AACD,MAAM,WAAW,cAAc;IAC3B,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACtC,SAAS,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACjC,WAAW,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACnC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAEhD,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;CACvC;AAED,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,cAAc,CAAA;AAEtD,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI,CACtE,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAC9B,OAAO,CAAC,SAAS,CAAC,CAAA;AAEvB,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,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAA;AAE9D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AACzC,MAAM,WAAW,qBAAqB,CAAC,GAAG,SAAS,cAAc,GAAG,cAAc;IAC9E,YAAY,EAAE,YAAY,CAAA;IAC1B;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAA;IAC3C,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,SAAS,CAAA;IACpB,WAAW,EAAE,MAAM,OAAO,EAAE,CAAA;IAC5B,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACzD,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAA;CACpB;AAED,MAAM,WAAW,aAAa;IAC1B,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;AACD,MAAM,WAAW,cAAc;IAC3B,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACtC,SAAS,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACjC,WAAW,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACnC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAEhD,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;CACvC;AAED,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,cAAc,CAAA;AAEtD,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI,CACtE,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAC9B,OAAO,CAAC,SAAS,CAAC,CAAA;AAEvB,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,cAAc,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,uBAE5F"}

package/build/lib/engine.d.ts

@@ -0,0 +1,31 @@
+import { Conversation, Message, StepBuilder } from './interfaces';
+import { AIEngine, EngineConfig } from './interfaces/engine';
+/**
+ * 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,
+ * });
+ *
+ * const workflow = await engine.createWorkflow(
+ *   engine.createStep({
+ *     name: 'generate-response',
+ *     prompt: engine.loadFile('prompts/response.txt'),
+ *     execute: (response) => conversation.setProposedReply(response)
+ *   })
+ * );
+ *
+ * const reply = await workflow.run(conversation);
+ * ```
+ */
+export declare function createAIEngine<CTX extends object>(cfg?: EngineConfig): AIEngine<CTX>;
+export declare function createConversation(initialMessages?: Message[]): Conversation;
+export declare function getStepBuilder<CTX = unknown>(): StepBuilder<CTX>;
+//# sourceMappingURL=engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/lib/engine.ts"],"names":[],"mappings":"AAIA,OAAO,EAEH,YAAY,EAGZ,OAAO,EAEP,WAAW,EAKd,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAG5D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,GAAG,SAAS,MAAM,EAAE,GAAG,GAAE,YAAiB,GAAG,QAAQ,CAAC,GAAG,CAAC,CA+NxF;AAuDD,wBAAgB,kBAAkB,CAAC,eAAe,GAAE,OAAO,EAAO,GAAG,YAAY,CA2ChF;AAED,wBAAgB,cAAc,CAAC,GAAG,GAAG,OAAO,KAAK,WAAW,CAAC,GAAG,CAAC,CAEhE"}

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

@@ -0,0 +1,13 @@
+import * as Zod from 'zod';
+export interface LlmAdapter {
+    /**
+     * @param systemPrompt - rendered system prompt
+     * @param messages - stringified {@link Conversation}
+     * @param schema - optional Zod schema to pass to the model. Will overwrite any schema set in adapter options.
+     * @returns LLM Response
+     */
+    generateResponse: (systemPrompt: string, messages: string, schema?: Zod.ZodType) => Promise<string>;
+    /** Returns adapter's configuration/options for tracing */
+    getOptions: () => unknown;
+}
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/lib/interfaces/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,KAAK,CAAA;AAE1B,MAAM,WAAW,UAAU;IACvB;;;;;OAKG;IACH,gBAAgB,EAAE,CACd,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,GAAG,CAAC,OAAO,KACnB,OAAO,CAAC,MAAM,CAAC,CAAA;IACpB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,OAAO,CAAA;CAC5B"}

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

@@ -0,0 +1 @@
+//# sourceMappingURL=ai.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../../src/lib/interfaces/ai.ts"],"names":[],"mappings":""}

package/build/lib/interfaces/ai.js

@@ -0,0 +1 @@
+"use strict";

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

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+export interface Conversation {
+    /**
+     * Sets the default formatter to stringify messages when toString is called.
+     * @param formatter - A function that takes a message and returns a formatted string.
+     */
+    setDefaultFormatter: (formatter: (message: Message) => string) => void;
+    /**
+     * Converts the conversation to a string representation to be fed to an LLM.
+     * @param filter - A function that filters messages based on certain criteria.
+     * @example
+     * @returns The string representation of the conversation.
+     */
+    toString: (options?: {
+        ignoreAddedMessages?: boolean;
+    }) => string;
+    /**
+     * Adds a message from a specified sender to the conversation.
+     * @param message - The message to add to the conversation.
+     */
+    addMessage: (message: Message, opts?: {
+        formatter?: (message: Message) => string;
+    }) => void;
+    /**
+     * Sets a custom formatter for proposed messages.
+     * @param formatter - A function that takes a message string and returns a formatted string.
+     */
+    setProposedMessageFormatter: (formatter: (message: string) => string) => void;
+    /**
+     * Sets a proposed reply message.
+     * @param message - The proposed reply message.
+     */
+    setProposedReply: (message: string) => void;
+    /**
+     * Gets the current proposed reply message.
+     * @returns The proposed reply message, or null if none exists.
+     */
+    getProposedReply: () => string | null;
+    /**
+     * Gets the history of all messages in the conversation. Returns {@link Message} rather than
+     * {@link ConversationMessage} because none of the {@link ConversationMessage} properties should
+     * be accessed outside of the {@link Conversation} context.
+     * @returns An array of Message objects representing the conversation history.
+     */
+    getHistory: () => Message[];
+}
+/**
+ * Represents a message in a conversation between a user and an agent, or a system message.
+ * Messages can contain text and optionally an image URL. To be used in the {@link Conversation} interface.
+ */
+export interface Message {
+    /** The sender of the message, which can be one of the following: 'user', 'agent', or 'system' */
+    sender: 'user' | 'agent' | 'system';
+    /** The text content of the message */
+    text: string;
+    /** Optional URL of an image associated with the message */
+    imageUrl?: string;
+}
+//# sourceMappingURL=conversation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../../../src/lib/interfaces/conversation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IACzB;;;OAGG;IACH,mBAAmB,EAAE,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,KAAK,IAAI,CAAA;IAEtE;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,mBAAmB,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,MAAM,CAAA;IAEjE;;;OAGG;IACH,UAAU,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;IAE3F;;;OAGG;IACH,2BAA2B,EAAE,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,KAAK,IAAI,CAAA;IAE7E;;;OAGG;IACH,gBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAE3C;;;OAGG;IACH,gBAAgB,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IAErC;;;;;OAKG;IACH,UAAU,EAAE,MAAM,OAAO,EAAE,CAAA;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACpB,iGAAiG;IACjG,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;IACnC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB"}

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

@@ -0,0 +1,65 @@
+import { Environment } from 'nunjucks';
+import { StepRegistry, StepTracer } from '../bosun';
+import { Conversation, Message } from './conversation';
+import { Logger } from './other';
+import { StepBuilder } from './steps';
+import { Workflow, WorkflowConfig } from './workflow';
+/**
+ * The main interface for the AI Engine.
+ *
+ * @example
+ * ```typescript
+ * import { createAIEngine } from '@recombine-ai/engine'
+ *
+ * Create a new AI engine instance
+ * const ai = createAIEngine({
+ *   // engine configuration, see EngineConfig
+ * })
+ *
+ * // create a conversation to be used in workflow.run(), see Conversation
+ * const conversation = ai.createConversation(messages)
+ * // create a workflow, see WorkflowConfig
+ * const workflow = ai.createWorkflow({steps})
+ * workflow.run(conversation)
+ * ```
+ */
+export interface AIEngine<CTX extends object> {
+    /**
+     * Creates a workflow from a sequence of steps.
+     * @param config - common parameters for a workflow
+     * @returns AI workflow Workflow.
+     */
+    createWorkflow: (config: WorkflowConfig<CTX>) => Workflow<CTX>;
+    /**
+     * Creates a new conversation instance.
+     * @param messages - Optional initial messages for the conversation.
+     * @returns A new Conversation object.
+     */
+    createConversation: (messages?: Message[]) => Conversation;
+    /**
+     * Get the function to create steps to use with {@link WorkflowConfig#steps}
+     * if you want to define steps outside of workflow.
+     */
+    getStepBuilder(): StepBuilder<CTX>;
+    /**
+     * Renders a prompt string using Nunjucks templating engine.
+     * @param prompt - The prompt string to render.
+     * @param context - Optional context object to use for rendering the prompt.
+     * @returns The rendered prompt string.
+     */
+    renderPrompt: (prompt: string, context?: object) => string;
+}
+/**
+ * Configuration options for the Engine.
+ */
+export interface EngineConfig {
+    /**  Optional logger instance for handling log messages.  */
+    logger?: Logger;
+    /** traces received prompt, rendered prompt, context and other useful info about LLM execution */
+    stepTracer?: StepTracer;
+    /** registers steps in workflow to be available in Bosun IDE */
+    stepRegistry?: StepRegistry;
+    /** Optional nunjucks Environment to customize prompt rendering.  */
+    nunjucksEnv?: Environment;
+}
+//# sourceMappingURL=engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/lib/interfaces/engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAErD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,QAAQ,CAAC,GAAG,SAAS,MAAM;IACxC;;;;OAIG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC,GAAG,CAAC,CAAA;IAE9D;;;;OAIG;IACH,kBAAkB,EAAE,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,KAAK,YAAY,CAAA;IAE1D;;;OAGG;IACH,cAAc,IAAI,WAAW,CAAC,GAAG,CAAC,CAAA;IAElC;;;;;OAKG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAC7D;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iGAAiG;IACjG,UAAU,CAAC,EAAE,UAAU,CAAA;IAEvB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAE3B,oEAAoE;IACpE,WAAW,CAAC,EAAE,WAAW,CAAA;CAC5B"}

package/build/lib/interfaces/engine.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,8 @@
+export * from './other';
+export * from './conversation';
+export * from './steps';
+export * from './stream';
+export * from './workflow';
+export * from './adapter';
+export * from './engine';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/interfaces/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,UAAU,CAAA"}

package/build/lib/interfaces/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+__exportStar(require("./other"), exports);
+__exportStar(require("./conversation"), exports);
+__exportStar(require("./steps"), exports);
+__exportStar(require("./stream"), exports);
+__exportStar(require("./workflow"), exports);
+__exportStar(require("./adapter"), exports);
+__exportStar(require("./engine"), exports);

package/build/lib/{interfaces.d.ts → interfaces/other.d.ts}

@@ -23,4 +23,4 @@ export interface Scheduler {
      */
     clearAllPendingActions: (phone: string) => Promise<unknown>;
 }
-//# sourceMappingURL=interfaces.d.ts.map
+//# sourceMappingURL=other.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"other.d.ts","sourceRoot":"","sources":["../../../src/lib/interfaces/other.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,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE1E,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"}

package/build/lib/interfaces/other.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,84 @@
+import * as Zod from 'zod';
+import { PromptFile } from '../prompt-fs';
+import { LlmAdapter } from './adapter';
+import { Conversation } from './conversation';
+import { WorkflowControls } from './workflow';
+export interface BasicStep<CTX> {
+    /** Step name  */
+    name: string;
+    /** Determines if the step should be run or not */
+    runIf?: (messages: Conversation, ctx: CTX) => boolean | Promise<boolean>;
+    /**
+     * When provided, throws an error if the step is invoked more times than `maxAttempts`.
+     * Number of attempts taken is reset when the flow passed the step that was rewinding.
+     */
+    maxAttempts?: number;
+    /** Error handler called if an error occurred during in `execute` function */
+    onError?: (error: string, ctx: CTX) => Promise<unknown>;
+}
+export interface ProgrammaticStep<CTX> extends BasicStep<CTX> {
+    /** Content of the step */
+    execute: (messages: Conversation, ctx: CTX, workflow: WorkflowControls) => Promise<unknown>;
+}
+export interface LLMStep<CTX> extends BasicStep<CTX> {
+    /** LLM adapter to use */
+    model: LlmAdapter;
+    /**
+     * 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 | PromptFile;
+    /**
+     * Do not put messages that were added via {@link Conversation.addMessage} into the prompt.
+     */
+    ignoreAddedMessages?: boolean;
+}
+export interface JsonLLMStep<CTX, Schema extends Zod.ZodType> extends LLMStep<CTX> {
+    /**
+     * Defines the expected structure of the LLM's output. Accepts ZodSchema. When provided, the
+     * LLM's response is validated and parsed according to this schema ensuring reliable structured
+     * output.
+     */
+    schema: Schema;
+    /**
+     * Function to execute with the LLM's response. Use {@link setProposedReply} to use the LLM's output as the proposed reply.
+     * Or use combination of {@link getProposedReply} and {@link setProposedReply} to substitute parts of the string.
+     * @example
+     * ```
+     * // 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: Zod.infer<Schema>, conversation: Conversation, ctx: CTX, workflowControls: WorkflowControls) => Promise<unknown>;
+}
+export interface StringLLMStep<CTX> extends LLMStep<CTX> {
+    /**
+     * Function to execute with the LLM's response. Use {@link setProposedReply} to use the LLM's output as the proposed reply.
+     * Or use combination of {@link getProposedReply} and {@link setProposedReply} to substitute parts of the string.
+     * @example
+     * ```
+     * // 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, conversation: Conversation, ctx: CTX, workflowControls?: WorkflowControls) => Promise<unknown>;
+}
+export type WorkflowStep<CTX> = StringLLMStep<CTX> | JsonLLMStep<CTX, any> | ProgrammaticStep<CTX>;
+export interface StepBuilder<CTX> {
+    <Schema extends Zod.ZodType>(step: JsonLLMStep<CTX, Schema>): JsonLLMStep<CTX, Schema>;
+    (step: StringLLMStep<CTX>): StringLLMStep<CTX>;
+    (step: ProgrammaticStep<CTX>): ProgrammaticStep<CTX>;
+}
+//# sourceMappingURL=steps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../../src/lib/interfaces/steps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,KAAK,CAAA;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAE7C,MAAM,WAAW,SAAS,CAAC,GAAG;IAC1B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAA;IAEZ,kDAAkD;IAClD,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAExE;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC1D;AAED,MAAM,WAAW,gBAAgB,CAAC,GAAG,CAAE,SAAQ,SAAS,CAAC,GAAG,CAAC;IACzD,0BAA0B;IAC1B,OAAO,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,gBAAgB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC9F;AAED,MAAM,WAAW,OAAO,CAAC,GAAG,CAAE,SAAQ,SAAS,CAAC,GAAG,CAAC;IAChD,yBAAyB;IACzB,KAAK,EAAE,UAAU,CAAA;IAEjB;;;OAGG;IACH,MAAM,EAAE,MAAM,GAAG,UAAU,CAAA;IAE3B;;OAEG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAChC;AAED,MAAM,WAAW,WAAW,CAAC,GAAG,EAAE,MAAM,SAAS,GAAG,CAAC,OAAO,CAAE,SAAQ,OAAO,CAAC,GAAG,CAAC;IAC9E;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;;;;;;;;;OAcG;IACH,OAAO,EAAE,CACL,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EACxB,YAAY,EAAE,YAAY,EAC1B,GAAG,EAAE,GAAG,EACR,gBAAgB,EAAE,gBAAgB,KACjC,OAAO,CAAC,OAAO,CAAC,CAAA;CACxB;AAED,MAAM,WAAW,aAAa,CAAC,GAAG,CAAE,SAAQ,OAAO,CAAC,GAAG,CAAC;IACpD;;;;;;;;;;;;;;OAcG;IACH,OAAO,EAAE,CACL,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,YAAY,EAC1B,GAAG,EAAE,GAAG,EACR,gBAAgB,CAAC,EAAE,gBAAgB,KAClC,OAAO,CAAC,OAAO,CAAC,CAAA;CACxB;AAED,MAAM,MAAM,YAAY,CAAC,GAAG,IAAI,aAAa,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAA;AAElG,MAAM,WAAW,WAAW,CAAC,GAAG;IAC5B,CAAC,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IACtF,CAAC,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,CAAA;IAC9C,CAAC,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAA;CACvD"}

package/build/lib/interfaces/steps.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/lib/{stream/interfaces.d.ts → interfaces/stream.d.ts}

@@ -1,10 +1,10 @@
-import { Message } from '../ai';
-import { Logger } from '../interfaces';
-import { ConversationalTracer, StepRegistry, StepTracer } from '../bosun';
+import { Message } from './conversation';
+import { StepRegistry, StepTracer } from '../bosun';
 import { PromptFile } from '../prompt-fs';
-export interface AIStreamEngine {
+import { Logger } from './other';
+export interface AIStreamEngine<CTX extends {}> {
     /** creates streaming workflow */
-    createWorkflow: <CTX extends {}>(config: WorkflowConfig<CTX>) => {
+    createWorkflow: (config: StreamWorkflowConfig<CTX>) => {
         /**
          * Runs streaming workflow (starts stream)
          * @param messages
@@ -21,10 +21,8 @@ export interface StreamingEngineConfig {
     stepRegistry?: StepRegistry;
     /** traces received prompt, rendered prompt, context and other useful info about LLM execution */
     stepTracer?: StepTracer;
-    /** same as stepTracer but for “something happened in the conversation” events  */
-    conversationalTracer?: ConversationalTracer;
 }
-export interface WorkflowConfig<CTX> {
+export interface StreamWorkflowConfig<CTX> {
     /** name of the workflow and its only step to appear in Bosun and in traces */
     name: string;
     /** system prompt */
@@ -70,4 +68,4 @@ export interface ResponseChunk {
     role: 'agent' | 'system';
     delta: string;
 }
-//# sourceMappingURL=interfaces.d.ts.map
+//# sourceMappingURL=stream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../src/lib/interfaces/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAEhC,MAAM,WAAW,cAAc,CAAC,GAAG,SAAS,EAAE;IAC1C,iCAAiC;IACjC,cAAc,EAAE,CAAC,MAAM,EAAE,oBAAoB,CAAC,GAAG,CAAC,KAAK;QACnD;;;;;WAKG;QACH,GAAG,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAA;KACjF,CAAA;CACJ;AAED,MAAM,WAAW,qBAAqB;IAClC,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,iGAAiG;IACjG,UAAU,CAAC,EAAE,UAAU,CAAA;CAC1B;AAED,MAAM,WAAW,oBAAoB,CAAC,GAAG;IACrC,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAA;IACZ,oBAAoB;IACpB,MAAM,EAAE,MAAM,GAAG,UAAU,CAAA;IAC3B,uCAAuC;IACvC,KAAK,EAAE,gBAAgB,CAAA;IACvB,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3D,wCAAwC;IACxC,MAAM,CAAC,EAAE,kBAAkB,CAAA;CAC9B;AAED,MAAM,WAAW,UAAU;IACvB,cAAc,EAAE,aAAa,EAAE,CAAA;IAC/B,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAA;IACtC,wBAAwB,IAAI,IAAI,CAAA;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IAC5C,eAAe,IAAI,OAAO,EAAE,CAAA;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC7B;;;;OAIG;IACH,cAAc,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAA;IAC3F,0DAA0D;IAC1D,UAAU,EAAE,MAAM,OAAO,CAAA;CAC5B;AAED,MAAM,WAAW,kBAAkB;IAC/B,oBAAoB,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAA;IACtE,UAAU,EAAE,CACR,KAAK,EAAE,UAAU,EACjB,cAAc,EAAE,MAAM,EAAE,KACvB;QAAE,MAAM,EAAE,oBAAoB,CAAA;KAAE,GAAG;QAAE,MAAM,EAAE,gBAAgB,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;IACtF,WAAW,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK;QAAE,eAAe,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CAC9F;AAED,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAA;IACxB,KAAK,EAAE,MAAM,CAAA;CAChB"}

package/build/lib/interfaces/stream.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,44 @@
+import { Conversation } from './conversation';
+import { WorkflowStep } from './steps';
+export interface WorkflowControls {
+    /**
+     * Terminates the workflow, preventing further steps from being executed.
+     */
+    terminate: () => void;
+    /**
+     * Rewinds the workflow execution to a specific step.
+     * @param step - The name of the step to rewind to
+     */
+    rewindTo: (step: string) => void;
+}
+export type BeforeEachStep<CTX> = (conversation: Conversation, ctx: CTX, workflowControls?: WorkflowControls) => Promise<void>;
+/**
+ * An AI workflow composed of steps.
+ */
+export interface Workflow<CTX> {
+    /**
+     * Runs the workflow with a given conversation context.
+     * Executes steps sequentially until completion or termination.
+     * @param conversation - The conversation context for the workflow
+     * @param contextProvider - A provider function for the context that will be passed to all steps and to all prompts in those steps
+     * @param beforeEach - A callback, that runs before each step
+     * @returns The proposed reply if workflow completes, or null if terminated
+     */
+    run: (conversation: Conversation, contextProvider: (() => CTX) | (() => Promise<CTX>), beforeEach?: BeforeEachStep<CTX>) => Promise<string | null>;
+}
+/**
+ * Config object to be used in {@link AIEngine#createWorkflow}
+ */
+export interface WorkflowConfig<CTX> {
+    /** workflow name, to use in traces, defaults to 'workflow' */
+    name?: string;
+    /** a function that will run once, if any of the steps going to be executed */
+    beforeExecute?: (ctx: CTX) => Promise<void>;
+    /** a function that will run once, if any of the steps was executed */
+    afterExecute?: (ctx: CTX) => Promise<void>;
+    /** common error handler for workflow */
+    onError: (error: string, ctx: CTX) => Promise<unknown>;
+    /** workflow steps {@link ProgrammaticStep}, {@link StringLLMStep} or {@link JsonLLMStep} */
+    steps?: WorkflowStep<CTX>[];
+}
+//# sourceMappingURL=workflow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../../src/lib/interfaces/workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAEtC,MAAM,WAAW,gBAAgB;IAC7B;;OAEG;IACH,SAAS,EAAE,MAAM,IAAI,CAAA;IAErB;;;OAGG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACnC;AAED,MAAM,MAAM,cAAc,CAAC,GAAG,IAAI,CAC9B,YAAY,EAAE,YAAY,EAC1B,GAAG,EAAE,GAAG,EACR,gBAAgB,CAAC,EAAE,gBAAgB,KAClC,OAAO,CAAC,IAAI,CAAC,CAAA;AAElB;;GAEG;AACH,MAAM,WAAW,QAAQ,CAAC,GAAG;IACzB;;;;;;;OAOG;IACH,GAAG,EAAE,CACD,YAAY,EAAE,YAAY,EAC1B,eAAe,EAAE,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,EACnD,UAAU,CAAC,EAAE,cAAc,CAAC,GAAG,CAAC,KAC/B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,GAAG;IAC/B,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,sEAAsE;IACtE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1C,wCAAwC;IACxC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACtD,4FAA4F;IAC5F,KAAK,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAA;CAC9B"}

package/build/lib/interfaces/workflow.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/lib/llm-adapters/mock.d.ts

@@ -1,3 +1,3 @@
-import type { LlmAdapter } from '../ai';
+import { LlmAdapter } from '../interfaces';
 export declare function createMockAdapter(): LlmAdapter;
 //# sourceMappingURL=mock.d.ts.map

package/build/lib/llm-adapters/mock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../../src/lib/llm-adapters/mock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAEvC,wBAAgB,iBAAiB,IAAI,UAAU,CAU9C"}
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../../src/lib/llm-adapters/mock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE1C,wBAAgB,iBAAiB,IAAI,UAAU,CAU9C"}

package/build/lib/llm-adapters/openai-stream.d.ts

@@ -1,6 +1,6 @@
 import { OpenAI } from 'openai';
 import { ChatCompletionCreateParamsBase } from 'openai/resources/chat/completions';
-import { LlmStreamAdapter } from '../stream/interfaces';
+import { LlmStreamAdapter } from '../interfaces/stream';
 export type OpenAIChatOptions = Omit<ChatCompletionCreateParamsBase, 'messages' | 'response_format' | 'stream'>;
 export declare function createOpenAIStreamAdapter(options: OpenAIChatOptions, client?: OpenAI): LlmStreamAdapter;
 //# sourceMappingURL=openai-stream.d.ts.map

package/build/lib/llm-adapters/openai.d.ts

@@ -1,6 +1,6 @@
 import { OpenAI } from 'openai';
 import { ChatCompletionCreateParamsBase } from 'openai/resources/chat/completions';
-import type { LlmAdapter } from '../ai';
+import { LlmAdapter } from '../interfaces';
 type OpenaiOptionsToSend = Omit<ChatCompletionCreateParamsBase, 'messages' | 'stream'>;
 export type OpenAIChatOptions = Omit<OpenaiOptionsToSend, 'response_format'>;
 export declare function createOpenAIAdapter(options: OpenAIChatOptions, client?: OpenAI): LlmAdapter;

package/build/lib/llm-adapters/openai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../../src/lib/llm-adapters/openai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAA;AAClF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAGvC,KAAK,mBAAmB,GAAG,IAAI,CAAC,8BAA8B,EAAE,UAAU,GAAG,QAAQ,CAAC,CAAA;AACtF,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAAA;AAE5E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAe,GAAG,UAAU,CAmCjG"}
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../../src/lib/llm-adapters/openai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAA;AAElF,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE1C,KAAK,mBAAmB,GAAG,IAAI,CAAC,8BAA8B,EAAE,UAAU,GAAG,QAAQ,CAAC,CAAA;AACtF,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAAA;AAE5E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAe,GAAG,UAAU,CAmCjG"}

package/build/lib/stream/engine.d.ts

@@ -0,0 +1,3 @@
+import { AIStreamEngine, StreamingEngineConfig } from '../interfaces/stream';
+export declare function createAIStreamEngine<CTX extends {}>(cfg: StreamingEngineConfig): AIStreamEngine<CTX>;
+//# sourceMappingURL=engine.d.ts.map

package/build/lib/stream/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/lib/stream/engine.ts"],"names":[],"mappings":"AAMA,OAAO,EACH,cAAc,EAGd,qBAAqB,EAGxB,MAAM,sBAAsB,CAAA;AAI7B,wBAAgB,oBAAoB,CAAC,GAAG,SAAS,EAAE,EAC/C,GAAG,EAAE,qBAAqB,GAC3B,cAAc,CAAC,GAAG,CAAC,CAuMrB"}

package/build/lib/stream/{ai.js → engine.js}

@@ -144,27 +144,6 @@ function createAIStreamEngine(cfg) {
                     // Add step trace and flush to telescope
                     cfg.stepTracer?.addStepTrace(mainStepTrace);
                     await cfg.stepTracer?.flush();
-                    if (cfg.conversationalTracer) {
-                        try {
-                            const ctxWithState = ctx;
-                            const rawConversationId = ctxWithState?.state?.callId ?? ctxWithState?.callId;
-                            const conversationId = typeof rawConversationId === 'string' && rawConversationId !== ''
-                                ? rawConversationId
-                                : undefined;
-                            cfg.conversationalTracer.addConversationalTrace({
-                                conversationId,
-                                eventName: 'finished-main-streaming-step',
-                                role: 'agent',
-                                medium: 'phone',
-                                content: transcript.currentResponse,
-                                createdAt: Date.now(),
-                            });
-                            await cfg.conversationalTracer.flush();
-                        }
-                        catch (err) {
-                            logger.error('Failed to write conversational trace', { err });
-                        }
-                    }
                     if (!streamCancelled) {
                         controller.close();
                     }

package/build/lib/stream/filter.d.ts

@@ -1,4 +1,4 @@
-import { ProgrammaticFilter } from './interfaces';
+import { ProgrammaticFilter } from '../interfaces/stream';
 /**
  * filter out 'Agent:' at the beginning of the llm response
  */

package/build/lib/stream/filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/lib/stream/filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAEjD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,kBAc3B,CAAA"}
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/lib/stream/filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAEzD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,kBAc3B,CAAA"}

package/build/lib/stream/index.d.ts

@@ -1,4 +1,4 @@
-export { createAIStreamEngine } from './ai';
-export { AIStreamEngine, ProgrammaticFilter, LlmStreamAdapter, ResponseChunk, Transcript, StreamingEngineConfig, WorkflowConfig as StreamingWorkflowConfig, } from './interfaces';
+export { createAIStreamEngine } from './engine';
+export { AIStreamEngine, ProgrammaticFilter, LlmStreamAdapter, ResponseChunk, Transcript, StreamingEngineConfig, StreamWorkflowConfig as StreamingWorkflowConfig, } from '../interfaces/stream';
 export { getAzureClient, getOpenAiClient } from './get-client';
 //# sourceMappingURL=index.d.ts.map

package/build/lib/stream/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/stream/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,MAAM,CAAA;AAE3C,OAAO,EACH,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,qBAAqB,EACrB,cAAc,IAAI,uBAAuB,GAC5C,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/stream/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAE/C,OAAO,EACH,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,qBAAqB,EACrB,oBAAoB,IAAI,uBAAuB,GAClD,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA"}

package/build/lib/stream/index.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getOpenAiClient = exports.getAzureClient = exports.createAIStreamEngine = void 0;
-var ai_1 = require("./ai");
-Object.defineProperty(exports, "createAIStreamEngine", { enumerable: true, get: function () { return ai_1.createAIStreamEngine; } });
+var engine_1 = require("./engine");
+Object.defineProperty(exports, "createAIStreamEngine", { enumerable: true, get: function () { return engine_1.createAIStreamEngine; } });
 var get_client_1 = require("./get-client");
 Object.defineProperty(exports, "getAzureClient", { enumerable: true, get: function () { return get_client_1.getAzureClient; } });
 Object.defineProperty(exports, "getOpenAiClient", { enumerable: true, get: function () { return get_client_1.getOpenAiClient; } });

package/changelog.md

@@ -4,6 +4,7 @@
 
 - **Breaking:** `model` field on `LLMStep` is now required and must be an `LlmAdapter` (string model names removed)
 - **Breaking:** OpenAI adapter no longer embeds API-key management; pass a pre-configured `OpenAI` client instead
+- **Breaking:** `AIEngine` now requires `CTX` parameter
 - **Breaking:** Removed deprecated `Conversation.setUserName()` / `setAgentName()` (defaults: "User" / "Agent")
 - **Breaking:** Removed deprecated `Workflow.addStep()` – pass all steps via `WorkflowConfig#steps`
 - **Breaking:** Removed deprecated `EngineConfig.tokenStorage`, `sendAction`, and `tracer` (use `stepRegistry`)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@recombine-ai/engine",
-    "version": "1.0.0-beta-1",
+    "version": "1.0.0-beta-3",
     "description": "Recombine AI engine for creating conversational AI agents",
     "repository": {
         "url": "git+https://github.com/recombine-ai/engine.git"

package/build/lib/ai.d.ts

@@ -1,286 +0,0 @@
-import nunjucks from 'nunjucks';
-import * as Zod from 'zod';
-import { Logger } from './interfaces';
-import { PromptFile } from './prompt-fs';
-import { StepTracer } from './bosun/step-tracer';
-import { StepRegistry } from './bosun/step-registry';
-export interface LlmAdapter {
-    /**
-     * @param systemPrompt - rendered system prompt
-     * @param messages - stringified {@link Conversation}
-     * @param schema - optional Zod schema to pass to the model. Will overwrite any schema set in adapter options.
-     * @returns LLM Response
-     */
-    generateResponse: (systemPrompt: string, messages: string, schema?: Zod.ZodType) => Promise<string>;
-    /** Returns adapter's configuration/options for tracing */
-    getOptions: () => unknown;
-}
-export interface BasicStep<CTX> {
-    /** Step name  */
-    name: string;
-    /** Determines if the step should be run or not */
-    runIf?: (messages: Conversation, ctx: CTX) => boolean | Promise<boolean>;
-    /**
-     * When provided, throws an error if the step is invoked more times than `maxAttempts`.
-     * Number of attempts taken is reset when the flow passed the step that was rewinding.
-     */
-    maxAttempts?: number;
-    /** Error handler called if an error occurred during in `execute` function */
-    onError?: (error: string, ctx: CTX) => Promise<unknown>;
-}
-export interface ProgrammaticStep<CTX> extends BasicStep<CTX> {
-    /** Content of the step */
-    execute: (messages: Conversation, ctx: CTX, workflow: WorkflowControls) => Promise<unknown>;
-}
-export interface LLMStep<CTX> extends BasicStep<CTX> {
-    /** LLM adapter to use */
-    model: LlmAdapter;
-    /**
-     * 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 | PromptFile;
-    /**
-     * Do not put messages that were added via {@link Conversation.addMessage} into the prompt.
-     */
-    ignoreAddedMessages?: boolean;
-}
-export interface WorkflowControls {
-    /**
-     * Terminates the workflow, preventing further steps from being executed.
-     */
-    terminate: () => void;
-    /**
-     * Rewinds the workflow execution to a specific step.
-     * @param step - The name of the step to rewind to
-     */
-    rewindTo: (step: string) => void;
-}
-export interface JsonLLMStep<CTX, Schema extends Zod.ZodType> extends LLMStep<CTX> {
-    /**
-     * Defines the expected structure of the LLM's output. Accepts ZodSchema. When provided, the
-     * LLM's response is validated and parsed according to this schema ensuring reliable structured
-     * output.
-     */
-    schema: Schema;
-    /**
-     * Function to execute with the LLM's response. Use {@link setProposedReply} to use the LLM's output as the proposed reply.
-     * Or use combination of {@link getProposedReply} and {@link setProposedReply} to substitute parts of the string.
-     * @example
-     * ```
-     * // 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: Zod.infer<Schema>, conversation: Conversation, ctx: CTX, workflowControls: WorkflowControls) => Promise<unknown>;
-}
-export interface StringLLMStep<CTX> extends LLMStep<CTX> {
-    /**
-     * Function to execute with the LLM's response. Use {@link setProposedReply} to use the LLM's output as the proposed reply.
-     * Or use combination of {@link getProposedReply} and {@link setProposedReply} to substitute parts of the string.
-     * @example
-     * ```
-     * // 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, conversation: Conversation, ctx: CTX, workflowControls?: WorkflowControls) => Promise<unknown>;
-}
-type BeforeEachStep<CTX> = (conversation: Conversation, ctx: CTX, workflowControls?: WorkflowControls) => Promise<void>;
-/**
- * An AI workflow composed of steps.
- */
-export interface Workflow<CTX> {
-    /**
-     * Runs the workflow with a given conversation context.
-     * Executes steps sequentially until completion or termination.
-     * @param conversation - The conversation context for the workflow
-     * @param contextProvider - A provider function for the context that will be passed to all steps and to all prompts in those steps
-     * @param beforeEach - A callback, that runs before each step
-     * @returns The proposed reply if workflow completes, or null if terminated
-     */
-    run: (conversation: Conversation, contextProvider: (() => CTX) | (() => Promise<CTX>), beforeEach?: BeforeEachStep<CTX>) => Promise<string | null>;
-}
-type WorkflowStep<CTX> = StringLLMStep<CTX> | JsonLLMStep<CTX, any> | ProgrammaticStep<CTX>;
-/**
- * Config object to be used in {@link AIEngine#createWorkflow}
- */
-export interface WorkflowConfig<CTX> {
-    /** workflow name, to use in traces, defaults to 'workflow' */
-    name?: string;
-    /** a function that will run once, if any of the steps going to be executed */
-    beforeExecute?: (ctx: CTX) => Promise<void>;
-    /** a function that will run once, if any of the steps was executed */
-    afterExecute?: (ctx: CTX) => Promise<void>;
-    /** common error handler for workflow */
-    onError: (error: string, ctx: CTX) => Promise<unknown>;
-    /** workflow steps {@link ProgrammaticStep}, {@link StringLLMStep} or {@link JsonLLMStep} */
-    steps?: WorkflowStep<CTX>[];
-}
-interface StepBuilder<CTX> {
-    <Schema extends Zod.ZodType>(step: JsonLLMStep<CTX, Schema>): JsonLLMStep<CTX, Schema>;
-    (step: StringLLMStep<CTX>): StringLLMStep<CTX>;
-    (step: ProgrammaticStep<CTX>): ProgrammaticStep<CTX>;
-}
-/**
- * The main interface for the AI Engine.
- *
- * @example
- * ```typescript
- * import { createAIEngine } from '@recombine-ai/engine'
- *
- * Create a new AI engine instance
- * const ai = createAIEngine({
- *   // engine configuration, see EngineConfig
- * })
- *
- * // create a conversation to be used in workflow.run(), see Conversation
- * const conversation = ai.createConversation(messages)
- * // create a workflow, see WorkflowConfig
- * const workflow = ai.createWorkflow({steps})
- * workflow.run(conversation)
- * ```
- */
-export interface AIEngine {
-    /**
-     * Creates a workflow from a sequence of steps.
-     * @param config - common parameters for a workflow
-     * @returns AI workflow Workflow.
-     */
-    createWorkflow: <CTX extends object>(config: WorkflowConfig<CTX>) => Workflow<CTX>;
-    /**
-     * Creates a new conversation instance.
-     * @param messages - Optional initial messages for the conversation.
-     * @returns A new Conversation object.
-     */
-    createConversation: (messages?: Message[]) => Conversation;
-    /**
-     * Get the function to create steps to use with {@link WorkflowConfig#steps}
-     * if you want to define steps outside of workflow.
-     */
-    getStepBuilder<CTX>(): StepBuilder<CTX>;
-    /**
-     * Renders a prompt string using Nunjucks templating engine.
-     * @param prompt - The prompt string to render.
-     * @param context - Optional context object to use for rendering the prompt.
-     * @returns The rendered prompt string.
-     */
-    renderPrompt: (prompt: string, context?: object) => string;
-}
-/**
- * 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.
- */
-export interface Conversation {
-    /**
-     * Sets the default formatter to stringify messages when toString is called.
-     * @param formatter - A function that takes a message and returns a formatted string.
-     */
-    setDefaultFormatter: (formatter: (message: Message) => string) => void;
-    /**
-     * Converts the conversation to a string representation to be fed to an LLM.
-     * @param filter - A function that filters messages based on certain criteria.
-     * @example
-     * @returns The string representation of the conversation.
-     */
-    toString: (options?: {
-        ignoreAddedMessages?: boolean;
-    }) => string;
-    /**
-     * Adds a message from a specified sender to the conversation.
-     * @param message - The message to add to the conversation.
-     */
-    addMessage: (message: Message, opts?: {
-        formatter?: (message: Message) => string;
-    }) => void;
-    /**
-     * Sets a custom formatter for proposed messages.
-     * @param formatter - A function that takes a message string and returns a formatted string.
-     */
-    setProposedMessageFormatter: (formatter: (message: string) => string) => void;
-    /**
-     * Sets a proposed reply message.
-     * @param message - The proposed reply message.
-     */
-    setProposedReply: (message: string) => void;
-    /**
-     * Gets the current proposed reply message.
-     * @returns The proposed reply message, or null if none exists.
-     */
-    getProposedReply: () => string | null;
-    /**
-     * Gets the history of all messages in the conversation. Returns {@link Message} rather than
-     * {@link ConversationMessage} because none of the {@link ConversationMessage} properties should
-     * be accessed outside of the {@link Conversation} context.
-     * @returns An array of Message objects representing the conversation history.
-     */
-    getHistory: () => Message[];
-}
-/**
- * Represents a message in a conversation between a user and an agent, or a system message.
- * Messages can contain text and optionally an image URL. To be used in the {@link Conversation} interface.
- */
-export interface Message {
-    /** The sender of the message, which can be one of the following: 'user', 'agent', or 'system' */
-    sender: 'user' | 'agent' | 'system';
-    /** The text content of the message */
-    text: string;
-    /** Optional URL of an image associated with the message */
-    imageUrl?: string;
-}
-/**
- * Configuration options for the Engine.
- */
-export interface EngineConfig {
-    /**  Optional logger instance for handling log messages.  */
-    logger?: Logger;
-    /** traces received prompt, rendered prompt, context and other useful info about LLM execution */
-    stepTracer?: StepTracer;
-    /** registers steps in workflow to be available in Bosun IDE */
-    stepRegistry?: StepRegistry;
-    /** Optional nunjucks Environment to customize prompt rendering.  */
-    nunjucksEnv?: nunjucks.Environment;
-}
-/**
- * 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,
- * });
- *
- * const workflow = await engine.createWorkflow(
- *   engine.createStep({
- *     name: 'generate-response',
- *     prompt: engine.loadFile('prompts/response.txt'),
- *     execute: (response) => conversation.setProposedReply(response)
- *   })
- * );
- *
- * const reply = await workflow.run(conversation);
- * ```
- */
-export declare function createAIEngine(cfg?: EngineConfig): AIEngine;
-export declare function createConversation(initialMessages?: Message[]): Conversation;
-export declare function getStepBuilder<CTX = unknown>(): StepBuilder<CTX>;
-export {};
-//# sourceMappingURL=ai.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/lib/ai.ts"],"names":[],"mappings":"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"}

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

@@ -1 +0,0 @@
-{"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,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE1E,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"}

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

@@ -1,3 +0,0 @@
-import { AIStreamEngine, StreamingEngineConfig } from './interfaces';
-export declare function createAIStreamEngine(cfg: StreamingEngineConfig): AIStreamEngine;
-//# sourceMappingURL=ai.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../../src/lib/stream/ai.ts"],"names":[],"mappings":"AAOA,OAAO,EACH,cAAc,EAGd,qBAAqB,EAGxB,MAAM,cAAc,CAAA;AAIrB,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,qBAAqB,GAAG,cAAc,CA6N/E"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../../src/lib/stream/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AACtC,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC,MAAM,WAAW,cAAc;IAC3B,iCAAiC;IACjC,cAAc,EAAE,CAAC,GAAG,SAAS,EAAE,EAC3B,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,KAC1B;QACD;;;;;WAKG;QACH,GAAG,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAA;KACjF,CAAA;CACJ;AAED,MAAM,WAAW,qBAAqB;IAClC,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,iGAAiG;IACjG,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,kFAAkF;IAClF,oBAAoB,CAAC,EAAE,oBAAoB,CAAA;CAC9C;AAED,MAAM,WAAW,cAAc,CAAC,GAAG;IAC/B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAA;IACZ,oBAAoB;IACpB,MAAM,EAAE,MAAM,GAAG,UAAU,CAAA;IAC3B,uCAAuC;IACvC,KAAK,EAAE,gBAAgB,CAAA;IACvB,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3D,wCAAwC;IACxC,MAAM,CAAC,EAAE,kBAAkB,CAAA;CAC9B;AAED,MAAM,WAAW,UAAU;IACvB,cAAc,EAAE,aAAa,EAAE,CAAA;IAC/B,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAA;IACtC,wBAAwB,IAAI,IAAI,CAAA;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IAC5C,eAAe,IAAI,OAAO,EAAE,CAAA;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC7B;;;;OAIG;IACH,cAAc,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAA;IAC3F,0DAA0D;IAC1D,UAAU,EAAE,MAAM,OAAO,CAAA;CAC5B;AAED,MAAM,WAAW,kBAAkB;IAC/B,oBAAoB,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAA;IACtE,UAAU,EAAE,CACR,KAAK,EAAE,UAAU,EACjB,cAAc,EAAE,MAAM,EAAE,KACvB;QAAE,MAAM,EAAE,oBAAoB,CAAA;KAAE,GAAG;QAAE,MAAM,EAAE,gBAAgB,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;IACtF,WAAW,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK;QAAE,eAAe,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CAC9F;AAED,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAA;IACxB,KAAK,EAAE,MAAM,CAAA;CAChB"}