@falai/agent 0.8.1 → 0.9.0-alpha-2

package/src/core/Route.ts

@@ -5,16 +5,21 @@
 import type {
   RouteOptions,
   RouteRef,
-  TransitionSpec,
-  TransitionResult,
+  StepOptions,
+  StepResult,
   RouteTransitionConfig,
   RouteCompletionHandler,
-} from "../types/route";
-import type { StructuredSchema } from "../types/schema";
-import type { Guideline } from "../types/agent";
+  RouteLifecycleHooks,
+  StructuredSchema,
+  Guideline,
+  Term,
+  Tool,
+  Template,
+} from "../types";
 
 import { Step } from "./Step";
 import { generateRouteId } from "../utils/id";
+import { END_ROUTE } from "../constants";
 
 /**
  * Represents a conversational route/journey
@@ -23,53 +28,76 @@ export class Route<TContext = unknown, TData = unknown> {
   public readonly id: string;
   public readonly title: string;
   public readonly description?: string;
-  public readonly conditions: string[];
-  public readonly domains?: string[];
-  public readonly rules: string[];
-  public readonly prohibitions: string[];
+  public readonly identity?: Template<TContext, TData>;
+  public readonly personality?: Template<TContext, TData>;
+  public readonly conditions: Template<TContext, TData>[];
+  public readonly rules: Template<TContext, TData>[];
+  public readonly prohibitions: Template<TContext, TData>[];
   public readonly initialStep: Step<TContext, TData>;
   public readonly endStepSpec: Omit<
-    TransitionSpec<TContext, TData>,
+    StepOptions<TContext, TData>,
     "step" | "condition" | "skipIf"
   >;
   public readonly responseOutputSchema?: StructuredSchema;
-  public readonly schema?: StructuredSchema;
   public readonly initialData?: Partial<TData>;
+  public readonly requiredFields?: (keyof TData)[];
+  public readonly optionalFields?: (keyof TData)[];
   public readonly onComplete?:
     | string
-    | RouteTransitionConfig
+    | RouteTransitionConfig<TContext, TData>
     | RouteCompletionHandler<TContext, TData>;
-  private routingExtrasSchema?: StructuredSchema;
-  private guidelines: Guideline[] = [];
+  public readonly hooks?: RouteLifecycleHooks<TContext, TData>;
+  public routingExtrasSchema?: StructuredSchema;
+  public guidelines: Guideline<TContext>[] = [];
+  public terms: Term<TContext>[] = [];
+  public tools: Tool<TContext, TData, unknown[], unknown>[] = [];
+  public knowledgeBase: Record<string, unknown> = {};
 
   constructor(options: RouteOptions<TContext, TData>) {
     // Use provided ID or generate a deterministic one from the title
     this.id = options.id || generateRouteId(options.title);
     this.title = options.title;
     this.description = options.description;
+    this.identity = options.identity;
+    this.personality = options.personality;
     this.conditions = options.conditions || [];
-    this.domains = options.domains;
-    this.rules = options.rules || ([] as string[]);
-    this.prohibitions = options.prohibitions || ([] as string[]);
-    this.initialStep = new Step<TContext, TData>(
-      this.id,
-      options.initialStep?.instructions || "Initial step",
-      options.initialStep?.id,
-      options.initialStep?.collect,
-      options.initialStep?.skipIf,
-      options.initialStep?.requires,
-      options.initialStep?.instructions
-    );
+    this.rules = options.rules || [];
+    this.prohibitions = options.prohibitions || [];
+
+    // Handle initial step logic
+    let initialStepOptions = options.initialStep;
+    let stepsToChain: StepOptions<TContext, TData>[] = [];
+
+    if (options.steps && options.steps.length > 0) {
+      // If steps are provided but no initialStep, use first step as initial
+      if (!options.initialStep) {
+        initialStepOptions = options.steps[0];
+        stepsToChain = options.steps.slice(1);
+      } else {
+        // Both initialStep and steps provided - chain steps after initial
+        stepsToChain = options.steps;
+      }
+    }
+
+    this.initialStep = new Step<TContext, TData>(this.id, initialStepOptions);
+
     // Store endStep spec (will be used when route completes)
     this.endStepSpec = options.endStep || {
-      instructions:
+      prompt:
         "Summarize what was accomplished and confirm completion based on the conversation history and collected data",
     };
     this.routingExtrasSchema = options.routingExtrasSchema;
     this.responseOutputSchema = options.responseOutputSchema;
-    this.schema = options.schema;
     this.initialData = options.initialData;
+    this.requiredFields = options.requiredFields;
+    this.optionalFields = options.optionalFields;
     this.onComplete = options.onComplete;
+    this.hooks = options.hooks;
+
+    // Initialize knowledge base
+    if (options.knowledgeBase) {
+      this.knowledgeBase = { ...options.knowledgeBase };
+    }
 
     // Initialize guidelines from options
     if (options.guidelines) {
@@ -78,9 +106,23 @@ export class Route<TContext = unknown, TData = unknown> {
       });
     }
 
+    // Initialize terms from options
+    if (options.terms) {
+      options.terms.forEach((term) => {
+        this.createTerm(term);
+      });
+    }
+
+    // Initialize tools from options
+    if (options.tools) {
+      options.tools.forEach((tool) => {
+        this.createTool(tool);
+      });
+    }
+
     // Build sequential steps if provided
-    if (options.steps && options.steps.length > 0) {
-      this.buildSequentialSteps(options.steps);
+    if (stepsToChain.length > 0) {
+      this.buildSequentialSteps(stepsToChain);
     }
   }
 
@@ -89,25 +131,24 @@ export class Route<TContext = unknown, TData = unknown> {
    * @private
    */
   private buildSequentialSteps(
-    steps: Array<TransitionSpec<TContext, TData>>
+    steps: Array<StepOptions<TContext, TData> | typeof END_ROUTE>
   ): void {
-    // Import END_ROUTE dynamically to avoid circular dependency
-    const END_ROUTE = Symbol.for("END_ROUTE");
-
-    let currentStep: TransitionResult<TContext, TData> = this.initialStep;
+    let currentStep: StepResult<TContext, TData> =
+      this.initialStep.asStepResult();
 
     for (const step of steps) {
-      currentStep = currentStep.nextStep(step);
+      if (step === END_ROUTE) {
+        currentStep.nextStep({ step: END_ROUTE });
+      } else {
+        currentStep = currentStep.nextStep(step);
+      }
     }
-
-    // End the route
-    currentStep.nextStep({ step: END_ROUTE });
   }
 
   /**
    * Create a guideline specific to this route
    */
-  createGuideline(guideline: Guideline): this {
+  createGuideline(guideline: Guideline<TContext>): this {
     this.guidelines.push({
       ...guideline,
       id: guideline.id || `guideline_${this.id}_${this.guidelines.length}`,
@@ -116,32 +157,69 @@ export class Route<TContext = unknown, TData = unknown> {
     return this;
   }
 
+  /**
+   * Create a term for the route's domain glossary
+   */
+  createTerm(term: Term<TContext>): this {
+    this.terms.push(term);
+    return this;
+  }
+
+  /**
+   * Register a tool for this route
+   */
+  createTool(tool: Tool<TContext, TData, unknown[], unknown>): this {
+    this.tools.push(tool);
+    return this;
+  }
+
+  /**
+   * Register multiple tools for this route
+   */
+  registerTools(tools: Tool<TContext, TData, unknown[], unknown>[]): this {
+    tools.forEach((tool) => this.createTool(tool));
+    return this;
+  }
+
   /**
    * Get all guidelines for this route
    */
-  getGuidelines(): Guideline[] {
+  getGuidelines(): Guideline<TContext>[] {
     return [...this.guidelines];
   }
 
   /**
-   * Get allowed domain names for this route
-   * @returns Array of domain names, or undefined if all domains are allowed
+   * Get all terms for this route
    */
-  getDomains(): string[] | undefined {
-    return this.domains ? [...this.domains] : undefined;
+  getTerms(): Term<TContext>[] {
+    return [...this.terms];
+  }
+
+  /**
+   * Get all tools for this route
+   */
+  getTools(): Tool<TContext, TData, unknown[], unknown>[] {
+    return [...this.tools];
+  }
+
+  /**
+   * Get the route's knowledge base
+   */
+  getKnowledgeBase(): Record<string, unknown> {
+    return { ...this.knowledgeBase };
   }
 
   /**
    * Get rules for this route
    */
-  getRules(): string[] {
+  getRules(): Template<TContext, TData>[] {
     return [...this.rules];
   }
 
   /**
    * Get prohibitions for this route
    */
-  getProhibitions(): string[] {
+  getProhibitions(): Template<TContext, TData>[] {
     return [...this.prohibitions];
   }
 
@@ -159,6 +237,10 @@ export class Route<TContext = unknown, TData = unknown> {
     return this.responseOutputSchema;
   }
 
+  getSteps(): Step<TContext, TData>[] {
+    return this.getAllSteps();
+  }
+
   /**
    * Get route reference
    */
@@ -187,10 +269,9 @@ export class Route<TContext = unknown, TData = unknown> {
       steps.push(current);
 
       // Add target steps from transitions
-      for (const transition of current.getTransitions()) {
-        const target = transition.getTarget();
-        if (target && !visited.has(target.id)) {
-          queue.push(target);
+      for (const nextStep of current.getTransitions()) {
+        if (nextStep && !visited.has(nextStep.id)) {
+          queue.push(nextStep);
         }
       }
     }
@@ -229,13 +310,101 @@ export class Route<TContext = unknown, TData = unknown> {
 
       const transitions = step.getTransitions();
       for (const transition of transitions) {
-        lines.push(`    -> ${transition.describe()}`);
+        lines.push(
+          `    -> ${transition.id}${
+            transition.description ? `: ${transition.description}` : ""
+          }`
+        );
       }
     }
 
     return lines.join("\n");
   }
 
+  /**
+   * Handle data updates for this route, calling the onDataUpdate hook if configured
+   * @param data - New collected data
+   * @param previousCollected - Previously collected data
+   * @returns Modified data after hook processing, or original data if no hook
+   */
+  async handleDataUpdate(
+    data: Partial<TData>,
+    previousCollected: Partial<TData>
+  ): Promise<Partial<TData>> {
+    // Call route-specific onDataUpdate hook if configured
+    if (this.hooks?.onDataUpdate) {
+      return await this.hooks.onDataUpdate(data, previousCollected);
+    }
+
+    // Return original data if no hook
+    return data;
+  }
+
+  /**
+   * Handle context updates for this route, calling the onContextUpdate hook if configured
+   * @param newContext - New context
+   * @param previousContext - Previous context
+   */
+  async handleContextUpdate(
+    newContext: TContext,
+    previousContext: TContext
+  ): Promise<void> {
+    // Call route-specific onContextUpdate hook if configured
+    if (this.hooks?.onContextUpdate) {
+      await this.hooks.onContextUpdate(newContext, previousContext);
+    }
+  }
+
+  /**
+   * Check if this route is complete based on the provided data
+   * @param data - Currently collected agent-level data
+   * @returns true if all required fields are present, false otherwise
+   */
+  isComplete(data: Partial<TData>): boolean {
+    if (!this.requiredFields || this.requiredFields.length === 0) {
+      return true; // No required fields means route is always complete
+    }
+
+    return this.requiredFields.every(field => {
+      const value = data[field];
+      return value !== undefined && value !== null && value !== '';
+    });
+  }
+
+  /**
+   * Get the list of missing required fields for this route
+   * @param data - Currently collected agent-level data
+   * @returns Array of missing required field keys
+   */
+  getMissingRequiredFields(data: Partial<TData>): (keyof TData)[] {
+    if (!this.requiredFields || this.requiredFields.length === 0) {
+      return [];
+    }
+
+    return this.requiredFields.filter(field => {
+      const value = data[field];
+      return value === undefined || value === null || value === '';
+    });
+  }
+
+  /**
+   * Get the completion progress for this route as a percentage
+   * @param data - Currently collected agent-level data
+   * @returns Completion progress as a number between 0 and 1
+   */
+  getCompletionProgress(data: Partial<TData>): number {
+    if (!this.requiredFields || this.requiredFields.length === 0) {
+      return 1; // No required fields means 100% complete
+    }
+
+    const completedFields = this.requiredFields.filter(field => {
+      const value = data[field];
+      return value !== undefined && value !== null && value !== '';
+    });
+
+    return completedFields.length / this.requiredFields.length;
+  }
+
   /**
    * Evaluate the onComplete handler and return transition config
    * @param session - Current session step
@@ -245,7 +414,7 @@ export class Route<TContext = unknown, TData = unknown> {
   async evaluateOnComplete(
     session: { data?: Partial<TData> },
     context?: TContext
-  ): Promise<RouteTransitionConfig | undefined> {
+  ): Promise<RouteTransitionConfig<TContext, TData> | undefined> {
     if (!this.onComplete) {
       return undefined;
     }