@falai/agent 0.5.5 → 0.6.0

package/examples/healthcare-agent.ts

@@ -130,7 +130,7 @@ async function createHealthcareAgent() {
     title: "Schedule an Appointment",
     description: "Helps the patient find a time for their appointment.",
     conditions: ["The patient wants to schedule an appointment"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         appointmentReason: {
@@ -161,25 +161,21 @@ async function createHealthcareAgent() {
   });
 
   // State 1: Gather appointment reason
-  const gatherReason = schedulingRoute.initialState.transitionTo(
-    {
-      chatState: "Ask what the patient needs an appointment for",
-      gather: ["appointmentReason"],
-      skipIf: (extracted) => !!extracted.appointmentReason,
-    },
-    "Patient hasn't specified reason for appointment yet"
-  );
+  const gatherReason = schedulingRoute.initialState.transitionTo({
+    chatState: "Ask what the patient needs an appointment for",
+    gather: ["appointmentReason"],
+    skipIf: (extracted) => !!extracted.appointmentReason,
+    condition: "Patient hasn't specified reason for appointment yet",
+  });
 
   // State 2: Check urgency and show available slots
-  const checkUrgency = gatherReason.transitionTo(
-    {
-      chatState: "Check if this is urgent and show available slots",
-      gather: ["urgency"],
-      skipIf: (extracted) => !!extracted.urgency,
-      requiredData: ["appointmentReason"],
-    },
-    "Reason provided, now assess urgency level"
-  );
+  const checkUrgency = gatherReason.transitionTo({
+    chatState: "Check if this is urgent and show available slots",
+    gather: ["urgency"],
+    skipIf: (extracted) => !!extracted.urgency,
+    requiredData: ["appointmentReason"],
+    condition: "Reason provided, now assess urgency level",
+  });
 
   const showSlots = checkUrgency.transitionTo({
     toolState: getUpcomingSlots,
@@ -206,22 +202,20 @@ async function createHealthcareAgent() {
     requiredData: ["appointmentReason", "preferredTime", "preferredDate"],
   });
 
-  const schedule = confirmDetails.transitionTo(
-    {
-      toolState: scheduleAppointment,
-      requiredData: ["appointmentReason", "preferredTime", "preferredDate"],
-    },
-    "All details confirmed, book the appointment"
-  );
+  const schedule = confirmDetails.transitionTo({
+    toolState: scheduleAppointment,
+    requiredData: ["appointmentReason", "preferredTime", "preferredDate"],
+    condition: "All details confirmed, book the appointment",
+  });
 
   const confirmation = schedule.transitionTo({
     chatState: "Confirm the appointment has been scheduled",
   });
 
-  confirmation.transitionTo(
-    { state: END_ROUTE },
-    "Appointment booked successfully"
-  );
+  confirmation.transitionTo({
+    state: END_ROUTE,
+    condition: "Appointment booked successfully",
+  });
 
   // Alternative path: no times work - show later slots
   const laterSlots = presentTimes.transitionTo({
@@ -250,7 +244,7 @@ async function createHealthcareAgent() {
     title: "Lab Results",
     description: "Retrieves the patient's lab results and explains them.",
     conditions: ["The patient wants to see their lab results"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         testType: {

package/examples/openai-agent.ts

@@ -112,7 +112,7 @@ async function main() {
     title: "Check Weather",
     description: "Help user check weather for a location",
     conditions: ["User wants to know the weather"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         location: {

package/examples/opensearch-persistence.ts

@@ -105,7 +105,7 @@ async function example() {
       "User reports an issue or problem",
       "User is dissatisfied",
     ],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         category: {
@@ -337,7 +337,7 @@ async function analyticsExample() {
 
   const ticketRoute = agent.createRoute<TicketData>({
     title: "Analyze Support Ticket",
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         ticketType: { type: "string" },

package/examples/persistent-onboarding.ts

@@ -244,7 +244,7 @@ async function createPersistentOnboardingAgent(sessionId: string) {
     title: "Business Onboarding",
     description: "Guide user through business information collection",
     conditions: ["User is onboarding their business"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         businessName: {
@@ -503,7 +503,7 @@ async function main() {
  *    - Always-on routing respects intent changes
  *
  * ✅ PATTERN 2: Schema-First Data Extraction
- *    - gatherSchema: Define data contracts upfront
+ *    - extractionSchema: Define data contracts upfront
  *    - Type-safe extraction throughout conversation
  *    - skipIf functions for deterministic state logic
  *    - requiredData arrays for prerequisites

package/examples/prisma-persistence.ts

@@ -96,7 +96,7 @@ async function example() {
       "User wants to book a flight",
       "User mentions travel, flying, or booking tickets",
     ],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         destination: {
@@ -413,7 +413,7 @@ async function advancedExample() {
   const onboardingRoute = agent.createRoute<OnboardingData>({
     title: "User Onboarding",
     description: "Collect user information for account setup",
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         fullName: { type: "string" },
@@ -514,7 +514,7 @@ async function quickStart() {
   // Create a simple contact form route
   const contactRoute = agent.createRoute<ContactFormData>({
     title: "Contact Form",
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         name: { type: "string" },

package/examples/redis-persistence.ts

@@ -88,7 +88,7 @@ async function example() {
       "User wants to report a problem",
       "User mentions support, help, or issue",
     ],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         issue: {
@@ -286,7 +286,7 @@ async function highThroughputExample() {
   // Simple chat route that extracts topic and sentiment
   const chatRoute = agent.createRoute<QuickChatData>({
     title: "General Chat",
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         topic: {
@@ -364,7 +364,7 @@ async function sessionRecoveryExample() {
 
   const orderRoute = agent.createRoute<OrderData>({
     title: "Place Order",
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         productId: { type: "string" },

package/examples/travel-agent.ts

@@ -223,7 +223,7 @@ async function createTravelAgent() {
     description:
       "Helps the customer find and book a flight to their desired destination.",
     conditions: ["The customer wants to book a flight"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         destination: {
@@ -270,85 +270,67 @@ async function createTravelAgent() {
   });
 
   // Build the route flow with data extraction and smart state progression
-  const askDestination = flightBookingRoute.initialState.transitionTo(
-    {
-      chatState: "Ask about the destination",
-      gather: ["destination"],
-      skipIf: (extracted) => !!extracted.destination,
-    },
-    "Customer needs to specify their travel destination"
-  );
+  const askDestination = flightBookingRoute.initialState.transitionTo({
+    chatState: "Ask about the destination",
+    gather: ["destination"],
+    skipIf: (extracted) => !!extracted.destination,
+    condition: "Customer needs to specify their travel destination",
+  });
 
-  const enrichDestination = askDestination.transitionTo(
-    {
-      toolState: lookupDestinationCode,
-      requiredData: ["destination"],
-    },
-    "Destination provided, lookup airport code"
-  );
+  const enrichDestination = askDestination.transitionTo({
+    toolState: lookupDestinationCode,
+    requiredData: ["destination"],
+    condition: "Destination provided, lookup airport code",
+  });
 
-  const askDates = enrichDestination.transitionTo(
-    {
-      chatState: "Ask about preferred travel dates",
-      gather: ["departureDate"],
-      skipIf: (extracted) => !!extracted.departureDate,
-      requiredData: ["destination"],
-    },
-    "Destination confirmed, need travel dates"
-  );
+  const askDates = enrichDestination.transitionTo({
+    chatState: "Ask about preferred travel dates",
+    gather: ["departureDate"],
+    skipIf: (extracted) => !!extracted.departureDate,
+    requiredData: ["destination"],
+    condition: "Destination confirmed, need travel dates",
+  });
 
-  const askPassengers = askDates.transitionTo(
-    {
-      chatState: "Ask for number of passengers",
-      gather: ["passengers"],
-      skipIf: (extracted) => !!extracted.passengers,
-      requiredData: ["destination", "departureDate"],
-    },
-    "Dates confirmed, need passenger count"
-  );
+  const askPassengers = askDates.transitionTo({
+    chatState: "Ask for number of passengers",
+    gather: ["passengers"],
+    skipIf: (extracted) => !!extracted.passengers,
+    requiredData: ["destination", "departureDate"],
+    condition: "Dates confirmed, need passenger count",
+  });
 
-  const searchFlightsState = askPassengers.transitionTo(
-    {
-      toolState: searchFlights,
-      // Triggered when shouldSearchFlights flag is set by hook
-    },
-    "All basic info gathered, search for available flights"
-  );
+  const searchFlightsState = askPassengers.transitionTo({
+    toolState: searchFlights,
+    // Triggered when shouldSearchFlights flag is set by hook
+    condition: "All basic info gathered, search for available flights",
+  });
 
-  const presentFlights = searchFlightsState.transitionTo(
-    {
-      chatState: "Present available flights and ask which one works for them",
-    },
-    "Flight search complete, present options to customer"
-  );
+  const presentFlights = searchFlightsState.transitionTo({
+    chatState: "Present available flights and ask which one works for them",
+    condition: "Flight search complete, present options to customer",
+  });
 
   // Happy path: customer selects a flight
-  const confirmBooking = presentFlights.transitionTo(
-    {
-      chatState: "Confirm booking details before proceeding",
-      gather: ["cabinClass", "urgency"], // Additional optional data
-    },
-    "Customer interested in a flight, confirm booking details"
-  );
+  const confirmBooking = presentFlights.transitionTo({
+    chatState: "Confirm booking details before proceeding",
+    gather: ["cabinClass", "urgency"], // Additional optional data
+    condition: "Customer interested in a flight, confirm booking details",
+  });
 
-  const bookFlightState = confirmBooking.transitionTo(
-    {
-      toolState: bookFlight,
-    },
-    "Customer confirmed, proceed with booking"
-  );
+  const bookFlightState = confirmBooking.transitionTo({
+    toolState: bookFlight,
+    condition: "Customer confirmed, proceed with booking",
+  });
 
-  const provideConfirmation = bookFlightState.transitionTo(
-    {
-      chatState: "Provide confirmation number and booking summary",
-    },
-    "Booking completed successfully"
-  );
+  const provideConfirmation = bookFlightState.transitionTo({
+    chatState: "Provide confirmation number and booking summary",
+    condition: "Booking completed successfully",
+  });
 
-  provideConfirmation.transitionTo(
-    { state: END_ROUTE },
-    "Customer has confirmation, booking flow complete"
-  );
+  provideConfirmation.transitionTo({
+    state: END_ROUTE,
+    condition: "Customer has confirmation, booking flow complete",
+  });
 
   // Add route-specific guidelines
   flightBookingRoute.createGuideline({
@@ -370,7 +352,7 @@ async function createTravelAgent() {
     description:
       "Retrieves the customer's booking status and provides relevant information.",
     conditions: ["The customer wants to check their booking status"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         confirmationNumber: {
@@ -386,34 +368,29 @@ async function createTravelAgent() {
     },
   });
 
-  const askConfirmation = bookingStatusRoute.initialState.transitionTo(
-    {
-      chatState: "Ask for the confirmation number or booking reference",
-      gather: ["confirmationNumber"],
-      skipIf: (extracted) => !!extracted.confirmationNumber,
-    },
-    "Customer wants to check booking status but hasn't provided confirmation number"
-  );
+  const askConfirmation = bookingStatusRoute.initialState.transitionTo({
+    chatState: "Ask for the confirmation number or booking reference",
+    gather: ["confirmationNumber"],
+    skipIf: (extracted) => !!extracted.confirmationNumber,
+    condition:
+      "Customer wants to check booking status but hasn't provided confirmation number",
+  });
 
-  const checkStatus = askConfirmation.transitionTo(
-    {
-      toolState: getBookingStatus,
-      requiredData: ["confirmationNumber"],
-    },
-    "Confirmation number provided, look up booking details"
-  );
+  const checkStatus = askConfirmation.transitionTo({
+    toolState: getBookingStatus,
+    requiredData: ["confirmationNumber"],
+    condition: "Confirmation number provided, look up booking details",
+  });
 
-  const provideStatus = checkStatus.transitionTo(
-    {
-      chatState: "Provide booking status and relevant information",
-    },
-    "Booking status retrieved successfully"
-  );
+  const provideStatus = checkStatus.transitionTo({
+    chatState: "Provide booking status and relevant information",
+    condition: "Booking status retrieved successfully",
+  });
 
-  provideStatus.transitionTo(
-    { state: END_ROUTE },
-    "Booking information provided to customer"
-  );
+  provideStatus.transitionTo({
+    state: END_ROUTE,
+    condition: "Booking information provided to customer",
+  });
 
   // Global guidelines
   agent.createGuideline({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/ResponseEngine.ts

@@ -30,9 +30,9 @@ export class ResponseEngine<TContext = unknown> {
     }
 
     // Add gather fields from current state
-    if (currentState?.gatherFields && route.gatherSchema?.properties) {
+    if (currentState?.gatherFields && route.extractionSchema?.properties) {
       for (const field of currentState.gatherFields) {
-        const fieldSchema = route.gatherSchema.properties[field];
+        const fieldSchema = route.extractionSchema.properties[field];
         if (fieldSchema) {
           base.properties![field] = fieldSchema;
         }

package/src/core/Route.ts

@@ -2,7 +2,12 @@
  * Route (Journey) DSL implementation
  */
 
-import type { RouteOptions, RouteRef } from "../types/route";
+import type {
+  RouteOptions,
+  RouteRef,
+  TransitionSpec,
+  TransitionResult,
+} from "../types/route";
 import type { StructuredSchema } from "../types/schema";
 import type { Guideline } from "../types/agent";
 
@@ -22,7 +27,7 @@ export class Route<TContext = unknown, TExtracted = unknown> {
   public readonly prohibitions: string[];
   public readonly initialState: State<TContext, TExtracted>;
   public readonly responseOutputSchema?: StructuredSchema;
-  public readonly gatherSchema?: StructuredSchema;
+  public readonly extractionSchema?: StructuredSchema;
   public readonly initialData?: Partial<TExtracted>;
   private routingExtrasSchema?: StructuredSchema;
   private guidelines: Guideline[] = [];
@@ -42,7 +47,7 @@ export class Route<TContext = unknown, TExtracted = unknown> {
     );
     this.routingExtrasSchema = options.routingExtrasSchema;
     this.responseOutputSchema = options.responseOutputSchema;
-    this.gatherSchema = options.gatherSchema;
+    this.extractionSchema = options.extractionSchema;
     this.initialData = options.initialData;
 
     // Initialize guidelines from options
@@ -51,6 +56,32 @@ export class Route<TContext = unknown, TExtracted = unknown> {
         this.createGuideline(guideline);
       });
     }
+
+    // Build sequential steps if provided
+    if (options.steps && options.steps.length > 0) {
+      this.buildSequentialSteps(options.steps);
+    }
+  }
+
+  /**
+   * Build a sequential state machine from an array of steps
+   * @private
+   */
+  private buildSequentialSteps(
+    steps: Array<TransitionSpec<TContext, TExtracted>>
+  ): void {
+    // Import END_ROUTE dynamically to avoid circular dependency
+    const END_ROUTE = Symbol.for("END_ROUTE");
+
+    let currentState: TransitionResult<TContext, TExtracted> =
+      this.initialState;
+
+    for (const step of steps) {
+      currentState = currentState.transitionTo(step);
+    }
+
+    // End the route
+    currentState.transitionTo({ state: END_ROUTE });
   }
 
   /**

package/src/core/State.ts

@@ -43,12 +43,10 @@ export class State<TContext = unknown, TExtracted = unknown> {
    * Create a transition from this state to another
    *
    * @param spec - Transition specification (chatState, toolState, or direct state)
-   * @param condition - Optional condition for this transition
    * @returns TransitionResult that supports chaining
    */
   transitionTo(
-    spec: TransitionSpec<TContext, TExtracted>,
-    condition?: string
+    spec: TransitionSpec<TContext, TExtracted>
   ): TransitionResult<TContext, TExtracted> {
     // Handle END_ROUTE
     if (
@@ -58,8 +56,7 @@ export class State<TContext = unknown, TExtracted = unknown> {
     ) {
       const endTransition = new Transition<TContext, TExtracted>(
         this.getRef(),
-        { state: END_ROUTE },
-        condition
+        { state: END_ROUTE, condition: spec.condition }
       );
       this.transitions.push(endTransition);
 
@@ -71,8 +68,7 @@ export class State<TContext = unknown, TExtracted = unknown> {
     if (spec.state && typeof spec.state !== "symbol") {
       const transition = new Transition<TContext, TExtracted>(
         this.getRef(),
-        spec,
-        condition
+        spec
       );
       this.transitions.push(transition);
 
@@ -90,8 +86,7 @@ export class State<TContext = unknown, TExtracted = unknown> {
     );
     const transition = new Transition<TContext, TExtracted>(
       this.getRef(),
-      spec,
-      condition
+      spec
     );
     transition.setTarget(targetState);
 
@@ -160,10 +155,8 @@ export class State<TContext = unknown, TExtracted = unknown> {
 
     return {
       ...ref,
-      transitionTo: (
-        spec: TransitionSpec<TContext, TExtracted>,
-        condition?: string
-      ) => stateInstance.transitionTo(spec, condition),
+      transitionTo: (spec: TransitionSpec<TContext, TExtracted>) =>
+        stateInstance.transitionTo(spec),
     };
   }
 

package/src/core/Transition.ts

@@ -10,12 +10,15 @@ import type { State } from "./State";
  */
 export class Transition<TContext = unknown, TExtracted = unknown> {
   private target?: State<TContext, TExtracted>;
+  public readonly condition?: string;
 
   constructor(
     public readonly source: StateRef,
-    public readonly spec: TransitionSpec<TContext, TExtracted>,
-    public readonly condition?: string
-  ) {}
+    public readonly spec: TransitionSpec<TContext, TExtracted>
+  ) {
+    // Extract condition from spec for convenience
+    this.condition = spec.condition;
+  }
 
   /**
    * Set the target state for this transition

package/src/types/route.ts

@@ -30,7 +30,7 @@ import type { Guideline } from "./agent";
 
 /**
  * Options for creating a route
- * @template TExtracted - Type of data extracted throughout the route (inferred from gatherSchema)
+ * @template TExtracted - Type of data extracted throughout the route (inferred from extractionSchema)
  */
 export interface RouteOptions<TExtracted = unknown> {
   /** Custom ID for the route (optional - will generate deterministic ID from title if not provided) */
@@ -57,13 +57,19 @@ export interface RouteOptions<TExtracted = unknown> {
    * NEW: Schema defining data to extract throughout this route
    * This creates a type-safe contract for what data the route collects
    */
-  gatherSchema?: StructuredSchema;
+  extractionSchema?: StructuredSchema;
   /**
    * NEW: Initial data to pre-populate when entering this route
    * Useful for restoring sessions or pre-filling known information
    * States with skipIf conditions will be automatically bypassed if data is present
    */
   initialData?: Partial<TExtracted>;
+  /**
+   * NEW: Sequential steps for simple linear flows
+   * If provided, automatically chains the steps from initialState to END_ROUTE
+   * For complex flows with branching, build the state machine manually instead
+   */
+  steps?: TransitionSpec<unknown, TExtracted>[];
 }
 
 /**
@@ -81,7 +87,7 @@ export interface TransitionSpec<TContext = unknown, TExtracted = unknown> {
   state?: StateRef | symbol;
   /**
    * NEW: Fields to gather from the conversation in this state
-   * These should match keys in the route's gatherSchema
+   * These should match keys in the route's extractionSchema
    */
   gather?: string[];
   /**
@@ -97,6 +103,11 @@ export interface TransitionSpec<TContext = unknown, TExtracted = unknown> {
    * Uses string[] for developer-friendly usage (same as gather)
    */
   requiredData?: string[];
+  /**
+   * Optional condition for this transition
+   * Description of when this transition should be taken
+   */
+  condition?: string;
 }
 
 /**
@@ -107,7 +118,6 @@ export interface TransitionResult<TContext = unknown, TExtracted = unknown>
   extends StateRef {
   /** Allow chaining transitions */
   transitionTo: (
-    spec: TransitionSpec<TContext, TExtracted>,
-    condition?: string
+    spec: TransitionSpec<TContext, TExtracted>
   ) => TransitionResult<TContext, TExtracted>;
 }