@falai/agent 0.9.0-alpha-1 → 0.9.0-alpha-2

package/examples/conversation-flows/completion-transitions.ts

@@ -15,21 +15,35 @@ import {
   type SessionState,
 } from "../../src/index";
 
-// Type definitions for our booking data
-interface BookingData {
+// Type definitions for our unified data collection
+interface UnifiedBookingData {
+  // Booking fields
   hotelName: string;
   date: string;
   guests: number;
-}
-
-interface FeedbackData {
+  // Feedback fields
   rating: number;
   comments?: string;
 }
 
 async function main() {
-  // Create agent
-  const agent = new Agent({
+  // Define unified schema for both booking and feedback data
+  const unifiedSchema = {
+    type: "object",
+    properties: {
+      // Booking fields
+      hotelName: { type: "string" },
+      date: { type: "string" },
+      guests: { type: "number" },
+      // Feedback fields
+      rating: { type: "number", minimum: 1, maximum: 5 },
+      comments: { type: "string" },
+    },
+    required: ["hotelName", "date", "guests"], // Only booking fields are required initially
+  };
+
+  // Create agent with unified schema
+  const agent = new Agent<unknown, UnifiedBookingData>({
     name: "HotelBot",
     description: "A hotel booking assistant with feedback collection",
     provider: new GeminiProvider({
@@ -37,22 +51,16 @@ async function main() {
       model: "models/gemini-2.5-flash",
     }),
     debug: true,
+    schema: unifiedSchema,
   });
 
   // Route 1: Hotel Booking with automatic transition to feedback
-  agent.createRoute<BookingData>({
+  agent.createRoute({
     title: "Book Hotel",
     description: "Collects hotel booking information",
     conditions: ["User wants to book a hotel"],
-    schema: {
-      type: "object",
-      properties: {
-        hotelName: { type: "string" },
-        date: { type: "string" },
-        guests: { type: "number" },
-      },
-      required: ["hotelName", "date", "guests"],
-    },
+    // NEW: Required fields for route completion
+    requiredFields: ["hotelName", "date", "guests"],
     // Sequential steps for booking flow
     steps: [
       {
@@ -60,7 +68,7 @@ async function main() {
         description: "Ask for hotel preference",
         prompt: "Which hotel would you like to book?",
         collect: ["hotelName"],
-        skipIf: (data: Partial<BookingData>) => !!data.hotelName,
+        skipIf: (data: Partial<UnifiedBookingData>) => !!data.hotelName,
       },
       {
         id: "ask_date",
@@ -68,7 +76,7 @@ async function main() {
         prompt: "What date would you like to book for?",
         collect: ["date"],
         requires: ["hotelName"],
-        skipIf: (data: Partial<BookingData>) => !!data.date,
+        skipIf: (data: Partial<UnifiedBookingData>) => !!data.date,
       },
       {
         id: "ask_guests",
@@ -76,7 +84,7 @@ async function main() {
         prompt: "How many guests will be staying?",
         collect: ["guests"],
         requires: ["hotelName", "date"],
-        skipIf: (data: Partial<BookingData>) => data.guests !== undefined,
+        skipIf: (data: Partial<UnifiedBookingData>) => data.guests !== undefined,
       },
       {
         id: "confirm_booking",
@@ -91,18 +99,14 @@ async function main() {
   });
 
   // Route 2: Feedback Collection
-  agent.createRoute<FeedbackData>({
+  agent.createRoute({
     title: "Collect Feedback",
     description: "Collects user feedback after booking",
     conditions: ["User wants to provide feedback"],
-    schema: {
-      type: "object",
-      properties: {
-        rating: { type: "number", minimum: 1, maximum: 5 },
-        comments: { type: "string" },
-      },
-      required: ["rating"],
-    },
+    // NEW: Required fields for route completion
+    requiredFields: ["rating"],
+    // NEW: Optional fields that enhance the experience
+    optionalFields: ["comments"],
     // Sequential steps for feedback collection
     steps: [
       {
@@ -110,7 +114,7 @@ async function main() {
         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,
+        skipIf: (data: Partial<UnifiedBookingData>) => data.rating !== undefined,
       },
       {
         id: "ask_comments",
@@ -153,7 +157,7 @@ async function main() {
     "Pending transition?",
     response1.session?.pendingTransition?.targetRouteId
   );
-  console.log("Data booking data:", response1.session?.data);
+  console.log("Collected data:", response1.session?.data);
 
   session = response1.session;
   history = [
@@ -203,7 +207,7 @@ async function main() {
   const response3 = await agent.respond({ history, session });
   console.log("\nBot:", response3.message);
   console.log("Current route:", response3.session?.currentRoute?.title);
-  console.log("Data feedback data:", response3.session?.data);
+  console.log("Collected data:", response3.session?.data);
   console.log("Route complete?", response3.isRouteComplete);
 
   console.log("\n=== Manual Transition Example ===\n");

package/examples/core-concepts/basic-agent.ts

@@ -17,7 +17,6 @@ import {
   type Guideline,
   type Tool,
   type RouteOptions,
-  History,
 } from "../../src/index";
 
 // Context type
@@ -42,7 +41,7 @@ interface LabData {
 }
 
 // Define tools using the new Tool interface
-const getInsuranceProviders: Tool<HealthcareContext, [], string[]> = {
+const getInsuranceProviders: Tool<HealthcareContext, HealthcareData, [], string[]> = {
   id: "healthcare_insurance_providers",
   description: "Retrieves list of accepted insurance providers",
   parameters: {
@@ -58,6 +57,7 @@ const getInsuranceProviders: Tool<HealthcareContext, [], string[]> = {
 
 const getAvailableSlots: Tool<
   HealthcareContext,
+  HealthcareData,
   [],
   { date: string; time: string }[]
 > = {
@@ -80,6 +80,7 @@ const getAvailableSlots: Tool<
 
 const getLabResults: Tool<
   HealthcareContext,
+  HealthcareData,
   [],
   { report: string; status: string }
 > = {
@@ -89,19 +90,12 @@ const getLabResults: Tool<
     type: "object",
     properties: {},
   },
-  handler: ({
-    context,
-    data,
-  }: {
-    context: HealthcareContext;
-    data?: Partial<LabData>;
-  }) => {
+  handler: ({ context, data }) => {
     // Tools can access collected data and context
-    const labData = data as Partial<LabData>;
-    if (labData?.testType) {
+    if (data?.testType) {
       return {
         data: {
-          report: `${labData.testType} results for ${context.patientName}`,
+          report: `${data.testType} results for ${context.patientName}`,
           status: "All values within normal range",
         },
       };
@@ -118,6 +112,7 @@ const getLabResults: Tool<
 
 const scheduleAppointment: Tool<
   HealthcareContext,
+  HealthcareData,
   [],
   { confirmation: string }
 > = {
@@ -127,21 +122,15 @@ const scheduleAppointment: Tool<
     type: "object",
     properties: {},
   },
-  handler: ({
-    data,
-  }: {
-    context: HealthcareContext;
-    data?: Partial<AppointmentData>;
-  }) => {
+  handler: ({ data }) => {
     // Tools access collected appointment data
-    const appointment = data as Partial<AppointmentData>;
-    if (!appointment?.preferredDate || !appointment?.preferredTime) {
+    if (!data?.preferredDate || !data?.preferredTime) {
       return { data: { confirmation: "Please provide appointment details" } };
     }
 
     return {
       data: {
-        confirmation: `Appointment scheduled for ${appointment.preferredDate} at ${appointment.preferredTime}`,
+        confirmation: `Appointment scheduled for ${data.preferredDate} at ${data.preferredTime}`,
       },
     };
   },
@@ -186,40 +175,16 @@ const guidelines: Guideline<HealthcareContext>[] = [
   },
 ];
 
-const routes: RouteOptions<HealthcareContext>[] = [
+const routes: RouteOptions<HealthcareContext, HealthcareData>[] = [
   {
     id: "route_schedule_appointment",
     title: "Schedule Appointment",
     description: "Helps the patient schedule an appointment",
     conditions: ["The patient wants to schedule an appointment"],
-    schema: {
-      type: "object",
-      properties: {
-        appointmentType: {
-          type: "string",
-          enum: ["checkup", "consultation", "followup"],
-          description: "Type of appointment needed",
-        },
-        preferredDate: {
-          type: "string",
-          description: "Preferred appointment date",
-        },
-        preferredTime: {
-          type: "string",
-          description: "Preferred appointment time",
-        },
-        symptoms: {
-          type: "string",
-          description: "Description of symptoms (if applicable)",
-        },
-        urgency: {
-          type: "string",
-          enum: ["low", "medium", "high"],
-          default: "medium",
-        },
-      },
-      required: ["appointmentType", "preferredDate", "preferredTime"],
-    },
+    // NEW: Required fields for route completion (instead of schema)
+    requiredFields: ["appointmentType", "preferredDate", "preferredTime"],
+    // NEW: Optional fields that enhance the experience
+    optionalFields: ["symptoms", "urgency"],
     guidelines: [
       {
         condition: "The patient says their visit is urgent",
@@ -249,7 +214,7 @@ const routes: RouteOptions<HealthcareContext>[] = [
         description: "Ask about symptoms",
         prompt: "Are you experiencing any symptoms?",
         collect: ["symptoms"],
-        skipIf: (data: Partial<AppointmentData>) =>
+        skipIf: (data: Partial<HealthcareData>) =>
           data.appointmentType === "checkup", // Skip for checkups
       },
       {
@@ -283,25 +248,10 @@ const routes: RouteOptions<HealthcareContext>[] = [
     title: "Check Lab Results",
     description: "Retrieves and explains patient lab results",
     conditions: ["The patient wants to see their lab results"],
-    schema: {
-      type: "object",
-      properties: {
-        testType: {
-          type: "string",
-          description: "Type of lab test",
-        },
-        testDate: {
-          type: "string",
-          description: "Date of the lab test",
-        },
-        resultsNeeded: {
-          type: "boolean",
-          default: true,
-          description: "Whether detailed results are needed",
-        },
-      },
-      required: ["testType"],
-    },
+    // NEW: Required fields for route completion
+    requiredFields: ["testType"],
+    // NEW: Optional fields
+    optionalFields: ["testDate", "resultsNeeded"],
     guidelines: [
       {
         condition: "The patient presses for more conclusions about results",
@@ -316,12 +266,58 @@ const routes: RouteOptions<HealthcareContext>[] = [
     title: "General Healthcare Questions",
     description: "Answer general healthcare questions",
     conditions: ["Patient asks general healthcare questions"],
-    // No schema - conversational Q&A
+    // No required fields - conversational Q&A
   },
 ];
 
-// Create the fully configured agent
-const agent = new Agent<HealthcareContext>({
+// Define a unified data schema for all healthcare interactions
+interface HealthcareData extends AppointmentData, LabData {}
+
+const healthcareSchema = {
+  type: "object",
+  properties: {
+    // Appointment fields
+    appointmentType: {
+      type: "string",
+      enum: ["checkup", "consultation", "followup"],
+      description: "Type of appointment needed",
+    },
+    preferredDate: {
+      type: "string",
+      description: "Preferred appointment date",
+    },
+    preferredTime: {
+      type: "string",
+      description: "Preferred appointment time",
+    },
+    symptoms: {
+      type: "string",
+      description: "Description of symptoms (if applicable)",
+    },
+    urgency: {
+      type: "string",
+      enum: ["low", "medium", "high"],
+      default: "medium",
+    },
+    // Lab fields
+    testType: {
+      type: "string",
+      description: "Type of lab test",
+    },
+    testDate: {
+      type: "string",
+      description: "Date of the lab test",
+    },
+    resultsNeeded: {
+      type: "boolean",
+      default: true,
+      description: "Whether detailed results are needed",
+    },
+  },
+};
+
+// Create the fully configured agent with agent-level schema
+const agent = new Agent<HealthcareContext, HealthcareData>({
   name: "HealthBot",
   description: "A compassionate healthcare assistant",
   goal: "Provide helpful information and assist with appointments",
@@ -333,6 +329,8 @@ const agent = new Agent<HealthcareContext>({
     apiKey: process.env.GEMINI_API_KEY || "demo-key",
     model: "models/gemini-2.5-flash",
   }),
+  // NEW: Agent-level schema
+  schema: healthcareSchema,
   // Declarative initialization
   terms,
   guidelines,
@@ -381,7 +379,7 @@ async function main() {
   });
   
   console.log("🤖 Agent:", response2.message);
-  console.log("📊 Collected data:", agent.session.getData<AppointmentData | LabData>());
+  console.log("📊 Collected data:", agent.session.getData());
   console.log("📍 Current step:", response2.session?.currentStep?.id);
 
   await agent.session.addMessage("assistant", response2.message);
@@ -396,7 +394,7 @@ async function main() {
   });
   
   console.log("🤖 Agent:", response3.message);
-  console.log("📊 Updated data:", agent.session.getData<AppointmentData | LabData>());
+  console.log("📊 Updated data:", agent.session.getData());
   console.log("📍 Current step:", response3.session?.currentStep?.id);
   
   await agent.session.addMessage("assistant", response3.message);
@@ -405,7 +403,7 @@ async function main() {
   if (response3.isRouteComplete && response3.session) {
     console.log("\n✅ Appointment scheduling complete!");
     await sendAppointmentConfirmation(
-      agent.getData<AppointmentData>(response3.session.id) as AppointmentData
+      agent.getCollectedData() as HealthcareData
     );
   }
 
@@ -424,9 +422,9 @@ async function main() {
 
 /**
  * Mock function to send an appointment confirmation.
- * @param data - The appointment data.
+ * @param data - The healthcare data.
  */
-async function sendAppointmentConfirmation(data: AppointmentData) {
+async function sendAppointmentConfirmation(data: HealthcareData) {
   console.log("\n" + "=".repeat(60));
   console.log("🚀 Sending Appointment Confirmation...");
   console.log("=".repeat(60));

package/examples/core-concepts/schema-driven-extraction.ts

@@ -24,7 +24,7 @@ interface UserProfileData {
 }
 
 // Define a tool that uses the collected data
-const saveUserProfile: Tool<unknown, [], string, UserProfileData> = {
+const saveUserProfile: Tool<unknown, UserProfileData, [], string> = {
   id: "save_user_profile",
   description: "Save the collected user profile information",
   parameters: {
@@ -37,24 +37,12 @@ const saveUserProfile: Tool<unknown, [], string, UserProfileData> = {
     // Simulate saving to database
     console.log("Profile data:", data);
 
-    const userData = data as Partial<UserProfileData>;
     return {
-      data: `Profile saved successfully! Welcome ${userData?.name}!`,
+      data: `Profile saved successfully! Welcome ${data?.name}!`,
     };
   },
 };
 
-// Create the agent
-const agent = new Agent({
-  name: "ProfileBot",
-  description:
-    "A bot that collects user profile information using schema-driven extraction",
-  provider: new GeminiProvider({
-    apiKey: process.env.GEMINI_API_KEY!,
-    model: "models/gemini-2.5-flash",
-  }),
-});
-
 // Define the schema for data validation and extraction
 const userProfileSchema = {
   type: "object",
@@ -98,11 +86,27 @@ const userProfileSchema = {
   required: ["name", "email"],
 };
 
+// Create the agent with agent-level schema
+const agent = new Agent<unknown, UserProfileData>({
+  name: "ProfileBot",
+  description:
+    "A bot that collects user profile information using schema-driven extraction",
+  provider: new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY!,
+    model: "models/gemini-2.5-flash",
+  }),
+  // NEW: Agent-level schema definition
+  schema: userProfileSchema,
+});
+
 // Create a route that collects profile information step by step
-agent.createRoute<UserProfileData>({
+agent.createRoute({
   title: "User Profile Collection",
   description: "Collect comprehensive user profile information",
-  schema: userProfileSchema,
+  // NEW: Required fields for route completion (instead of schema)
+  requiredFields: ["name", "email"],
+  // NEW: Optional fields that enhance the experience
+  optionalFields: ["age", "interests", "preferredContact", "newsletterOptIn"],
   // Use sequential steps for a linear flow with smart skipIf conditions
   steps: [
     {