@recombine-ai/engine 0.11.0 → 0.11.1

package/.github/workflows/publish.yml

@@ -39,5 +39,17 @@ jobs:
             - name: 'Build'
               run: npm run build
 
+            - name: 'Compute npm publish args'
+              id: publish_meta
+              run: |
+                  VERSION="${GITHUB_REF_NAME#v}"
+                  if [[ "$VERSION" == *-* ]]; then
+                      PRERELEASE="${VERSION#*-}"
+                      DIST_TAG="${PRERELEASE%%.*}"
+                      echo "publish_args=--access public --tag ${DIST_TAG}" >> "$GITHUB_OUTPUT"
+                  else
+                      echo "publish_args=--access public" >> "$GITHUB_OUTPUT"
+                  fi
+
             - name: 'Publish to npm'
-              run: npm publish --access public
+              run: npm publish ${{ steps.publish_meta.outputs.publish_args }}

package/build/lib/ai.d.ts

@@ -118,17 +118,27 @@ export interface Workflow<CTX> {
     run: (conversation: Conversation, contextProvider: (() => CTX) | (() => Promise<CTX>), beforeEach?: BeforeEachStep<CTX>) => Promise<string | null>;
     /**
      * Add a step to workflow
+     * @deprecated use {@link WorkflowConfig#steps} instead
      */
     addStep<Schema extends Zod.ZodTypeAny>(step: JsonLLMStep<CTX, Schema>): void;
     addStep(step: StringLLMStep<CTX>): void;
     addStep(step: ProgrammaticStep<CTX>): void;
 }
 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>[];
-    name?: string;
-    beforeEachCallback?: () => Promise<unknown>;
 }
 interface StepBuilder<CTX> {
     <Schema extends Zod.ZodTypeAny>(step: JsonLLMStep<CTX, Schema>): JsonLLMStep<CTX, Schema>;
@@ -140,57 +150,25 @@ interface StepBuilder<CTX> {
  *
  * @example
  * ```typescript
- * import { AIEngine } from './lib/ai'
- *
- * // Create a new AI engine instance
- * const ai = AIEngine.createAIEngine()
+ * import { createAIEngine } from '@recombine-ai/engine'
  *
- * // Create a conversation
- * const conversation = ai.createConversation()
- * conversation.addMessage('user', 'I need help with my order')
- *
- * // Define workflow steps
- * const killswitch = ai.createStep({
- *   name: 'killswitch',
- *   prompt: ai.loadFile('prompts/killswitch.njk'),
- *   execute: async (reply) => {
- *     const result = JSON.parse(reply)
- *     if (result.terminate) {
- *       conversation.addDirective(`Terminating workflow: ${result.reason}`)
- *       return workflow.terminate()
- *     }
- *   },
- *   onError: async (error) => conversation.addDirective(`Error in killswitch: ${error}`)
- * })
- *
- * const analyzeIntent = ai.createStep({
- *   name: 'analyze-intent',
- *   prompt: ai.loadFile('prompts/analyze-intent.njk'),
- *   execute: async (reply) => {
- *     const intent = JSON.parse(reply)
- *     conversation.addDirective(`User intent is: ${intent.category}`)
- *   },
- *   onError: async (error) => conversation.addDirective(`Error analyzing intent: ${error}`)
+ * Create a new AI engine instance
+ * const ai = createAIEngine({
+ *   // engine configuration, see EngineConfig
  * })
  *
- * const mainReply = ai.createStep({
- *   name: 'main-reply',
- *   prompt: ai.loadFile('prompts/generate-response.njk'),
- *   execute: async (reply) => conversation.setProposedReply(reply),
- *   onError: async (error) => conversation.setProposedReply(`I'm sorry, I'm having trouble right now.`)
- * })
- *
- * // Create and run the workflow
- * const workflow = await ai.createWorkflow(killswitch, analyzeIntent, mainReply)
- * const response = await workflow.run(conversation)
- * console.log(response)
+ * // 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 A Promise that resolves to the created Workflow.
+     * @returns AI workflow Workflow.
      */
     createWorkflow: <CTX extends object>(config: WorkflowConfig<CTX>) => Workflow<CTX>;
     /**
@@ -216,36 +194,18 @@ export interface AIEngine {
  * Represents a conversation between a user and an AI agent.
  * Provides methods to manage the conversation flow, format messages, and convert the conversation
  * to a string representation.
- *
- * @example
- * ```typescript
- * // Create a new conversation instance
- * const conversation = new Conversation();
- *
- * // Set names for the participants
- * conversation.setUserName("Client");
- * conversation.setAgentName("Support");
- *
- * // Add messages to the conversation
- * conversation.addMessage("user", "I need help with my account");
- * conversation.addDirective("Ask for account details");
- *
- * // Get the conversation as a string to feed to an LLM
- * const conversationText = conversation.toString();
- * // Output:
- * // Client: I need help with my account
- * // System: Ask for account details
- * ```
  */
 export interface Conversation {
     /**
      * Sets the name of the user in the conversation to be used in {@link toString}.
      * @param name - The name to set for the user.
+     * @deprecated
      */
     setUserName(name: string): void;
     /**
      * Sets the name of the AI agent in the conversation to be used in {@link toString}.
      * @param name - The name to set for the agent.
+     * @deprecated
      */
     setAgentName(name: string): void;
     /**

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

@@ -78,11 +78,13 @@ function createAIEngine(cfg = {}) {
     const stepTracer = cfg.stepTracer || (0, stepTracer_1.createStubStepTracer)(logger);
     const registry = cfg.stepRegistry || cfg.tracer || (0, tracer_1.createStubRegistry)(logger);
     // tokenStorage is used by the default adapter to fetch API keys (backwards compatible)
-    function createWorkflow({ onError, steps = [], name = 'workflow', }) {
+    function createWorkflow({ onError, beforeExecute, afterExecute, steps = [], name = 'workflow', }) {
         steps.forEach(addStepToTracer);
         return {
             run: async (messages, contextProvider, beforeEach) => {
                 const state = new WorkflowState(logger, steps);
+                let beforeHookExecuted = false;
+                let didExecute = false;
                 do {
                     const ctx = await contextProvider();
                     await beforeEach?.(messages, ctx, state);
@@ -92,8 +94,14 @@ function createAIEngine(cfg = {}) {
                         break;
                     }
                     if (!step.runIf || (await step.runIf(messages, ctx))) {
+                        // TODO: drop actions, they are replaced by traces
                         const action = (0, action_1.makeAction)(cfg.sendAction, 'AI', step.name);
                         await action('started');
+                        didExecute = true;
+                        if (beforeExecute && !beforeHookExecuted) {
+                            await beforeExecute(ctx);
+                            beforeHookExecuted = true;
+                        }
                         if ('prompt' in step) {
                             await runStep(step, messages, ctx, state);
                         }
@@ -103,6 +111,9 @@ function createAIEngine(cfg = {}) {
                         await action('completed');
                     }
                 } while (state.next());
+                if (afterExecute && didExecute) {
+                    await afterExecute(await contextProvider());
+                }
                 await stepTracer.flush();
                 return state.isTerminated() ? null : messages.getProposedReply();
             },

package/changelog.md

@@ -1,5 +1,22 @@
 # Changelog
 
+### 0.11.0 → 0.11.1 (unstable)
+
+- Added `beforeExecute` and `afterExecute` hooks to Workflow configuration.
+
+### 0.10.4 → 0.11.0 (unstable)
+
+- Breaking change: second argument in `workflow.run(conversation, contextProvider)` now must be a
+  function.
+
+### 0.10.3 → 0.10.4 (unstable)
+
+- Added LLM usage to `StepTrace` interface
+
+### 0.10.2 → 0.10.3 (unstable)
+
+- Enhanced error handling for AI-generated responses in `runStep`.
+
 ### 0.10.2 → 0.10.3 (unstable)
 
 - Enhanced error handling for AI-generated responses in `runStep`.

package/package.json

@@ -1,9 +1,9 @@
 {
     "name": "@recombine-ai/engine",
-    "version": "0.11.0",
+    "version": "0.11.1",
     "description": "Recombine AI engine for creating conversational AI agents",
     "repository": {
-        "url": "https://github.com/recombine-ai/engine"
+        "url": "git+https://github.com/recombine-ai/engine.git"
     },
     "main": "build/index.js",
     "types": "build/index.d.ts",