@falai/agent 0.8.0 → 0.9.0-alpha-1

package/examples/{route-transitions.ts → conversation-flows/completion-transitions.ts}

@@ -11,11 +11,9 @@
 import {
   Agent,
   GeminiProvider,
-  createMessageEvent,
-  EventSource,
-  END_ROUTE,
-  type SessionStep,
-} from "../src/index";
+  History,
+  type SessionState,
+} from "../../src/index";
 
 // Type definitions for our booking data
 interface BookingData {
@@ -36,13 +34,13 @@ async function main() {
     description: "A hotel booking assistant with feedback collection",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
-      model: "models/gemini-2.0-flash-exp",
+      model: "models/gemini-2.5-flash",
     }),
     debug: true,
   });
 
-  // Route 1: Hotel Booking
-  const bookingRoute = agent.createRoute<BookingData>({
+  // Route 1: Hotel Booking with automatic transition to feedback
+  agent.createRoute<BookingData>({
     title: "Book Hotel",
     description: "Collects hotel booking information",
     conditions: ["User wants to book a hotel"],
@@ -55,99 +53,97 @@ async function main() {
       },
       required: ["hotelName", "date", "guests"],
     },
-    // Configure completion message at route level
-    endStep: {
-      instructions:
-        "Confirm the booking with a summary of the hotel, date, and number of guests. Be enthusiastic!",
-    },
-    // Option 1: Simple string
+    // Sequential steps for booking flow
+    steps: [
+      {
+        id: "ask_hotel",
+        description: "Ask for hotel preference",
+        prompt: "Which hotel would you like to book?",
+        collect: ["hotelName"],
+        skipIf: (data: Partial<BookingData>) => !!data.hotelName,
+      },
+      {
+        id: "ask_date",
+        description: "Ask for booking date",
+        prompt: "What date would you like to book for?",
+        collect: ["date"],
+        requires: ["hotelName"],
+        skipIf: (data: Partial<BookingData>) => !!data.date,
+      },
+      {
+        id: "ask_guests",
+        description: "Ask for number of guests",
+        prompt: "How many guests will be staying?",
+        collect: ["guests"],
+        requires: ["hotelName", "date"],
+        skipIf: (data: Partial<BookingData>) => data.guests !== undefined,
+      },
+      {
+        id: "confirm_booking",
+        description: "Confirm the booking",
+        prompt:
+          "Confirm the booking with a summary of the hotel, date, and number of guests. Be enthusiastic!",
+        requires: ["hotelName", "date", "guests"],
+      },
+    ],
+    // Automatic transition to feedback collection when booking completes
     onComplete: "Collect Feedback",
-    // Option 2: Object with condition
-    // onComplete: {
-    //   nextStep: "Collect Feedback",
-    //   condition: "if booking was successful"
-    // },
-    // Option 3: Function with logic
-    // onComplete: (session) => {
-    //   if (session.data?.guests && session.data.guests > 5) {
-    //     return "VIP Feedback"; // Different feedback for large groups
-    //   }
-    //   return "Collect Feedback";
-    // },
-  });
-
-  const askHotel = bookingRoute.initialStep.nextStep({
-    instructions: "Ask which hotel they want to book",
-    collect: ["hotelName"],
-    skipIf: (data) => !!data.hotelName,
-  });
-
-  const askDate = askHotel.nextStep({
-    instructions: "Ask for the booking date",
-    collect: ["date"],
-    skipIf: (data) => !!data.date,
-  });
-
-  const askGuests = askDate.nextStep({
-    instructions: "Ask for the number of guests",
-    collect: ["guests"],
-    skipIf: (data) => !!data.guests,
-  });
-
-  // No need to specify instructions here - using route-level endStep configuration
-  askGuests.nextStep({
-    step: END_ROUTE,
   });
 
   // Route 2: Feedback Collection
-  const feedbackRoute = agent.createRoute<FeedbackData>({
+  agent.createRoute<FeedbackData>({
     title: "Collect Feedback",
     description: "Collects user feedback after booking",
     conditions: ["User wants to provide feedback"],
     schema: {
       type: "object",
       properties: {
-        rating: { type: "number" },
+        rating: { type: "number", minimum: 1, maximum: 5 },
         comments: { type: "string" },
       },
       required: ["rating"],
     },
-    // Configure completion message for feedback route
-    endStep: {
-      instructions:
-        "Thank the user warmly for their feedback and let them know their input is valuable",
-    },
-  });
-
-  const askRating = feedbackRoute.initialStep.nextStep({
-    instructions: "Ask for rating from 1 to 5",
-    collect: ["rating"],
-    skipIf: (data) => !!data.rating,
-  });
-
-  const askComments = askRating.nextStep({
-    instructions: "Ask for any additional comments (optional)",
-    collect: ["comments"],
-  });
-
-  // No need to specify instructions here - using route-level endStep configuration
-  askComments.nextStep({
-    step: END_ROUTE,
+    // Sequential steps for feedback collection
+    steps: [
+      {
+        id: "ask_rating",
+        description: "Ask for rating",
+        prompt: "How would you rate your booking experience from 1 to 5?",
+        collect: ["rating"],
+        skipIf: (data: Partial<FeedbackData>) => data.rating !== undefined,
+      },
+      {
+        id: "ask_comments",
+        description: "Ask for comments",
+        prompt:
+          "Would you like to share any additional comments about your experience?",
+        collect: ["comments"],
+      },
+      {
+        id: "thank_feedback",
+        description: "Thank user for feedback",
+        prompt:
+          "Thank the user warmly for their feedback and let them know their input is valuable",
+        requires: ["rating"],
+      },
+    ],
+    // End conversation after feedback is collected
+    onComplete: undefined, // No transition - conversation ends
   });
 
   console.log("\n=== Route Transitions Example ===\n");
 
   // Conversation 1: User provides all booking info at once
-  let session: SessionStep | undefined;
-  let history = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Alice",
-      "I want to book the Grand Hotel for 2 guests on December 25th"
-    ),
+  let session: SessionState | undefined;
+  let history: History = [
+    {
+      role: "user" as const,
+      content: "I want to book the Grand Hotel for 2 guests on December 25th",
+      name: "Alice",
+    },
   ];
 
-  console.log("User:", history[0].data.message);
+  console.log("User:", history[0].content);
 
   // First response - should handle booking
   const response1 = await agent.respond({ history, session });
@@ -163,15 +159,19 @@ async function main() {
   history = [
     ...history,
     {
-      ...createMessageEvent(EventSource.AI_AGENT, "Bot", response1.message),
-      id: "2",
+      role: "assistant" as const,
+      content: response1.message,
     },
-  ];
+  ] as History;
 
   // Second response - should auto-transition to a feedback route
   history = [
     ...history,
-    createMessageEvent(EventSource.CUSTOMER, "Alice", "Yes, please proceed!"),
+    {
+      role: "user" as const,
+      content: "Yes, please proceed!",
+      name: "Alice",
+    },
   ];
   console.log("\nUser:", "Yes, please proceed!");
 
@@ -184,19 +184,19 @@ async function main() {
   history = [
     ...history,
     {
-      ...createMessageEvent(EventSource.AI_AGENT, "Bot", response2.message),
-      id: "4",
+      role: "assistant" as const,
+      content: response2.message,
     },
   ];
 
   // Third response - provide rating
   history = [
     ...history,
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Alice",
-      "I'd rate it 5 stars! The process was very smooth."
-    ),
+    {
+      role: "user" as const,
+      content: "I'd rate it 5 stars! The process was very smooth.",
+      name: "Alice",
+    },
   ];
   console.log("\nUser:", "I'd rate it 5 stars! The process was very smooth.");
 
@@ -209,16 +209,17 @@ async function main() {
   console.log("\n=== Manual Transition Example ===\n");
 
   // Demonstrate manual transition using agent.nextStepRoute()
-  let session2: SessionStep | undefined;
-  let history2 = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Bob",
-      "I want to book the Sunset Resort for 4 people on New Year's Eve"
-    ),
+  let session2: SessionState | undefined;
+  let history2: History = [
+    {
+      role: "user" as const,
+      content:
+        "I want to book the Sunset Resort for 4 people on New Year's Eve",
+      name: "Bob",
+    },
   ];
 
-  console.log("User:", history2[0].data.message);
+  console.log("User:", history2[0].content);
 
   const manualResponse = await agent.respond({
     history: history2,
@@ -230,7 +231,11 @@ async function main() {
   if (manualResponse.isRouteComplete && manualResponse.session) {
     // Manually trigger transition instead of auto-transition
     console.log("\n[Manually transitioning to feedback route...]");
-    session2 = agent.nextStepRoute("Collect Feedback", manualResponse.session);
+    session2 = await agent.nextStepRoute(
+      "Collect Feedback",
+      manualResponse.session,
+      "if booking was successful"
+    );
     console.log(
       "Pending transition set:",
       session2.pendingTransition?.targetRouteId
@@ -239,14 +244,14 @@ async function main() {
     history2 = [
       ...history2,
       {
-        ...createMessageEvent(
-          EventSource.AI_AGENT,
-          "Bot",
-          manualResponse.message
-        ),
-        id: "2",
+        role: "assistant" as const,
+        content: manualResponse.message,
+      },
+      {
+        role: "user" as const,
+        content: "Great!",
+        name: "Bob",
       },
-      createMessageEvent(EventSource.CUSTOMER, "Bob", "Great!"),
     ];
 
     const feedbackResponse = await agent.respond({
@@ -263,4 +268,6 @@ async function main() {
   console.log("\n=== Done ===\n");
 }
 
-main().catch(console.error);
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}