@falai/agent 0.6.3 → 0.6.5

package/examples/extracted-data-modification.ts

@@ -9,7 +9,14 @@
  * 5. Three-phase pipeline: PREPARATION → ROUTING → RESPONSE
  */
 
-import { Agent, createSession, EventSource, createMessageEvent } from "../src";
+import {
+  Agent,
+  createSession,
+  EventSource,
+  createMessageEvent,
+  END_STATE,
+  OpenAIProvider,
+} from "../src";
 import type { Event } from "../src/types";
 import type { ToolRef } from "../src/types/tool";
 
@@ -179,6 +186,20 @@ const searchFlightsTool: ToolRef<FlightBookingContext, [], void, FlightData> = {
   },
 };
 
+// Tool 4: Book the flight
+const bookFlightTool: ToolRef<FlightBookingContext, [], void, FlightData> = {
+  id: "book_flight",
+  name: "Book Flight",
+  description: "Finalize the flight booking",
+  handler: async (context) => {
+    const { extracted } = context;
+    const flightData = extracted as Partial<FlightData>;
+    console.log("[Tool] Booking flight with data:", flightData);
+    // Simulate booking API call
+    return { data: undefined };
+  },
+};
+
 // ==============================================================================
 // LIFECYCLE HOOKS: Data Validation & Business Logic (RESPONSE Phase)
 // ==============================================================================
@@ -236,7 +257,10 @@ const agent = new Agent<FlightBookingContext>({
   name: "Flight Booking Agent",
   goal: "Help users book flights efficiently",
   description: "I help you find and book flights",
-  ai: null as any, // Replace with actual AI provider
+  ai: new OpenAIProvider({
+    apiKey: process.env.OPENAI_API_KEY || "your-api-key-here",
+    model: "gpt-5o-mini",
+  }),
   context: {},
   hooks: {
     onExtractedUpdate, // Validation & enrichment hook
@@ -334,6 +358,21 @@ const presentResults = searchFlights.transitionTo({
   chatState: "Present available flights to the user",
 });
 
+// State 8: Confirm booking
+const confirmBooking = presentResults.transitionTo({
+  chatState: "Ask user to confirm the booking",
+  requiredData: ["destinationCode", "departureDateParsed", "passengers"],
+});
+
+// State 9: Finalize booking
+const finalizeBooking = confirmBooking.transitionTo({
+  toolState: bookFlightTool,
+  condition: "User confirms the booking",
+});
+
+// State 10: End of conversation
+finalizeBooking.transitionTo({ state: END_STATE });
+
 // ==============================================================================
 // USAGE EXAMPLE: Three-Phase Pipeline Demonstration
 // ==============================================================================
@@ -357,6 +396,11 @@ async function main() {
   console.log("Extracted:", response.session?.extracted);
   console.log("Context:", agent["context"]);
 
+  if (response.isRouteComplete) {
+    console.log("\n✅ Flight booking complete!");
+    await sendBookingConfirmation(response.session?.extracted);
+  }
+
   /*
    * Expected flow:
    * 1. AI extracts: { destination: "Paris", departureDate: "tomorrow", passengers: 2 }
@@ -374,6 +418,24 @@ async function main() {
    */
 }
 
+/**
+ * Mock function to send a booking confirmation.
+ * @param data - The flight booking data.
+ */
+async function sendBookingConfirmation(data: Partial<FlightData> | undefined) {
+  console.log("\n" + "=".repeat(60));
+  console.log("🚀 Sending Booking Confirmation...");
+  console.log("=".repeat(60));
+  console.log("Booking Details:", JSON.stringify(data, null, 2));
+  console.log(
+    `   - Sending confirmation for flight to ${data?.destinationCode} on ${
+      data?.departureDateParsed ?? ""
+    }.`
+  );
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log("✨ Confirmation sent!");
+}
+
 // ==============================================================================
 // KEY TAKEAWAYS: Architecture Principles Demonstrated
 // ==============================================================================

package/examples/healthcare-agent.ts

@@ -7,7 +7,7 @@ import {
   Agent,
   defineTool,
   AnthropicProvider,
-  END_ROUTE,
+  END_STATE,
   EventSource,
   createMessageEvent,
   createSession,
@@ -213,7 +213,7 @@ async function createHealthcareAgent() {
   });
 
   confirmation.transitionTo({
-    state: END_ROUTE,
+    state: END_STATE,
     condition: "Appointment booked successfully",
   });
 
@@ -232,7 +232,7 @@ async function createHealthcareAgent() {
       chatState:
         "Ask the patient to call the office to schedule an appointment",
     })
-    .transitionTo({ state: END_ROUTE });
+    .transitionTo({ state: END_STATE });
 
   schedulingRoute.createGuideline({
     condition: "The patient says their visit is urgent",
@@ -291,7 +291,7 @@ async function createHealthcareAgent() {
     chatState: "Present the lab results and explain what they mean",
   });
 
-  presentResults.transitionTo({ state: END_ROUTE });
+  presentResults.transitionTo({ state: END_STATE });
 
   labResultsRoute.createGuideline({
     condition:
@@ -383,9 +383,66 @@ async function main() {
 
     // Update session again
     session = response2.session!;
+
+    // Turn 3: Patient provides final details
+    const history3 = [
+      ...history2,
+      createMessageEvent(EventSource.AI_AGENT, "Agent", response2.message),
+      createMessageEvent(
+        EventSource.CUSTOMER,
+        "Patient",
+        "Tuesday at 2 PM works for me."
+      ),
+    ];
+
+    const response3 = await agent.respond({ history: history3, session });
+    console.log("\nPatient: Tuesday at 2 PM works for me.");
+    console.log("Agent:", response3.message);
+    console.log("Updated extracted:", response3.session?.extracted);
+    console.log("Current state:", response3.session?.currentState?.id);
+
+    // Check for route completion
+    if (response3.isRouteComplete) {
+      console.log("\n✅ Appointment scheduling complete!");
+      await sendAppointmentReminder(
+        agent.getExtractedData(
+          response3.session?.id
+        ) as unknown as AppointmentData
+      );
+    }
   }
 }
 
+/**
+ * Mock function to send an appointment reminder.
+ * @param data - The appointment data.
+ */
+async function sendAppointmentReminder(data: AppointmentData) {
+  console.log("\n" + "=".repeat(60));
+  console.log("🚀 Sending Appointment Reminder...");
+  console.log("=".repeat(60));
+  console.log("Appointment Details:", JSON.stringify(data, null, 2));
+  console.log(
+    `   - Sending reminder for ${data.appointmentReason} on ${data.preferredDate} at ${data.preferredTime}.`
+  );
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log("✨ Reminder sent!");
+}
+
+/**
+ * Mock function to log a patient inquiry about lab results.
+ * @param data - The lab results data.
+ */
+async function logPatientInquiry(data: LabResultsData) {
+  console.log("\n" + "=".repeat(60));
+  console.log("📝 Logging Patient Inquiry...");
+  console.log("=".repeat(60));
+  console.log("Inquiry Details:", JSON.stringify(data, null, 2));
+  console.log(`   - Logging inquiry for ${data.testType} results.`);
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log("✨ Inquiry logged!");
+}
+
 if (import.meta.url === `file://${process.argv[1]}`) {
   main().catch(console.error);
 }

package/examples/openai-agent.ts

@@ -10,7 +10,7 @@ import {
   createMessageEvent,
   EventSource,
   createSession,
-  END_ROUTE,
+  END_STATE,
 } from "../src/index";
 
 // Custom context type
@@ -151,7 +151,7 @@ async function main() {
       "Present the weather information in a friendly way with temperature and condition",
   });
 
-  showWeather.transitionTo({ state: END_ROUTE });
+  showWeather.transitionTo({ state: END_STATE });
 
   // Example conversation with session state management
   console.log("🤖 Starting OpenAI Agent Example\n");
@@ -191,6 +191,14 @@ async function main() {
     // Update session with progress
     session = response.session!;
 
+    // Check for route completion
+    if (response.isRouteComplete) {
+      console.log("\n✅ Weather route complete!");
+      await logWeatherRequest(
+        agent.getExtractedData(session.id) as WeatherData
+      );
+    }
+
     console.log("\n✨ Session state benefits:");
     console.log("   ✅ Data extraction tracked across turns");
     console.log("   ✅ State progression managed automatically");
@@ -203,6 +211,20 @@ async function main() {
   }
 }
 
+/**
+ * Mock function to log the weather request for analytics.
+ * @param data - The weather data from the completed route.
+ */
+async function logWeatherRequest(data: WeatherData) {
+  console.log("\n" + "=".repeat(60));
+  console.log("📊 Logging Weather Request for Analytics...");
+  console.log("=".repeat(60));
+  console.log("Request Details:", JSON.stringify(data, null, 2));
+  console.log(`   - Logging request for location: ${data.location}`);
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  console.log("✨ Request logged!");
+}
+
 // Run if executed directly
 if (import.meta.url === `file://${process.argv[1]}`) {
   main().catch(console.error);

package/examples/opensearch-persistence.ts

@@ -16,6 +16,7 @@ import {
   EventSource,
   MessageEventData,
   Event,
+  END_STATE,
 } from "../src/index";
 // @ts-ignore
 import { Client } from "@opensearch-project/opensearch";
@@ -157,7 +158,8 @@ async function example() {
     .transitionTo({
       chatState: "Propose solution and close complaint",
       requiredData: ["category", "description"],
-    });
+    })
+    .transitionTo({ state: END_STATE });
 
   const persistence = agent.getPersistenceManager();
   if (!persistence) return;
@@ -239,6 +241,13 @@ async function example() {
     content: response2.message,
   });
 
+  if (response2.isRouteComplete) {
+    console.log("\n✅ Complaint route complete!");
+    await createSupportTicket(
+      agent.getExtractedData(session.id) as ComplaintData
+    );
+  }
+
   // Load session from OpenSearch
   console.log("\n--- Loading Session from OpenSearch ---");
   const loadedSession = await persistence.loadSessionState<ComplaintData>(
@@ -471,6 +480,22 @@ async function timeSeriesExample() {
   }
 }
 
+/**
+ * Mock function to create a support ticket.
+ * @param data - The complaint data from the completed route.
+ */
+async function createSupportTicket(data: ComplaintData) {
+  console.log("\n" + "=".repeat(60));
+  console.log("🎫 Creating Support Ticket...");
+  console.log("=".repeat(60));
+  console.log("Ticket Details:", JSON.stringify(data, null, 2));
+  console.log(
+    `   - Creating ticket for category: ${data.category} with severity: ${data.severity}`
+  );
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log("✨ Ticket created successfully!");
+}
+
 // Run the example
 if (require.main === module) {
   example().catch(console.error);

package/examples/persistent-onboarding.ts

@@ -7,7 +7,8 @@ import {
   Agent,
   defineTool,
   GeminiProvider,
-  END_ROUTE,
+  END_STATE,
+  END_STATE_ID,
   EventSource,
   createMessageEvent,
   createSession,
@@ -269,24 +270,20 @@ async function createPersistentOnboardingAgent(sessionId: string) {
   });
 
   // State 1: Gather business name and description
-  const gatherBusinessInfo = onboardingRoute.initialState.transitionTo(
-    {
-      chatState: "Ask for business name and a brief description",
-      gather: ["businessName", "businessDescription"],
-      skipIf: (extracted) =>
-        !!extracted.businessName && !!extracted.businessDescription,
-    },
-    "Need to collect basic business information first"
-  );
+  const gatherBusinessInfo = onboardingRoute.initialState.transitionTo({
+    chatState: "Ask for business name and a brief description",
+    gather: ["businessName", "businessDescription"],
+    skipIf: (extracted) =>
+      !!extracted.businessName && !!extracted.businessDescription,
+    condition: "Need to collect basic business information first",
+  });
 
   // State 2: Save business info (tool execution)
-  const saveBusiness = gatherBusinessInfo.transitionTo(
-    {
-      toolState: saveBusinessInfo,
-      requiredData: ["businessName", "businessDescription"],
-    },
-    "Business name and description provided, save to database"
-  );
+  const saveBusiness = gatherBusinessInfo.transitionTo({
+    toolState: saveBusinessInfo,
+    requiredData: ["businessName", "businessDescription"],
+    condition: "Business name and description provided, save to database",
+  });
 
   // State 3: Gather industry
   const gatherIndustry = saveBusiness.transitionTo({
@@ -319,7 +316,7 @@ async function createPersistentOnboardingAgent(sessionId: string) {
     chatState: "Summarize all collected information and ask for confirmation",
   });
 
-  confirm.transitionTo({ state: END_ROUTE });
+  confirm.transitionTo({ state: END_STATE });
 
   // Guidelines
   onboardingRoute.createGuideline({
@@ -438,6 +435,15 @@ async function main() {
   console.log("🤖 Bot:", response1.message);
   console.log("📊 Extracted after turn 1:", response1.session?.extracted);
   console.log("📊 Route:", response1.session?.currentRoute?.title);
+
+  // Check route completion after turn 1
+  console.log("🔍 Route Completion Check (Turn 1):");
+  if (response1.isRouteComplete) {
+    console.log("   ✅ Route completed after turn 1!");
+  } else {
+    console.log("   ⏳ Route still in progress after turn 1");
+  }
+
   console.log();
 
   // Update session with progress
@@ -461,6 +467,15 @@ async function main() {
   const response2 = await agent.respond({ history: history2, session });
   console.log("🤖 Bot:", response2.message);
   console.log("📊 Extracted after turn 2:", response2.session?.extracted);
+
+  // Check route completion after turn 2
+  console.log("🔍 Route Completion Check (Turn 2):");
+  if (response2.isRouteComplete) {
+    console.log("   ✅ Route completed after turn 2!");
+  } else {
+    console.log("   ⏳ Route still in progress after turn 2");
+  }
+
   console.log();
 
   // Update session again
@@ -480,8 +495,43 @@ async function main() {
   const response3 = await agent.respond({ history: history3, session });
   console.log("🤖 Bot:", response3.message);
   console.log("📊 Extracted after turn 3:", response3.session?.extracted);
+
+  // Check route completion after turn 3
+  console.log("🔍 Route Completion Check (Turn 3):");
+  if (response3.isRouteComplete) {
+    console.log("   ✅ Route completed after turn 3!");
+  } else {
+    console.log("   ⏳ Route still in progress after turn 3");
+  }
+
   console.log();
 
+  // Update session again
+  session = response3.session!;
+
+  // Turn 4: User provides contact email, completing the flow
+  console.log("📱 Turn 4: User provides contact email");
+  const history4 = [
+    ...history3,
+    createMessageEvent(EventSource.AI_AGENT, "Agent", response3.message),
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Alice",
+      "Our contact email is contact@techflow.ai"
+    ),
+  ];
+  const response4 = await agent.respond({ history: history4, session });
+  console.log("🤖 Bot:", response4.message);
+  console.log("📊 Extracted after turn 4:", response4.session?.extracted);
+
+  // Check for route completion
+  if (response4.isRouteComplete) {
+    console.log("\n✅ Onboarding complete!");
+    await finalizeOnboarding(
+      agent.getExtractedData(response4.session?.id) as unknown as OnboardingData
+    );
+  }
+
   // Verify persistence
   console.log("=== PERSISTENCE VERIFICATION ===");
   const finalSession = await db.sessions.findById(sessionId);
@@ -529,6 +579,22 @@ async function main() {
  *    - No more LLM interpretation of state logic
  */
 
+/**
+ * Mock function to finalize the onboarding process.
+ * @param data - The complete onboarding data.
+ */
+async function finalizeOnboarding(data: OnboardingData) {
+  console.log("\n" + "=".repeat(60));
+  console.log("🚀 Finalizing Onboarding...");
+  console.log("=".repeat(60));
+  console.log("Onboarding Details:", JSON.stringify(data, null, 2));
+  console.log(`   - Sending welcome email to ${data.contactEmail}...`);
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log("   - Scheduling follow-up call...");
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  console.log("✨ Onboarding finalized!");
+}
+
 if (import.meta.url === `file://${process.argv[1]}`) {
   main().catch(console.error);
 }

package/examples/prisma-persistence.ts

@@ -11,7 +11,7 @@ import {
   PrismaAdapter,
   createMessageEvent,
   EventSource,
-  createSession,
+  END_STATE,
 } from "../src/index";
 
 // @ts-ignore
@@ -57,6 +57,21 @@ interface FlightBookingData {
   cabinClass: "economy" | "premium" | "business" | "first";
 }
 
+// Extracted data type for onboarding
+interface OnboardingData {
+  fullName: string;
+  email: string;
+  phoneNumber: string;
+  country: string;
+}
+
+// Extracted data type for contact form
+interface ContactFormData {
+  name: string;
+  email: string;
+  message: string;
+}
+
 async function example() {
   // Initialize Prisma client
   const prisma = new PrismaClient();
@@ -166,6 +181,8 @@ async function example() {
     requiredData: ["destination", "departureDate", "passengers", "cabinClass"],
   });
 
+  confirmBooking.transitionTo({ state: END_STATE });
+
   /**
    * Get persistence manager from agent
    */
@@ -305,6 +322,13 @@ async function example() {
 
   session = response2.session!;
 
+  if (response2.isRouteComplete) {
+    console.log("\n✅ Flight booking complete!");
+    await sendFlightConfirmation(
+      agent.getExtractedData(session.id) as FlightBookingData
+    );
+  }
+
   /**
    * Load session state from database (demonstrates persistence)
    */
@@ -356,13 +380,6 @@ async function advancedExample() {
     };
   }
 
-  interface OnboardingData {
-    fullName: string;
-    email: string;
-    phoneNumber: string;
-    country: string;
-  }
-
   const agent = new Agent<UserContext>({
     name: "Onboarding Assistant",
     description: "Help new users get started",
@@ -447,7 +464,8 @@ async function advancedExample() {
     })
     .transitionTo({
       chatState: "Confirm and complete onboarding",
-    });
+    })
+    .transitionTo({ state: END_STATE });
 
   const persistence = agent.getPersistenceManager()!;
 
@@ -481,6 +499,13 @@ async function advancedExample() {
     content: response.message,
   });
 
+  if (response.isRouteComplete) {
+    console.log("\n✅ Onboarding complete!");
+    await sendOnboardingEmail(
+      agent.getExtractedData(sessionData.id) as OnboardingData
+    );
+  }
+
   console.log("✅ Session state automatically saved to database!");
 
   await prisma.$disconnect();
@@ -492,12 +517,6 @@ async function advancedExample() {
 async function quickStart() {
   const prisma = new PrismaClient();
 
-  interface ContactFormData {
-    name: string;
-    email: string;
-    message: string;
-  }
-
   const agent = new Agent({
     name: "Support Agent",
     ai: new GeminiProvider({
@@ -532,7 +551,8 @@ async function quickStart() {
     })
     .transitionTo({
       chatState: "Confirm submission",
-    });
+    })
+    .transitionTo({ state: END_STATE });
 
   const persistence = agent.getPersistenceManager()!;
 
@@ -557,11 +577,65 @@ async function quickStart() {
 
   console.log("✅ Response:", response.message);
   console.log("📊 Extracted:", response.session?.extracted);
+
+  if (response.isRouteComplete) {
+    console.log("\n✅ Contact form submitted!");
+    await logContactForm(
+      agent.getExtractedData(sessionData.id) as ContactFormData
+    );
+  }
+
   console.log("💾 Session state auto-saved to Prisma!");
 
   await prisma.$disconnect();
 }
 
+/**
+ * Mock function to send a flight confirmation email.
+ * @param data - The flight booking data.
+ */
+async function sendFlightConfirmation(
+  data: Partial<FlightBookingData> | undefined
+) {
+  console.log("\n" + "=".repeat(60));
+  console.log("🚀 Sending Flight Confirmation...");
+  console.log("=".repeat(60));
+  console.log("Booking Details:", JSON.stringify(data, null, 2));
+  console.log(
+    `   - Sending confirmation for ${data?.passengers} passengers to ${data?.destination}.`
+  );
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log("✨ Confirmation sent!");
+}
+
+/**
+ * Mock function to send an onboarding email.
+ * @param data - The onboarding data.
+ */
+async function sendOnboardingEmail(data: Partial<OnboardingData> | undefined) {
+  console.log("\n" + "=".repeat(60));
+  console.log("🚀 Sending Onboarding Email...");
+  console.log("=".repeat(60));
+  console.log("Onboarding Details:", JSON.stringify(data, null, 2));
+  console.log(`   - Sending welcome email to ${data?.email}.`);
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log("✨ Email sent!");
+}
+
+/**
+ * Mock function to log a contact form submission.
+ * @param data - The contact form data.
+ */
+async function logContactForm(data: Partial<ContactFormData> | undefined) {
+  console.log("\n" + "=".repeat(60));
+  console.log("📝 Logging Contact Form Submission...");
+  console.log("=".repeat(60));
+  console.log("Submission Details:", JSON.stringify(data, null, 2));
+  console.log(`   - Logging message from ${data?.name}.`);
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  console.log("✨ Submission logged!");
+}
+
 // Run the example
 if (require.main === module) {
   example().catch(console.error);