@falai/agent 0.9.2 → 1.0.0

package/src/core/Step.ts

@@ -9,13 +9,15 @@ import type {
   BranchSpec,
   BranchResult,
   Guideline,
+  GuidelineMatch,
   Tool,
+  SessionState,
+  Event,
 } from "../types";
-import { ToolScope } from "../types";
-import { Template } from "../types/template";
+import { ToolScope, Template, ConditionTemplate, TemplateContext } from "../types";
+import { createConditionEvaluator, generateStepId, logger } from "../utils";
 import { Agent } from './Agent'
 import { END_ROUTE, END_ROUTE_ID } from "../constants";
-import { generateStepId } from "../utils/id";
 
 /**
  * Represents a step within a route
@@ -23,12 +25,12 @@ import { generateStepId } from "../utils/id";
 export class Step<TContext = unknown, TData = unknown> {
   public readonly id: string;
   private nextSteps: Step<TContext, TData>[] = [];
-  private guidelines: Guideline<TContext>[] = [];
+  private guidelines: Guideline<TContext, TData>[] = [];
   public readonly routeId: string;
   public collect?: (keyof TData)[];
   public description?: string;
-  public when?: Template<TContext, TData>;
-  public skipIf?: (data: Partial<TData>) => boolean;
+  public when?: ConditionTemplate<TContext, TData>;
+  public skipIf?: ConditionTemplate<TContext, TData>;
   public requires?: (keyof TData)[];
   public prompt?: Template<TContext, TData>;
   public prepare?:
@@ -63,6 +65,13 @@ export class Step<TContext = unknown, TData = unknown> {
     this.finalize = options.finalize;
     this.tools = options.tools;
 
+    // Initialize guidelines from options
+    if (options.guidelines) {
+      options.guidelines.forEach((guideline) => {
+        this.addGuideline(guideline);
+      });
+    }
+
     // Store reference to parent agent for ToolManager access
     this.parentAgent = parentAgent;
   }
@@ -74,7 +83,7 @@ export class Step<TContext = unknown, TData = unknown> {
   configure(config: {
     description?: string;
     collect?: (keyof TData)[];
-    skipIf?: (data: Partial<TData>) => boolean;
+    skipIf?: ConditionTemplate<TContext, TData>;
     requires?: (keyof TData)[];
     prompt?: Template<TContext, TData>;
     prepare?:
@@ -199,17 +208,66 @@ export class Step<TContext = unknown, TData = unknown> {
   /**
    * Add a guideline specific to this step
    */
-  addGuideline(guideline: Guideline<TContext>): void {
+  addGuideline(guideline: Guideline<TContext, TData>): void {
     this.guidelines.push(guideline);
   }
 
   /**
    * Get guidelines for this step
    */
-  getGuidelines(): Guideline<TContext>[] {
+  getGuidelines(): Guideline<TContext, TData>[] {
     return [...this.guidelines];
   }
 
+  /**
+   * Evaluate and match active guidelines based on their conditions
+   * Returns guidelines that should be active given the current context
+   */
+  async evaluateGuidelines(
+    context?: TContext,
+    session?: SessionState<TData>,
+    history?: Event[]
+  ): Promise<GuidelineMatch<TContext, TData>[]> {
+    const templateContext = { context, session, history, data: session?.data || {} };
+    const evaluator = createConditionEvaluator(templateContext);
+    const matches: GuidelineMatch<TContext, TData>[] = [];
+
+    for (const guideline of this.guidelines) {
+      // Skip disabled guidelines
+      if (guideline.enabled === false) {
+        continue;
+      }
+
+      if (guideline.condition) {
+        const evaluation = await evaluator.evaluateCondition(guideline.condition, 'AND');
+        
+        // Include guideline if:
+        // 1. No programmatic conditions (only strings) - always active
+        // 2. Programmatic conditions evaluate to true
+        if (!evaluation.hasProgrammaticConditions || evaluation.programmaticResult) {
+          const rationale = evaluation.aiContextStrings.length > 0
+            ? `Condition met: ${evaluation.aiContextStrings.join(" AND ")}`
+            : evaluation.hasProgrammaticConditions
+              ? "Programmatic condition evaluated to true"
+              : "Always active (no conditions)";
+          
+          matches.push({
+            guideline,
+            rationale
+          });
+        }
+      } else {
+        // No condition means always active
+        matches.push({
+          guideline,
+          rationale: "Always active (no conditions)"
+        });
+      }
+    }
+
+    return matches;
+  }
+
   /**
    * Add a tool to this step using the unified Tool interface
    * Creates and adds the tool to step scope in one operation
@@ -251,17 +309,17 @@ export class Step<TContext = unknown, TData = unknown> {
             resolvedTools.push(registeredTool);
           } else {
             // Tool not found - log warning but don't fail
-            console.warn(`[Step] Tool ID '${toolRef}' not found in any scope for step ${this.id}`);
+            logger.warn(`[Step] Tool ID '${toolRef}' not found in any scope for step ${this.id}`);
           }
         } else {
-          console.warn(`[Step] No parent agent available to resolve tool ID '${toolRef}' for step ${this.id}`);
+          logger.warn(`[Step] No parent agent available to resolve tool ID '${toolRef}' for step ${this.id}`);
         }
       } else {
         // Inline tool object - validate and use directly
         if (toolRef && toolRef.id && typeof toolRef.handler === 'function') {
           resolvedTools.push(toolRef);
         } else {
-          console.warn(`[Step] Invalid inline tool object in step ${this.id}:`, toolRef);
+          logger.warn(`[Step] Invalid inline tool object in step ${this.id}:`, toolRef);
         }
       }
     }
@@ -382,13 +440,63 @@ export class Step<TContext = unknown, TData = unknown> {
   }
 
   /**
-   * Check if this step should be skipped based on collected data
+   * Evaluate when condition using ConditionEvaluator
+   */
+  async evaluateWhen(
+    templateContext: TemplateContext<TContext, TData>
+  ): Promise<{ 
+    shouldActivate: boolean; 
+    aiContextStrings: string[];
+    hasProgrammaticConditions: boolean;
+  }> {
+    if (!this.when) {
+      return { 
+        shouldActivate: true, 
+        aiContextStrings: [], 
+        hasProgrammaticConditions: false 
+      };
+    }
+
+    const evaluator = createConditionEvaluator(templateContext);
+    const result = await evaluator.evaluateCondition(this.when, 'AND');
+    
+    return {
+      shouldActivate: result.programmaticResult,
+      aiContextStrings: result.aiContextStrings,
+      hasProgrammaticConditions: result.hasProgrammaticConditions
+    };
+  }
+
+  /**
+   * Evaluate skipIf condition using ConditionEvaluator
    */
-  shouldSkip(data: Partial<TData>): boolean {
-    if (!this.skipIf) return false;
-    return this.skipIf(data);
+  async evaluateSkipIf(
+    templateContext: TemplateContext<TContext, TData>
+  ): Promise<{ 
+    shouldSkip: boolean; 
+    aiContextStrings: string[];
+    hasProgrammaticConditions: boolean;
+  }> {
+    if (!this.skipIf) {
+      return { 
+        shouldSkip: false, 
+        aiContextStrings: [], 
+        hasProgrammaticConditions: false 
+      };
+    }
+
+    const evaluator = createConditionEvaluator(templateContext);
+    const result = await evaluator.evaluateCondition(this.skipIf, 'OR');
+    
+    return {
+      shouldSkip: result.programmaticResult,
+      aiContextStrings: result.aiContextStrings,
+      hasProgrammaticConditions: result.hasProgrammaticConditions
+    };
   }
 
+
+
   /**
    * Check if this step has all required data to proceed
    */
@@ -462,4 +570,24 @@ export class Step<TContext = unknown, TData = unknown> {
         this.endRoute(options),
     };
   }
+
+  /**
+   * Export step configuration as StepOptions for copying/cloning
+   * @returns StepOptions that can be used to create a new step with identical configuration
+   */
+  toOptions(): StepOptions<TContext, TData> {
+    return {
+      id: this.id,
+      description: this.description,
+      prompt: this.prompt,
+      tools: this.tools,
+      prepare: this.prepare,
+      finalize: this.finalize,
+      collect: this.collect,
+      skipIf: this.skipIf,
+      requires: this.requires,
+      when: this.when,
+      guidelines: this.getGuidelines(),
+    };
+  }
 }

package/src/index.ts

@@ -19,6 +19,8 @@ export { adaptEvent, convertHistoryToEvents } from "./core/Events";
 export { PersistenceManager } from "./core/PersistenceManager";
 export { SessionManager } from "./core/SessionManager";
 export { ToolManager, ToolCreationError, ToolExecutionError } from "./core/ToolManager";
+export { BatchExecutor, needsInput, type NeedsInputStep, type DetermineBatchParams } from "./core/BatchExecutor";
+export { BatchPromptBuilder, type BuildBatchPromptParams, type BatchPromptResult } from "./core/BatchPromptBuilder";
 
 // Providers
 export { GeminiProvider } from "./providers/GeminiProvider";
@@ -71,6 +73,12 @@ export { END_ROUTE, END_ROUTE_ID } from "./constants";
 // Utils
 export { generateRouteId, generateStepId, generateToolId } from "./utils/id";
 export { formatKnowledgeBase } from "./utils/template";
+export { 
+  ConditionEvaluator, 
+  createConditionEvaluator, 
+  extractAIContextStrings, 
+  hasProgrammaticConditions 
+} from "./utils/condition";
 export {
   normalizeHistory,
   historyItemToEvent,
@@ -86,6 +94,7 @@ export {
 // Types
 export type {
   AgentOptions,
+  AgentResponse,
   Term,
   Guideline,
   GuidelineMatch,
@@ -138,10 +147,20 @@ export type {
   PersistenceAdapter,
   Template,
   TemplateContext,
+  ConditionTemplate,
+  ConditionEvaluationResult,
   UserHistoryItem,
   AssistantHistoryItem,
   ToolHistoryItem,
   SystemHistoryItem,
+  // Multi-step execution types
+  StoppedReason,
+  BatchResult,
+  BatchExecutionResult,
+  BatchExecutionEvent,
+  BatchExecutionEventType,
+  BatchExecutionTiming,
+  BatchExecutionError,
 } from "./types";
 export { CompositionMode, EventKind, MessageRole } from "./types";
 export { createSession, enterRoute, enterStep, mergeCollected } from "./utils";

package/src/providers/AnthropicProvider.ts

@@ -15,7 +15,7 @@ import type {
   GenerateMessageStreamChunk,
   AgentStructuredResponse,
 } from "../types";
-import { withTimeoutAndRetry } from "../utils/retry";
+import { withTimeoutAndRetry, logger } from "../utils";
 
 const DEFAULT_RETRY_CONFIG = {
   timeout: 60000,
@@ -184,7 +184,7 @@ export class AnthropicProvider implements AiProvider {
       );
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
-      console.warn(
+      logger.warn(
         `[ANTHROPIC] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
       );
 
@@ -192,13 +192,13 @@ export class AnthropicProvider implements AiProvider {
         throw primaryError;
       }
 
-      console.log(`[ANTHROPIC] Trying backup models`);
+      logger.debug(`[ANTHROPIC] Trying backup models`);
 
       let lastBackupError: unknown = primaryError;
 
       for (let i = 0; i < this.backupModels.length; i++) {
         const backupModel = this.backupModels[i];
-        console.log(
+        logger.debug(
           `[ANTHROPIC] Trying backup model ${i + 1}/${
             this.backupModels.length
           }: ${backupModel}`
@@ -209,11 +209,11 @@ export class AnthropicProvider implements AiProvider {
             backupModel,
             input
           );
-          console.log(`[ANTHROPIC] Backup model ${backupModel} succeeded`);
+          logger.debug(`[ANTHROPIC] Backup model ${backupModel} succeeded`);
           return result;
         } catch (backupError: unknown) {
           const backupErrMsg = getErrorMessage(backupError);
-          console.warn(
+          logger.warn(
             `[ANTHROPIC] Backup model ${backupModel} failed: ${backupErrMsg}`
           );
           lastBackupError = backupError;
@@ -222,7 +222,7 @@ export class AnthropicProvider implements AiProvider {
             !shouldUseBackupModel(backupError) &&
             i < this.backupModels.length - 1
           ) {
-            console.log(
+            logger.debug(
               `[ANTHROPIC] Backup model error doesn't qualify for further attempts`
             );
             break;
@@ -231,7 +231,7 @@ export class AnthropicProvider implements AiProvider {
       }
 
       const lastBackupErrMsg = getErrorMessage(lastBackupError);
-      console.error(
+      logger.error(
         `[ANTHROPIC] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
       );
       throw lastBackupError;
@@ -325,7 +325,7 @@ export class AnthropicProvider implements AiProvider {
         try {
           structured = JSON.parse(message) as AgentStructuredResponse;
         } catch (error) {
-          console.warn("[ANTHROPIC] Failed to parse JSON response:", error);
+          logger.warn("[ANTHROPIC] Failed to parse JSON response:", error);
           // Fall back to treating the message as plain text
         }
       }
@@ -375,7 +375,7 @@ export class AnthropicProvider implements AiProvider {
       );
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
-      console.warn(
+      logger.warn(
         `[ANTHROPIC] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
       );
 
@@ -383,13 +383,13 @@ export class AnthropicProvider implements AiProvider {
         throw primaryError;
       }
 
-      console.log(`[ANTHROPIC] Trying backup models for streaming`);
+      logger.debug(`[ANTHROPIC] Trying backup models for streaming`);
 
       let lastBackupError: unknown = primaryError;
 
       for (let i = 0; i < this.backupModels.length; i++) {
         const backupModel = this.backupModels[i];
-        console.log(
+        logger.debug(
           `[ANTHROPIC] Trying backup model ${i + 1}/${
             this.backupModels.length
           }: ${backupModel}`
@@ -400,11 +400,11 @@ export class AnthropicProvider implements AiProvider {
             backupModel,
             input
           );
-          console.log(`[ANTHROPIC] Backup model ${backupModel} succeeded`);
+          logger.debug(`[ANTHROPIC] Backup model ${backupModel} succeeded`);
           return;
         } catch (backupError: unknown) {
           const backupErrMsg = getErrorMessage(backupError);
-          console.warn(
+          logger.warn(
             `[ANTHROPIC] Backup model ${backupModel} failed: ${backupErrMsg}`
           );
           lastBackupError = backupError;
@@ -413,7 +413,7 @@ export class AnthropicProvider implements AiProvider {
             !shouldUseBackupModel(backupError) &&
             i < this.backupModels.length - 1
           ) {
-            console.log(
+            logger.debug(
               `[ANTHROPIC] Backup model error doesn't qualify for further attempts`
             );
             break;
@@ -422,7 +422,7 @@ export class AnthropicProvider implements AiProvider {
       }
 
       const lastBackupErrMsg = getErrorMessage(lastBackupError);
-      console.error(
+      logger.error(
         `[ANTHROPIC] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
       );
       throw lastBackupError;
@@ -526,7 +526,7 @@ export class AnthropicProvider implements AiProvider {
       try {
         structured = JSON.parse(accumulated) as AgentStructuredResponse;
       } catch (error) {
-        console.warn(
+        logger.warn(
           "[ANTHROPIC] Failed to parse JSON response in stream:",
           error
         );