@falai/agent 0.9.0-alpha-1 → 0.9.0

package/examples/ai-providers/openai-integration.ts

@@ -26,7 +26,7 @@ interface WeatherData {
 }
 
 // Define a tool that can access collected data
-const getWeather: Tool<CustomerContext, unknown[], unknown, WeatherData> = {
+const getWeather: Tool<CustomerContext, WeatherData, unknown[], unknown> = {
   id: "get_weather",
   description: "Get current weather for a location",
   parameters: {
@@ -38,8 +38,7 @@ const getWeather: Tool<CustomerContext, unknown[], unknown, WeatherData> = {
   },
   handler: ({ data }, location) => {
     // Use data location if available, otherwise use args
-    const weatherData = data as Partial<WeatherData>;
-    const finalLocation = weatherData?.location || location;
+    const finalLocation = data?.location || location;
 
     // Simulate API call
     return {
@@ -71,7 +70,7 @@ async function main() {
   });
 
   // Create agent with OpenAI
-  const agent = new Agent<CustomerContext>({
+  const agent = new Agent<CustomerContext, WeatherData>({
     name: "Assistant",
     description:
       "A helpful AI assistant that can check weather and answer questions",
@@ -84,6 +83,25 @@ async function main() {
       preferences: ["concise answers", "weather updates"],
     },
     provider: openaiProvider,
+
+    schema: {
+      type: "object",
+      properties: {
+        location: {
+          type: "string",
+          description: "City or location for weather check",
+        },
+        temperature: {
+          type: "number",
+          description: "Temperature in Fahrenheit",
+        },
+        condition: {
+          type: "string",
+          description: "Weather condition (sunny, cloudy, rainy, etc.)",
+        },
+      },
+      required: ["location"],
+    },
   });
 
   // Add domain knowledge
@@ -106,28 +124,10 @@ async function main() {
     });
 
   // Create weather route with data extraction schema
-  const weatherRoute = agent.createRoute<WeatherData>({
+  const weatherRoute = agent.createRoute({
     title: "Check Weather",
     description: "Help user check weather for a location",
     conditions: ["User wants to know the weather"],
-    schema: {
-      type: "object",
-      properties: {
-        location: {
-          type: "string",
-          description: "City or location for weather check",
-        },
-        temperature: {
-          type: "number",
-          description: "Temperature in Fahrenheit",
-        },
-        condition: {
-          type: "string",
-          description: "Weather condition (sunny, cloudy, rainy, etc.)",
-        },
-      },
-      required: ["location"],
-    },
   });
 
   // Step 1: Collect location
@@ -180,14 +180,14 @@ async function main() {
     console.log(`   Customer: What's the weather like in San Francisco?`);
     console.log(`   Agent: ${response.message}`);
     console.log(`   Route: ${response.session?.currentRoute?.title}`);
-    console.log(`   Data:`, agent.session.getData<WeatherData>());
+    console.log(`   Data:`, agent.session.getData());
 
     await agent.session.addMessage("assistant", response.message);
 
     // Check for route completion
     if (response.isRouteComplete) {
       console.log("\n✅ Weather route complete!");
-      await logWeatherRequest(agent.session.getData<WeatherData>());
+      await logWeatherRequest(agent.session.getData());
     }
 
     console.log("\n✨ Session step benefits:");

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));