@falai/agent 0.9.0 → 1.0.0

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

@@ -4,19 +4,25 @@
  * This example demonstrates how to configure an entire agent
  * using declarative syntax in the constructor, including:
  * - Terms (domain glossary)
- * - Guidelines (behavior rules)
+ * - Guidelines (behavior rules) with flexible ConditionTemplate patterns
  * - Tools (capabilities)
  * - Routes with data extraction schemas and sequential steps
  * - Session management for multi-turn conversations
+ * - NEW: Flexible routing conditions with ConditionTemplate patterns:
+ *   - String-only conditions: "user wants to book" (AI context only)
+ *   - Function-only conditions: (ctx) => ctx.data?.hasPayment (programmatic only)
+ *   - Mixed arrays: ["user wants to book", (ctx) => !ctx.data?.complete] (hybrid)
+ *   - Route skipIf: Dynamic route exclusion based on conditions
+ *   - Step skipIf: Enhanced conditional step skipping
  */
 
 import {
   Agent,
   GeminiProvider,
+  Tool,
+  ValidationError,
   type Term,
   type Guideline,
-  type Tool,
-  type RouteOptions,
 } from "../../src/index";
 
 // Context type
@@ -40,98 +46,71 @@ interface LabData {
   resultsNeeded: boolean;
 }
 
-// Define tools using the new Tool interface
-const getInsuranceProviders: Tool<HealthcareContext, HealthcareData, [], string[]> = {
+// Define tools using unified Tool interface
+const getInsuranceProvidersTool: Tool<HealthcareContext, HealthcareData> = {
   id: "healthcare_insurance_providers",
   description: "Retrieves list of accepted insurance providers",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: () => {
+  handler: async (context, args) => {
     return {
-      data: ["MegaCare Insurance", "HealthFirst", "WellnessPlus"],
+      data: "Available insurance providers: MegaCare Insurance, HealthFirst, WellnessPlus",
     };
   },
 };
 
-const getAvailableSlots: Tool<
-  HealthcareContext,
-  HealthcareData,
-  [],
-  { date: string; time: string }[]
-> = {
+const getAvailableSlotsTool: Tool<HealthcareContext, HealthcareData> = {
   id: "healthcare_available_slots",
   description: "Gets available appointment slots",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: () => {
+  handler: async (context, args) => {
     return {
-      data: [
-        { date: "2025-10-20", time: "10:00 AM" },
-        { date: "2025-10-20", time: "2:00 PM" },
-        { date: "2025-10-21", time: "1:00 PM" },
-      ],
+      data: "Available slots: Oct 20 at 10:00 AM, Oct 20 at 2:00 PM, Oct 21 at 1:00 PM",
     };
   },
 };
 
-const getLabResults: Tool<
-  HealthcareContext,
-  HealthcareData,
-  [],
-  { report: string; status: string }
-> = {
+const getLabResultsTool: Tool<HealthcareContext, HealthcareData> = {
   id: "healthcare_lab_results",
   description: "Retrieves patient lab results",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: ({ context, data }) => {
+  handler: async (toolContext, args) => {
     // Tools can access collected data and context
-    if (data?.testType) {
+    if (toolContext.data?.testType) {
       return {
-        data: {
-          report: `${data.testType} results for ${context.patientName}`,
-          status: "All values within normal range",
-        },
+        data: `${toolContext.data.testType} results for ${toolContext.context.patientName}: All values within normal range`,
       };
     }
 
     return {
-      data: {
-        report: `Lab results for ${context.patientName}`,
-        status: "All values within normal range",
-      },
+      data: `Lab results for ${toolContext.context.patientName}: All values within normal range`,
     };
   },
 };
 
-const scheduleAppointment: Tool<
-  HealthcareContext,
-  HealthcareData,
-  [],
-  { confirmation: string }
-> = {
+const scheduleAppointmentTool: Tool<HealthcareContext, HealthcareData> = {
   id: "healthcare_schedule_appointment",
   description: "Schedules patient appointments",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: ({ data }) => {
+  handler: async (context, args) => {
     // Tools access collected appointment data
-    if (!data?.preferredDate || !data?.preferredTime) {
-      return { data: { confirmation: "Please provide appointment details" } };
+    if (!context.data?.preferredDate || !context.data?.preferredTime) {
+      return { data: "Please provide appointment details" };
     }
 
     return {
-      data: {
-        confirmation: `Appointment scheduled for ${data.preferredDate} at ${data.preferredTime}`,
-      },
+      data: `Appointment scheduled for ${context.data.preferredDate} at ${context.data.preferredTime}`,
     };
   },
 };
@@ -156,31 +135,53 @@ const terms: Term<HealthcareContext>[] = [
 
 const guidelines: Guideline<HealthcareContext>[] = [
   {
+    // String-only condition for AI context
     condition: "The patient asks about insurance",
     action:
       "List the insurance providers we accept and tell them to call the office for more details",
     tags: ["insurance", "billing"],
   },
   {
-    condition: "The patient asks to talk to a human agent",
+    // Mixed condition: AI context + programmatic check
+    condition: [
+      "The patient asks to talk to a human agent",
+      (ctx) => ctx.context?.patientName !== undefined // Only if we have patient info
+    ],
     action: ({ context }: { context?: HealthcareContext }) =>
       `Of course. You can reach our office at +1-234-567-8900 during office hours (Monday to Friday, 9 AM to 5 PM). I've noted that you'd like to speak with someone, and I can have a representative call you back if you'd like, ${context?.patientName}.`,
     tags: ["escalation"],
   },
   {
-    condition: "The patient inquires about something unrelated to healthcare",
+    // Function-only condition for programmatic logic
+    condition: (ctx) => {
+      const event = ctx.history?.[ctx.history.length - 1]
+      if(event && "content" in event){
+        const message = (event.content as string).toLocaleLowerCase() || '';
+        return !message.includes('health') && !message.includes('medical') && !message.includes('appointment');
+      }
+      return false
+    },
     action:
       "Kindly tell them you cannot assist with off-topic inquiries - do not engage",
     tags: ["off-topic"],
   },
 ];
 
-const routes: RouteOptions<HealthcareContext, HealthcareData>[] = [
+const routes = [
   {
     id: "route_schedule_appointment",
     title: "Schedule Appointment",
     description: "Helps the patient schedule an appointment",
-    conditions: ["The patient wants to schedule an appointment"],
+    // Mixed condition: AI context + programmatic check
+    when: [
+      "The patient wants to schedule an appointment",
+      (ctx) => !ctx.data?.orderId // Only if no existing order
+    ],
+    // Skip if patient already has urgent medical needs
+    skipIf: [
+      "patient has urgent medical emergency",
+      (ctx) => ctx.data?.urgency === "high"
+    ],
     // NEW: Required fields for route completion (instead of schema)
     requiredFields: ["appointmentType", "preferredDate", "preferredTime"],
     // NEW: Optional fields that enhance the experience
@@ -214,40 +215,35 @@ const routes: RouteOptions<HealthcareContext, HealthcareData>[] = [
         description: "Ask about symptoms",
         prompt: "Are you experiencing any symptoms?",
         collect: ["symptoms"],
-        skipIf: (data: Partial<HealthcareData>) =>
-          data.appointmentType === "checkup", // Skip for checkups
+        // Mixed skipIf: AI context + programmatic logic
+        skipIf: [
+          "routine checkup doesn't need symptom details",
+          (data: Partial<HealthcareData>) => data.appointmentType === "checkup"
+        ],
       },
       {
         id: "schedule_appointment",
         description: "Schedule the appointment",
         prompt: "I'll schedule your appointment now.",
-        tools: [scheduleAppointment], // Use the scheduling tool
+        tools: [scheduleAppointmentTool], // Inline tool - only available on this step
         requires: ["preferredDate", "preferredTime"],
-        prepare: getInsuranceProviders, // Use existing tool to prepare insurance info
-        finalize: {
-          // Inline tool to handle appointment finalization
-          id: "finalize_appointment",
-          description: "Complete the appointment booking process",
-          parameters: { type: "object", properties: {} },
-          handler: ({ context, data }) => {
-            console.log(`✅ Appointment finalized for ${context.patientName}`);
-            console.log(`📅 Details: ${JSON.stringify(data, null, 2)}`);
-
-            // Could send confirmation email, update calendar, etc.
-            return {
-              data: `Appointment confirmed for ${context.patientName}`,
-            };
-          },
-        },
+        prepare: "healthcare_insurance_providers", // Reference by ID
+        finalize: "finalize_appointment", // Reference by ID - will be registered later
       },
     ],
-    tools: [getAvailableSlots], // Route-level tools available to all steps
+    tools: ["healthcare_available_slots"], // Reference by ID
   },
   {
     id: "route_check_lab_results",
     title: "Check Lab Results",
     description: "Retrieves and explains patient lab results",
-    conditions: ["The patient wants to see their lab results"],
+    // Function-only condition for programmatic logic
+    when: (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('lab') || message.includes('test') || message.includes('results');
+    },
+    // Skip if no patient ID available
+    skipIf: (ctx) => !ctx.context?.patientId,
     // NEW: Required fields for route completion
     requiredFields: ["testType"],
     // NEW: Optional fields
@@ -260,12 +256,13 @@ const routes: RouteOptions<HealthcareContext, HealthcareData>[] = [
         tags: ["escalation"],
       },
     ],
-    tools: [getLabResults], // Route-level tools
+    tools: ["healthcare_lab_results"], // Reference by ID
   },
   {
     title: "General Healthcare Questions",
     description: "Answer general healthcare questions",
-    conditions: ["Patient asks general healthcare questions"],
+    // String-only condition for AI context
+    when: "Patient asks general healthcare questions",
     // No required fields - conversational Q&A
   },
 ];
@@ -334,8 +331,90 @@ const agent = new Agent<HealthcareContext, HealthcareData>({
   // Declarative initialization
   terms,
   guidelines,
-  tools: [getInsuranceProviders], // Agent-level tools
-  routes,
+  // Enable debug logging
+  debug: true,
+});
+
+// Demonstrate different tool registration approaches
+
+// Method 1: Register tools for ID-based reference in routes
+// Note: scheduleAppointmentTool is NOT registered globally - it's only available on the specific step
+agent.tool.registerMany([
+  getInsuranceProvidersTool,
+  getAvailableSlotsTool,
+  getLabResultsTool,
+  // scheduleAppointmentTool, // Commented out - will be added to specific step only
+]);
+
+// Method 2: Create and register specialized tools
+const appointmentValidator = agent.tool.createValidation({
+  id: "validate_appointment",
+  fields: ["appointmentType", "preferredDate", "preferredTime"] as const,
+  validator: async (context, data) => {
+    const errors: ValidationError[] = [];
+    if (!data.appointmentType) errors.push({ 
+      field: "appointmentType", 
+      value: data.appointmentType,
+      message: "Appointment type is required",
+      schemaPath: "appointmentType"
+    });
+    if (!data.preferredDate) errors.push({ 
+      field: "preferredDate", 
+      value: data.preferredDate,
+      message: "Preferred date is required",
+      schemaPath: "preferredDate"
+    });
+    if (!data.preferredTime) errors.push({ 
+      field: "preferredTime", 
+      value: data.preferredTime,
+      message: "Preferred time is required",
+      schemaPath: "preferredTime"
+    });
+    
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings: [],
+    };
+  },
+});
+
+// Method 3: Create data enrichment tool
+const patientDataEnricher = agent.tool.createDataEnrichment({
+  id: "enrich_patient_data",
+  fields: ["appointmentType", "symptoms"] as const,
+  enricher: async (context, data) => {
+    // Add urgency classification based on symptoms - return fields that exist in HealthcareData
+    const urgentKeywords = ["chest pain", "difficulty breathing", "severe", "emergency"];
+    const hasUrgentSymptoms = data.symptoms && urgentKeywords.some(keyword => 
+      data.symptoms!.toLowerCase().includes(keyword)
+    );
+    
+    return {
+      urgency: hasUrgentSymptoms ? "high" : "medium", // This matches the urgency field in HealthcareData
+    };
+  },
+});
+
+// Method 4: Create tool using tool.create()
+const finalizeAppointmentTool = agent.tool.create({
+  id: "finalize_appointment",
+  description: "Complete the appointment booking process",
+  parameters: { type: "object", properties: {} },
+  handler: async (context, args) => {
+    console.log(`✅ Appointment finalized for ${context.context.patientName}`);
+    console.log(`📅 Details: ${JSON.stringify(context.data, null, 2)}`);
+
+    // Could send confirmation email, update calendar, etc.
+    return {
+      data: `Appointment confirmed for ${context.context.patientName}`,
+    };
+  },
+});
+
+// Add routes after tools are registered
+routes.forEach((route: any) => {
+  agent.createRoute(route);
 });
 
 // You can still add more dynamically after construction
@@ -359,45 +438,26 @@ async function main() {
 
   // Turn 1 - Agent responds and routes to appropriate flow
   console.log("🔄 Turn 1: Initial inquiry");
-  await agent.session.addMessage("user", "Hi, I need to follow up on my recent visit", "Alice");
-  
-  const response1 = await agent.respond({ 
-    history: agent.session.getHistory() 
-  });
+  const response1 = await agent.chat("Hi, I need to follow up on my recent visit");
   
   console.log("🤖 Agent:", response1.message);
   console.log("🛤️  Route chosen:", response1.session?.currentRoute?.title);
 
-  await agent.session.addMessage("assistant", response1.message);
-
   // Turn 2 - User provides more details
   console.log("\n🔄 Turn 2: Providing appointment details");
-  await agent.session.addMessage("user", "I need a checkup next Tuesday at 2 PM", "Alice");
-
-  const response2 = await agent.respond({ 
-    history: agent.session.getHistory() 
-  });
+  const response2 = await agent.chat("I need a checkup next Tuesday at 2 PM");
   
   console.log("🤖 Agent:", response2.message);
   console.log("📊 Collected data:", agent.session.getData());
   console.log("📍 Current step:", response2.session?.currentStep?.id);
 
-  await agent.session.addMessage("assistant", response2.message);
-
   // Turn 3 - Continue the conversation flow
   console.log("\n🔄 Turn 3: Continuing appointment booking");
-  
-  await agent.session.addMessage("user", "I'm feeling a bit anxious about the visit", "Alice");
-
-  const response3 = await agent.respond({ 
-    history: agent.session.getHistory() 
-  });
+  const response3 = await agent.chat("I'm feeling a bit anxious about the visit");
   
   console.log("🤖 Agent:", response3.message);
   console.log("📊 Updated data:", agent.session.getData());
   console.log("📍 Current step:", response3.session?.currentStep?.id);
-  
-  await agent.session.addMessage("assistant", response3.message);
 
   // Check for route completion
   if (response3.isRouteComplete && response3.session) {

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

@@ -8,7 +8,11 @@
  * - Schema-first data definition
  * - Type-safe data extraction
  * - Automatic validation
- * - SkipIf conditions for smart flow control
+ * - NEW: Flexible ConditionTemplate patterns for routing and step control:
+ *   - String-only conditions: "user wants to register" (AI context only)
+ *   - Function-only conditions: (ctx) => ctx.data?.complete (programmatic only)
+ *   - Mixed arrays: ["user provided info", (ctx) => !!ctx.data?.name] (hybrid)
+ *   - Enhanced skipIf conditions for smart flow control
  */
 
 import { Agent, GeminiProvider, type Tool } from "../../src/index";
@@ -23,22 +27,22 @@ interface UserProfileData {
   newsletterOptIn: boolean;
 }
 
-// Define a tool that uses the collected data
-const saveUserProfile: Tool<unknown, UserProfileData, [], string> = {
+// Define a tool that uses the collected data - using unified Tool interface
+const saveUserProfileTool: Tool<unknown, UserProfileData> = {
   id: "save_user_profile",
   description: "Save the collected user profile information",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: ({ data }) => {
-    console.log("Saving user profile:", data);
+  handler: async (context, args) => {
+    console.log("Saving user profile:", context.data);
 
     // Simulate saving to database
-    console.log("Profile data:", data);
+    console.log("Profile data:", context.data);
 
     return {
-      data: `Profile saved successfully! Welcome ${data?.name}!`,
+      data: `Profile saved successfully! Welcome ${context.data?.name}!`,
     };
   },
 };
@@ -99,10 +103,23 @@ const agent = new Agent<unknown, UserProfileData>({
   schema: userProfileSchema,
 });
 
+// Add tool using unified interface
+agent.addTool(saveUserProfileTool);
+
 // Create a route that collects profile information step by step
 agent.createRoute({
   title: "User Profile Collection",
   description: "Collect comprehensive user profile information",
+  // Mixed condition: AI context + programmatic validation
+  when: [
+    "user wants to create a profile or register",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('profile') || message.includes('register') || message.includes('sign up');
+    }
+  ],
+  // Skip if user already has a complete profile
+  skipIf: (ctx) => Boolean(ctx.data?.name && ctx.data?.email && ctx.data?.age),
   // NEW: Required fields for route completion (instead of schema)
   requiredFields: ["name", "email"],
   // NEW: Optional fields that enhance the experience
@@ -114,7 +131,8 @@ agent.createRoute({
       description: "Ask for user's name",
       prompt: "Hi! I'd like to create a profile for you. What's your name?",
       collect: ["name"],
-      skipIf: (data: Partial<UserProfileData>) => !!data.name,
+      // String-only skipIf for AI context
+      skipIf: "user already provided their name",
     },
     {
       id: "ask_email",
@@ -122,7 +140,8 @@ agent.createRoute({
       prompt: "What's your email address?",
       collect: ["email"],
       requires: ["name"],
-      skipIf: (data: Partial<UserProfileData>) => !!data.email,
+      // Function-only skipIf for programmatic logic
+      skipIf: (ctx) => !!ctx.data?.email,
     },
     {
       id: "ask_age",
@@ -130,7 +149,11 @@ agent.createRoute({
       prompt: "How old are you? (optional)",
       collect: ["age"],
       requires: ["name", "email"],
-      skipIf: (data: Partial<UserProfileData>) => data.age !== undefined,
+      // Mixed skipIf: AI context + programmatic check
+      skipIf: [
+        "age already collected",
+        (ctx) => ctx.data?.age !== undefined
+      ],
     },
     {
       id: "ask_interests",
@@ -138,8 +161,11 @@ agent.createRoute({
       prompt: "What are your interests or hobbies? (optional)",
       collect: ["interests"],
       requires: ["name", "email"],
-      skipIf: (data: Partial<UserProfileData>) =>
-        !!(data.interests && data.interests.length > 0),
+      // Mixed skipIf with complex logic
+      skipIf: [
+        "interests already provided",
+        (ctx) => !!(ctx.data?.interests && ctx.data.interests.length > 0)
+      ],
     },
     {
       id: "ask_contact_preference",
@@ -147,7 +173,8 @@ agent.createRoute({
       prompt: "What's your preferred contact method?",
       collect: ["preferredContact"],
       requires: ["name", "email"],
-      skipIf: (data: Partial<UserProfileData>) => !!data.preferredContact,
+      // Function-only skipIf
+      skipIf: (ctx) => !!ctx.data?.preferredContact,
     },
     {
       id: "ask_newsletter",
@@ -155,15 +182,15 @@ agent.createRoute({
       prompt: "Would you like to subscribe to our newsletter?",
       collect: ["newsletterOptIn"],
       requires: ["name", "email"],
-      skipIf: (data: Partial<UserProfileData>) =>
-        data.newsletterOptIn !== undefined,
+      // String-only skipIf for simple cases
+      skipIf: "newsletter preference already collected",
     },
     {
       id: "save_profile",
       description: "Save the collected profile",
       prompt:
         "Thanks for providing your information! Let me save your profile.",
-      tools: [saveUserProfile],
+      tools: ["save_user_profile"], // Reference by ID
       requires: ["name", "email"],
     },
   ],