@falai/agent 0.6.3 → 0.6.4

package/examples/business-onboarding.ts

@@ -13,7 +13,7 @@
 import {
   Agent,
   defineTool,
-  END_ROUTE,
+  END_STATE,
   EventSource,
   createMessageEvent,
   OpenAIProvider,
@@ -563,7 +563,7 @@ async function createBusinessOnboardingAgent(
     condition: "User confirmed everything is okay",
   });
 
-  completion.transitionTo({ state: END_ROUTE });
+  completion.transitionTo({ state: END_STATE });
 
   // ==================== Alternative: Sequential Steps ====================
   // For simpler linear flows, you can use the new sequential steps approach:
@@ -619,7 +619,7 @@ async function createBusinessOnboardingAgent(
       chatState: "Thank you for your feedback! It helps us improve. 🙏",
       condition: "User provided feedback",
     })
-    .transitionTo({ state: END_ROUTE });
+    .transitionTo({ state: END_STATE });
 
   // ==================== Global Guidelines ====================
 
@@ -722,15 +722,31 @@ async function main() {
   try {
     // Initialize session state for multi-turn conversation
     let session = createSession<OnboardingData>();
+    agent.setCurrentSession(session);
 
-    const response = await agent.respond({ history, session });
+    const response = await agent.respond({ history });
     console.log("Agent:", response.message);
     console.log("\nRoute:", response.session?.currentRoute?.title);
-    console.log("Extracted:", response.session?.extracted);
+
+    // After the conversation, you can get the extracted data
+    const extractedData = agent.getExtractedData<OnboardingData>();
+    console.log("Extracted:", extractedData);
 
     // Update session with progress
     session = response.session!;
 
+    // You can also pass the session to the agent constructor
+    // const agentWithSession = await createBusinessOnboardingAgent("user_123", "Alice", "session_456", {}, session);
+    // const response2 = await agentWithSession.respond({ history });
+
+    if (response.isRouteComplete) {
+      console.log("\n✅ Onboarding route complete!");
+      // Here you would typically save the complete data to your database
+      await processOnboardingData(agent.getExtractedData());
+    } else {
+      console.log("\n⏳ Onboarding route in progress...");
+    }
+
     console.log("\n✅ Session state benefits:");
     console.log("   - Data extraction tracked across turns");
     console.log("   - State progression managed automatically");
@@ -741,6 +757,31 @@ async function main() {
   }
 }
 
+/**
+ * Mock function to process completed onboarding data
+ * @param data - The complete onboarding data
+ */
+async function processOnboardingData(data: Partial<OnboardingData>) {
+  console.log("\n" + "=".repeat(60));
+  console.log("🚀 Processing Completed Onboarding Data...");
+  console.log("=".repeat(60));
+  console.log("Received data:", JSON.stringify(data, null, 2));
+
+  // Example: Save to a database
+  console.log("\n💾 Saving to database...");
+  await new Promise((resolve) => setTimeout(resolve, 1000)); // Simulate async operation
+  console.log("   - Business Info:", data.business?.businessName);
+  console.log("   - Contact Info:", data.contact?.website);
+  console.log("   - Location Info:", data.location?.address);
+
+  // Example: Triggering a welcome email
+  console.log("\n📧 Sending welcome email...");
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log(`   - Email sent to user associated with the account.`);
+
+  console.log("\n✨ Onboarding processing complete!");
+}
+
 // Run if executed directly
 if (import.meta.url === `file://${process.argv[1]}`) {
   main().catch(console.error);

package/examples/company-qna-agent.ts

@@ -15,6 +15,8 @@ import {
   EventSource,
   createMessageEvent,
   EventKind,
+  END_STATE,
+  OpenAIProvider,
 } from "../src";
 import type { Event } from "../src/types";
 import type { ToolRef } from "../src/types/tool";
@@ -54,6 +56,12 @@ interface CompanyContext {
   }>;
 }
 
+interface FeedbackData {
+  rating?: number;
+  comments?: string;
+  contactPermission?: boolean;
+}
+
 // ==============================================================================
 // TOOLS: Context Enrichment (PREPARATION Phase)
 // ==============================================================================
@@ -138,7 +146,10 @@ const agent = new Agent<CompanyContext>({
     "I'm here to help you learn about Acme Corp, our products, and policies",
   personality:
     "Friendly, helpful, and knowledgeable. Always professional but approachable.",
-  ai: null as any, // Replace with actual AI provider
+  ai: new OpenAIProvider({
+    apiKey: process.env.OPENAI_API_KEY || "test-key",
+    model: "gpt-5o-mini",
+  }),
 
   // Initialize with company knowledge
   context: {
@@ -325,6 +336,57 @@ const fallbackRoute = agent.createRoute({
 
 // Initial state is enough for fallback conversations
 
+// Route 7: Collect Feedback (Stateful Example)
+const feedbackRoute = agent.createRoute<FeedbackData>({
+  title: "Collect Feedback",
+  description: "Collect user feedback about their experience",
+  conditions: ["User wants to leave feedback", "User seems satisfied or upset"],
+  extractionSchema: {
+    type: "object",
+    properties: {
+      rating: {
+        type: "number",
+        description: "A rating from 1 to 5",
+        minimum: 1,
+        maximum: 5,
+      },
+      comments: { type: "string", description: "Open-ended feedback" },
+      contactPermission: {
+        type: "boolean",
+        description: "Permission to contact the user for more details",
+      },
+    },
+    required: ["rating", "comments"],
+  },
+});
+
+feedbackRoute.initialState
+  .transitionTo({
+    id: "ask_rating",
+    chatState:
+      "I'd love to hear your feedback. On a scale of 1 to 5, how would you rate your experience with me today?",
+    gather: ["rating"],
+  })
+  .transitionTo({
+    id: "ask_comments",
+    chatState:
+      "Thanks for the rating! Do you have any specific comments or suggestions?",
+    gather: ["comments"],
+    requiredData: ["rating"],
+  })
+  .transitionTo({
+    id: "ask_permission",
+    chatState:
+      "Thank you for the detailed feedback. Would it be okay if our team contacted you for more details?",
+    gather: ["contactPermission"],
+    requiredData: ["comments"],
+  })
+  .transitionTo({
+    id: "thank_you",
+    chatState: "Thank you for your valuable feedback!",
+  })
+  .transitionTo({ state: END_STATE });
+
 // ==============================================================================
 // USAGE EXAMPLES: Three-Phase Pipeline Demonstration
 // ==============================================================================
@@ -439,6 +501,50 @@ async function exampleConversations() {
   console.log("User: How much does it cost?");
   console.log("AI:", resp2.message);
   // AI understands "it" refers to Acme Widget from context
+
+  // =========================================================================
+  // Example 6: Stateful feedback collection
+  // =========================================================================
+  console.log("\n=== EXAMPLE 6: Stateful Feedback Collection ===");
+  const feedbackHistory: Event[] = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "User",
+      "This was very helpful, I want to leave some feedback."
+    ),
+  ];
+
+  const feedbackResponse = await agent.respond({
+    history: feedbackHistory,
+    session,
+  });
+  console.log("AI:", feedbackResponse.message);
+  console.log("Route:", feedbackResponse.session?.currentRoute?.title);
+
+  if (feedbackResponse.isRouteComplete) {
+    console.log("\n✅ Feedback collection complete!");
+    await processFeedback(agent.getExtractedData(feedbackResponse.session?.id));
+  } else {
+    console.log("\n⏳ Feedback collection in progress...");
+  }
+}
+
+/**
+ * Mock function to process collected feedback.
+ * @param data The feedback data collected from the user.
+ */
+async function processFeedback(data: Partial<FeedbackData>) {
+  console.log("\n" + "=".repeat(60));
+  console.log("Processing user feedback...");
+  console.log("=".repeat(60));
+  console.log("Rating:", data.rating);
+  console.log("Comments:", data.comments);
+  console.log("Permission to contact:", data.contactPermission);
+
+  // Here you would typically save this to a database or send it to a support system.
+  await new Promise((resolve) => setTimeout(resolve, 500)); // Simulate async operation
+  console.log("Feedback logged successfully!");
+  console.log("=".repeat(60));
 }
 
 // ==============================================================================

package/examples/custom-database-persistence.ts

@@ -19,6 +19,7 @@ import {
   SessionState,
   MessageEventData,
   Event,
+  END_STATE,
 } from "../src/index";
 
 /**
@@ -32,6 +33,7 @@ interface CustomDatabaseSession {
   currentState?: string;
   collectedData?: {
     extracted?: Record<string, unknown>;
+    extractedByRoute?: Record<string, Partial<unknown>>;
     routeHistory?: unknown[];
     currentRouteTitle?: string;
     currentStateDescription?: string;
@@ -193,7 +195,13 @@ async function example() {
       id: "confirm_details",
       chatState: "Confirm all details",
       requiredData: ["fullName", "email", "companyName"],
-    });
+    })
+    .transitionTo({
+      id: "complete_onboarding",
+      chatState:
+        "Thank you! Your account is set up. You will receive a confirmation email shortly.",
+    })
+    .transitionTo({ state: END_STATE });
 
   /**
    * Create or load session from your custom database
@@ -234,6 +242,11 @@ async function example() {
         : undefined,
       extracted:
         (dbSession.collectedData?.extracted as Partial<OnboardingData>) || {},
+      extractedByRoute:
+        (dbSession.collectedData?.extractedByRoute as Record<
+          string,
+          Partial<OnboardingData>
+        >) || {},
       routeHistory:
         (dbSession.collectedData
           ?.routeHistory as SessionState<OnboardingData>["routeHistory"]) || [],
@@ -373,6 +386,14 @@ async function example() {
 
   console.log("💾 Session saved to database");
 
+  // Check for route completion
+  if (response2.isRouteComplete) {
+    console.log("\n✅ Onboarding Complete!");
+    // In a real app, you would now trigger the next steps,
+    // like sending a welcome email, creating an account, etc.
+    await processOnboarding(response2.session?.extracted);
+  }
+
   /**
    * Demonstrate session recovery
    */
@@ -404,6 +425,11 @@ async function example() {
     extracted:
       (reloadedDbSession.collectedData?.extracted as Partial<OnboardingData>) ||
       {},
+    extractedByRoute:
+      (reloadedDbSession.collectedData?.extractedByRoute as Record<
+        string,
+        Partial<OnboardingData>
+      >) || {},
     routeHistory:
       (reloadedDbSession.collectedData
         ?.routeHistory as SessionState<OnboardingData>["routeHistory"]) || [],
@@ -429,6 +455,23 @@ async function example() {
   console.log("\n✅ Example complete!");
 }
 
+/**
+ * Mock function to simulate processing the completed onboarding data.
+ * @param data - The collected onboarding data.
+ */
+async function processOnboarding(data: Partial<OnboardingData> | undefined) {
+  console.log("\n🚀 Processing onboarding data...");
+  // Simulate creating a user account
+  console.log(
+    `   - Creating account for ${data?.fullName} at ${data?.companyName}`
+  );
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  // Simulate sending a welcome email
+  console.log(`   - Sending welcome email to ${data?.email}`);
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log("✨ Onboarding processed successfully!");
+}
+
 /**
  * Advanced Example: With validation hooks
  */

package/examples/declarative-agent.ts

@@ -21,6 +21,7 @@ import {
   type Guideline,
   type Capability,
   type RouteOptions,
+  END_STATE,
 } from "../src/index";
 
 // Context type
@@ -45,24 +46,22 @@ interface LabData {
 }
 
 // Define tools with custom IDs (optional - IDs are deterministic by default)
-const getInsuranceProviders = defineTool<HealthcareContext, [], string[]>(
-  "get_insurance_providers",
-  async () => {
+const getInsuranceProviders = defineTool<HealthcareContext, [], string[]>({
+  name: "get_insurance_providers",
+  handler: async () => {
     return { data: ["MegaCare Insurance", "HealthFirst", "WellnessPlus"] };
   },
-  {
-    id: "healthcare_insurance_providers", // Custom ID for persistence
-    description: "Retrieves list of accepted insurance providers",
-  }
-);
+  id: "healthcare_insurance_providers", // Custom ID for persistence
+  description: "Retrieves list of accepted insurance providers",
+});
 
 const getAvailableSlots = defineTool<
   HealthcareContext,
   [],
   { date: string; time: string }[]
->(
-  "get_available_slots",
-  async () => {
+>({
+  name: "get_available_slots",
+  handler: async () => {
     return {
       data: [
         { date: "2025-10-20", time: "10:00 AM" },
@@ -71,19 +70,17 @@ const getAvailableSlots = defineTool<
       ],
     };
   },
-  {
-    id: "healthcare_available_slots", // Custom ID
-    description: "Gets available appointment slots",
-  }
-);
+  id: "healthcare_available_slots", // Custom ID
+  description: "Gets available appointment slots",
+});
 
 const getLabResults = defineTool<
   HealthcareContext,
   [],
   { report: string; status: string }
->(
-  "get_lab_results",
-  async ({ context, extracted }) => {
+>({
+  name: "get_lab_results",
+  handler: async ({ context, extracted }) => {
     // Tools can now access extracted data
     const labData = extracted as Partial<LabData>;
     if (labData?.testType) {
@@ -102,19 +99,13 @@ const getLabResults = defineTool<
       },
     };
   },
-  {
-    id: "healthcare_lab_results", // Custom ID
-    description: "Retrieves patient lab results",
-  }
-);
+  id: "healthcare_lab_results", // Custom ID
+  description: "Retrieves patient lab results",
+});
 
-const scheduleAppointment = defineTool<
-  HealthcareContext,
-  [],
-  { confirmation: string }
->(
-  "schedule_appointment",
-  async ({ context, extracted }) => {
+const scheduleAppointment = defineTool<HealthcareContext>({
+  name: "schedule_appointment",
+  handler: async ({ context, extracted }) => {
     // Tools can access extracted appointment data
     const appointment = extracted as Partial<AppointmentData>;
     if (!appointment?.preferredDate || !appointment?.preferredTime) {
@@ -127,11 +118,9 @@ const scheduleAppointment = defineTool<
       },
     };
   },
-  {
-    id: "healthcare_schedule_appointment",
-    description: "Schedules patient appointments",
-  }
-);
+  id: "healthcare_schedule_appointment",
+  description: "Schedules patient appointments",
+});
 
 // Declarative configuration
 const terms: Term[] = [
@@ -226,6 +215,36 @@ const routes: RouteOptions[] = [
         enabled: true,
       },
     ],
+    // NEW: Use sequential steps for a linear booking flow
+    steps: [
+      {
+        id: "ask_appointment_type",
+        chatState:
+          "What type of appointment do you need? (checkup, consultation, or followup)",
+        gather: ["appointmentType"],
+      },
+      {
+        id: "ask_date_time",
+        chatState: "When would you like to come in?",
+        gather: ["preferredDate", "preferredTime"],
+        requiredData: ["appointmentType"],
+      },
+      {
+        id: "ask_symptoms",
+        chatState: "Are you experiencing any symptoms?",
+        gather: ["symptoms"],
+      },
+      {
+        id: "confirm_appointment",
+        toolState: scheduleAppointment,
+        requiredData: ["preferredDate", "preferredTime"],
+      },
+      {
+        id: "final_confirmation",
+        chatState:
+          "Your appointment is confirmed. You will receive a notification shortly.",
+      },
+    ],
   },
   {
     id: "route_check_lab_results", // Custom ID
@@ -266,7 +285,7 @@ const routes: RouteOptions[] = [
     conditions: ["Patient asks general healthcare questions"],
     // No extractionSchema - stateless Q&A
   },
-];
+] as RouteOptions[];
 
 // Create the fully configured agent
 const agent = new Agent<HealthcareContext>({
@@ -342,6 +361,14 @@ async function main() {
 
     // Session tracks the appointment booking progress
     console.log("Current state:", response2.session?.currentState?.id);
+
+    // Check for route completion
+    if (response2.isRouteComplete && response2.session) {
+      console.log("\n✅ Appointment scheduling complete!");
+      await sendAppointmentConfirmation(
+        agent.getExtractedData(response2.session.id) as AppointmentData
+      );
+    }
   }
 
   // Note: Custom IDs ensure consistency across server restarts
@@ -352,6 +379,22 @@ async function main() {
   // - State recovery for resuming conversations
 }
 
+/**
+ * Mock function to send an appointment confirmation.
+ * @param data - The appointment data.
+ */
+async function sendAppointmentConfirmation(data: AppointmentData) {
+  console.log("\n" + "=".repeat(60));
+  console.log("🚀 Sending Appointment Confirmation...");
+  console.log("=".repeat(60));
+  console.log("Appointment Details:", JSON.stringify(data, null, 2));
+  console.log(
+    `   - Sending confirmation to patient for ${data.preferredDate} at ${data.preferredTime}.`
+  );
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log("✨ Confirmation sent!");
+}
+
 // Uncomment to run:
 // main().catch(console.error);
 

package/examples/domain-scoping.ts

@@ -17,6 +17,8 @@ import {
   createMessageEvent,
   EventSource,
   createSession,
+  END_STATE,
+  defineTool,
 } from "../src/index";
 import { OpenRouterProvider } from "../src/providers";
 
@@ -102,11 +104,55 @@ agent.createRoute({
   domains: ["scraping"], // ✅ Only scraping tools available
 });
 
-agent.createRoute({
+const scheduleEventTool = defineTool({
+  id: "scheduleEvent",
+  name: "scheduleEvent",
+  description: "Schedules an event in the calendar",
+  handler: async ({ extracted }) => {
+    const { title, date, description } = extracted as {
+      title: string;
+      date: string;
+      description: string;
+    };
+    console.log(`[Calendar] Scheduling event: ${title} on ${date}`);
+    return { data: { eventId: "evt_123", success: true } };
+  },
+});
+
+agent.createRoute<{ title: string; date: string; description: string }>({
   title: "Schedule Meeting",
   description: "Book and manage appointments",
   conditions: ["User wants to schedule, view, or cancel events"],
   domains: ["calendar"], // ✅ Only calendar tools available
+  extractionSchema: {
+    type: "object",
+    properties: {
+      title: { type: "string" },
+      date: { type: "string" },
+      description: { type: "string" },
+    },
+    required: ["title", "date"],
+  },
+  steps: [
+    {
+      chatState: "What is the title of the meeting?",
+      gather: ["title"],
+    },
+    {
+      chatState: "When would you like to schedule it?",
+      gather: ["date"],
+    },
+    {
+      chatState: "Any description for the meeting?",
+      gather: ["description"],
+    },
+    {
+      toolState: scheduleEventTool,
+    },
+    {
+      chatState: "The meeting has been scheduled.",
+    },
+  ],
 });
 
 agent.createRoute({
@@ -137,11 +183,11 @@ async function demonstrateScoping() {
   // Example 1: Data Collection route - only scraping tools available
   console.log("1️⃣  Example: User wants to scrape data");
   const history1 = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Alice",
-      "Can you scrape the homepage of example.com?"
-    ),
+    createMessageEvent({
+      source: EventSource.CUSTOMER,
+      participantName: "Alice",
+      message: "Can you scrape the homepage of example.com?",
+    }),
   ];
 
   // Initialize session state for multi-turn conversation
@@ -158,11 +204,11 @@ async function demonstrateScoping() {
   // Example 2: Schedule Meeting route - only calendar tools available
   console.log("2️⃣  Example: User wants to schedule a meeting");
   const history2 = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Bob",
-      "Schedule a meeting for tomorrow at 2pm"
-    ),
+    createMessageEvent({
+      source: EventSource.CUSTOMER,
+      participantName: "Bob",
+      message: "Schedule a meeting for tomorrow at 2pm",
+    }),
   ];
 
   const response2 = await agent.respond({ history: history2, session });
@@ -170,17 +216,27 @@ async function demonstrateScoping() {
   console.log(`Available tools in this route: calendar only`);
   console.log(`Response: ${response2.message}\n`);
 
+  if (response2.isRouteComplete) {
+    console.log("\n✅ Meeting scheduling complete!");
+    await sendMeetingInvite(
+      agent.getExtractedData(response2.session?.id) as {
+        title: string;
+        date: string;
+      }
+    );
+  }
+
   // Update session again
   session = response2.session!;
 
   // Example 3: Customer Support route - NO tools available
   console.log("3️⃣  Example: User has a general question");
   const history3 = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Charlie",
-      "What are your business hours?"
-    ),
+    createMessageEvent({
+      source: EventSource.CUSTOMER,
+      participantName: "Charlie",
+      message: "What are your business hours?",
+    }),
   ];
 
   const response3 = await agent.respond({ history: history3, session });
@@ -194,11 +250,11 @@ async function demonstrateScoping() {
   // Example 4: Admin Support route - ALL tools available (for demo purposes)
   console.log("4️⃣  Example: Admin needs full access");
   const history4 = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Admin",
-      "I need to generate a report and process a refund"
-    ),
+    createMessageEvent({
+      source: EventSource.CUSTOMER,
+      participantName: "Admin",
+      message: "I need to generate a report and process a refund",
+    }),
   ];
 
   const response4 = await agent.respond({ history: history4, session });
@@ -288,6 +344,20 @@ console.log(
   )}`
 );
 
+/**
+ * Mock function to send a meeting invite.
+ * @param data - The meeting data.
+ */
+async function sendMeetingInvite(data: { title: string; date: string }) {
+  console.log("\n" + "=".repeat(60));
+  console.log("🚀 Sending Meeting Invite...");
+  console.log("=".repeat(60));
+  console.log("Meeting Details:", JSON.stringify(data, null, 2));
+  console.log(`   - Sending invite for "${data.title}" on ${data.date}.`);
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log("✨ Invite sent!");
+}
+
 // Run demonstration
 if (import.meta.url === `file://${process.argv[1]}`) {
   demonstrateScoping().catch(console.error);