@falai/agent 0.9.2 → 1.0.1

package/examples/condition-patterns/string-only-conditions.ts

@@ -0,0 +1,296 @@
+/**
+ * String-Only Conditions Example
+ * 
+ * This example demonstrates using string-only conditions for AI context-driven routing.
+ * String conditions are perfect when you want the AI to make routing decisions based
+ * on natural language understanding rather than programmatic logic.
+ * 
+ * Key concepts:
+ * - String conditions provide AI context only
+ * - No programmatic evaluation - pure AI decision making
+ * - Perfect for natural language routing scenarios
+ * - Ideal for conversational flows where intent matters more than data
+ */
+
+import {
+  Agent,
+  GeminiProvider,
+  type Guideline,
+} from "../../src/index";
+
+// Context for a customer service chatbot
+interface CustomerContext {
+  customerId: string;
+  customerTier: "basic" | "premium" | "enterprise";
+  previousInteractions: number;
+}
+
+// Simple data schema for customer interactions
+interface CustomerData {
+  issueType?: string;
+  satisfactionRating?: number;
+  followUpNeeded?: boolean;
+}
+
+const customerSchema = {
+  type: "object",
+  properties: {
+    issueType: { type: "string" },
+    satisfactionRating: { type: "number", minimum: 1, maximum: 5 },
+    followUpNeeded: { type: "boolean" },
+  },
+};
+
+// Create agent with string-only condition examples
+const agent = new Agent<CustomerContext, CustomerData>({
+  name: "CustomerServiceBot",
+  description: "A customer service bot that uses AI context for routing decisions",
+  provider: new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY || "demo-key",
+    model: "models/gemini-2.5-flash",
+  }),
+  context: {
+    customerId: "cust_12345",
+    customerTier: "premium",
+    previousInteractions: 3,
+  },
+  schema: customerSchema,
+});
+
+// Guidelines with string-only conditions for AI context
+const guidelines: Guideline<CustomerContext>[] = [
+  {
+    // String-only condition - AI interprets the context
+    condition: "Customer is expressing frustration or anger",
+    action: "Acknowledge their feelings, apologize for the inconvenience, and escalate to a human agent if needed",
+    tags: ["empathy", "escalation"],
+  },
+  {
+    // String-only condition - AI understands satisfaction cues
+    condition: "Customer seems satisfied with the resolution",
+    action: "Thank them for their patience and ask if there's anything else you can help with",
+    tags: ["satisfaction", "closure"],
+  },
+  {
+    // String-only condition - AI detects urgency
+    condition: "Customer indicates this is an urgent or time-sensitive issue",
+    action: "Prioritize their request and provide immediate assistance or escalation",
+    tags: ["urgency", "priority"],
+  },
+];
+
+// Add guidelines to agent
+guidelines.forEach(guideline => agent.createGuideline(guideline));
+
+// Route 1: Billing Issues - String-only condition
+agent.createRoute({
+  title: "Billing Support",
+  description: "Handle billing questions and payment issues",
+  // String-only condition - AI interprets billing-related intent
+  when: "Customer has questions about billing, payments, charges, or invoices",
+  steps: [
+    {
+      id: "understand_billing_issue",
+      description: "Understand the specific billing concern",
+      prompt: "I'd be happy to help with your billing question. Can you tell me more about the specific issue you're experiencing?",
+      collect: ["issueType"],
+    },
+    {
+      id: "resolve_billing",
+      description: "Provide billing assistance",
+      prompt: "Let me help resolve your billing concern. Based on what you've told me, here's what I can do...",
+      requires: ["issueType"],
+    },
+  ],
+});
+
+// Route 2: Technical Support - String-only condition
+agent.createRoute({
+  title: "Technical Support",
+  description: "Help with technical problems and troubleshooting",
+  // String-only condition - AI understands technical issues
+  when: "Customer is experiencing technical difficulties, errors, or product malfunctions",
+  steps: [
+    {
+      id: "diagnose_technical_issue",
+      description: "Understand the technical problem",
+      prompt: "I'm here to help with your technical issue. Can you describe what's happening and when the problem started?",
+      collect: ["issueType"],
+    },
+    {
+      id: "provide_technical_solution",
+      description: "Offer technical assistance",
+      prompt: "Based on your description, let me walk you through some troubleshooting steps...",
+      requires: ["issueType"],
+    },
+  ],
+});
+
+// Route 3: Account Management - String-only condition
+agent.createRoute({
+  title: "Account Management",
+  description: "Handle account changes, updates, and settings",
+  // String-only condition - AI recognizes account-related requests
+  when: "Customer wants to make changes to their account, update information, or modify settings",
+  steps: [
+    {
+      id: "identify_account_request",
+      description: "Understand what account changes are needed",
+      prompt: "I can help you with your account. What changes would you like to make?",
+      collect: ["issueType"],
+    },
+    {
+      id: "process_account_changes",
+      description: "Assist with account modifications",
+      prompt: "I'll help you make those account changes. Let me guide you through the process...",
+      requires: ["issueType"],
+    },
+  ],
+});
+
+// Route 4: General Inquiry - String-only condition
+agent.createRoute({
+  title: "General Information",
+  description: "Answer general questions about products and services",
+  // String-only condition - AI handles general questions
+  when: "Customer has general questions about products, services, or company information",
+  steps: [
+    {
+      id: "answer_general_question",
+      description: "Provide information and answer questions",
+      prompt: "I'd be happy to answer your question. Let me provide you with the information you need...",
+    },
+  ],
+});
+
+// Route 5: Feedback Collection - String-only condition
+agent.createRoute({
+  title: "Customer Feedback",
+  description: "Collect customer feedback and satisfaction ratings",
+  // String-only condition - AI detects feedback intent
+  when: "Customer wants to provide feedback, leave a review, or share their experience",
+  requiredFields: ["satisfactionRating"],
+  optionalFields: ["followUpNeeded"],
+  steps: [
+    {
+      id: "collect_satisfaction_rating",
+      description: "Ask for satisfaction rating",
+      prompt: "Thank you for wanting to share feedback! On a scale of 1 to 5, how satisfied are you with our service today?",
+      collect: ["satisfactionRating"],
+    },
+    {
+      id: "ask_for_follow_up",
+      description: "Check if follow-up is needed",
+      prompt: "Thank you for the rating! Would you like someone from our team to follow up with you about your experience?",
+      collect: ["followUpNeeded"],
+      requires: ["satisfactionRating"],
+    },
+    {
+      id: "thank_for_feedback",
+      description: "Thank customer for feedback",
+      prompt: "We really appreciate your feedback! It helps us improve our service for all customers.",
+      requires: ["satisfactionRating"],
+    },
+  ],
+});
+
+// Route 6: Greeting and Welcome - String-only condition
+agent.createRoute({
+  title: "Welcome and Greeting",
+  description: "Welcome new customers and handle greetings",
+  // String-only condition - AI recognizes greetings and welcomes
+  when: "Customer is greeting, saying hello, or appears to be new to the service",
+  steps: [
+    {
+      id: "welcome_customer",
+      description: "Provide warm welcome",
+      prompt: "Hello! Welcome to our customer service. I'm here to help you with any questions or concerns you might have. How can I assist you today?",
+    },
+  ],
+});
+
+// Demonstration function
+async function demonstrateStringOnlyConditions() {
+  console.log("=== String-Only Conditions Demo ===\n");
+  console.log("This demo shows how string conditions let the AI make routing decisions based on natural language understanding.\n");
+
+  const testScenarios = [
+    {
+      name: "Billing Issue",
+      message: "Hi, I was charged twice for my subscription this month and I need help getting a refund",
+      expectedRoute: "Billing Support"
+    },
+    {
+      name: "Technical Problem", 
+      message: "My app keeps crashing every time I try to upload a file, can you help me fix this?",
+      expectedRoute: "Technical Support"
+    },
+    {
+      name: "Account Changes",
+      message: "I need to update my email address and change my password on my account",
+      expectedRoute: "Account Management"
+    },
+    {
+      name: "General Question",
+      message: "What are your business hours and do you offer phone support?",
+      expectedRoute: "General Information"
+    },
+    {
+      name: "Feedback",
+      message: "I had a great experience with your support team yesterday and wanted to leave some positive feedback",
+      expectedRoute: "Customer Feedback"
+    },
+    {
+      name: "Greeting",
+      message: "Hello! I'm new to your service and not sure where to start",
+      expectedRoute: "Welcome and Greeting"
+    },
+  ];
+
+  for (const scenario of testScenarios) {
+    console.log(`🔍 Testing: ${scenario.name}`);
+    console.log(`📝 Message: "${scenario.message}"`);
+    
+    try {
+      const response = await agent.respond({
+        history: [
+          {
+            role: "user",
+            content: scenario.message,
+            name: "Customer",
+          },
+        ],
+      });
+
+      console.log(`🎯 Routed to: ${response.session?.currentRoute?.title || "No route"}`);
+      console.log(`✅ Expected: ${scenario.expectedRoute}`);
+      console.log(`🤖 Response: ${response.message.substring(0, 100)}...`);
+      console.log();
+    } catch (error) {
+      console.log(`❌ Error: ${error}`);
+      console.log();
+    }
+  }
+
+  console.log("💡 Key Benefits of String-Only Conditions:");
+  console.log("   - Natural language understanding for routing");
+  console.log("   - No need to write complex programmatic logic");
+  console.log("   - AI handles intent recognition automatically");
+  console.log("   - Easy to maintain and update conditions");
+  console.log("   - Perfect for conversational, intent-based routing");
+}
+
+// Run demonstration
+async function main() {
+  try {
+    await demonstrateStringOnlyConditions();
+  } catch (error) {
+    console.error("Error:", error);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}
+
+export { agent, demonstrateStringOnlyConditions };

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

@@ -6,6 +6,12 @@
  * - Post-booking feedback collection
  * - Upsell after purchase
  * - Satisfaction surveys after support
+ * 
+ * NEW: Enhanced with flexible ConditionTemplate patterns:
+ * - Mixed route conditions: ["AI context", (ctx) => programmatic_check]
+ * - Route skipIf examples: Dynamic route exclusion based on state
+ * - Step skipIf examples: Enhanced conditional step skipping
+ * - AI context strings in action for better routing decisions
  */
 
 import {
@@ -43,7 +49,7 @@ async function main() {
   };
 
   // Create agent with unified schema
-  const agent = new Agent<unknown, UnifiedBookingData>({
+  const agent = new Agent<any, UnifiedBookingData>({
     name: "HotelBot",
     description: "A hotel booking assistant with feedback collection",
     provider: new GeminiProvider({
@@ -58,7 +64,23 @@ async function main() {
   agent.createRoute({
     title: "Book Hotel",
     description: "Collects hotel booking information",
-    conditions: ["User wants to book a hotel"],
+    // Mixed condition: AI context + programmatic validation
+    when: [
+      "User wants to book a hotel",
+      (ctx) => {
+        const event = ctx.history?.[ctx.history.length - 1]
+        if(event && "content" in event){
+          const message = (event.content as string).toLocaleLowerCase() || '';
+          return message.includes('book') || message.includes('hotel') || message.includes('reservation');
+        }
+        return false;
+      }
+    ],
+    // Skip if user already has a booking
+    skipIf: [
+      "user already has an active booking",
+      (ctx) => !!ctx.data?.hotelName && !!ctx.data?.date
+    ],
     // NEW: Required fields for route completion
     requiredFields: ["hotelName", "date", "guests"],
     // Sequential steps for booking flow
@@ -68,7 +90,8 @@ async function main() {
         description: "Ask for hotel preference",
         prompt: "Which hotel would you like to book?",
         collect: ["hotelName"],
-        skipIf: (data: Partial<UnifiedBookingData>) => !!data.hotelName,
+        // String-only skipIf for AI context
+        skipIf: "hotel already selected",
       },
       {
         id: "ask_date",
@@ -76,7 +99,8 @@ async function main() {
         prompt: "What date would you like to book for?",
         collect: ["date"],
         requires: ["hotelName"],
-        skipIf: (data: Partial<UnifiedBookingData>) => !!data.date,
+        // Function-only skipIf for programmatic check
+        skipIf: (data) => !!data.context.date,
       },
       {
         id: "ask_guests",
@@ -84,7 +108,11 @@ async function main() {
         prompt: "How many guests will be staying?",
         collect: ["guests"],
         requires: ["hotelName", "date"],
-        skipIf: (data: Partial<UnifiedBookingData>) => data.guests !== undefined,
+        // Mixed skipIf: AI context + programmatic logic
+        skipIf: [
+          "guest count already provided",
+          (data) => data.context.guests !== undefined
+        ],
       },
       {
         id: "confirm_booking",
@@ -102,7 +130,16 @@ async function main() {
   agent.createRoute({
     title: "Collect Feedback",
     description: "Collects user feedback after booking",
-    conditions: ["User wants to provide feedback"],
+    // Function-only condition for programmatic logic
+    when: (ctx) => {
+      // Only activate if we have booking data but no feedback yet
+      return !!ctx.data?.hotelName && ctx.data?.rating === undefined;
+    },
+    // Skip if feedback already collected
+    skipIf: [
+      "feedback already provided",
+      (ctx) => ctx.data?.rating !== undefined
+    ],
     // NEW: Required fields for route completion
     requiredFields: ["rating"],
     // NEW: Optional fields that enhance the experience
@@ -114,7 +151,11 @@ async function main() {
         description: "Ask for rating",
         prompt: "How would you rate your booking experience from 1 to 5?",
         collect: ["rating"],
-        skipIf: (data: Partial<UnifiedBookingData>) => data.rating !== undefined,
+        // Mixed skipIf: AI context + programmatic check
+        skipIf: [
+          "rating already provided",
+          (data) => data.context.rating !== undefined
+        ],
       },
       {
         id: "ask_comments",

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

@@ -4,10 +4,16 @@
  * 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 {
@@ -17,7 +23,6 @@ import {
   ValidationError,
   type Term,
   type Guideline,
-  type RouteOptions,
 } from "../../src/index";
 
 // Context type
@@ -130,19 +135,32 @@ 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"],
@@ -154,7 +172,16 @@ 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
@@ -188,14 +215,17 @@ const routes = [
         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: ["healthcare_schedule_appointment"], // Reference by ID
+        tools: [scheduleAppointmentTool], // Inline tool - only available on this step
         requires: ["preferredDate", "preferredTime"],
         prepare: "healthcare_insurance_providers", // Reference by ID
         finalize: "finalize_appointment", // Reference by ID - will be registered later
@@ -207,7 +237,13 @@ const routes = [
     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
@@ -225,7 +261,8 @@ const routes = [
   {
     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
   },
 ];
@@ -294,16 +331,19 @@ const agent = new Agent<HealthcareContext, HealthcareData>({
   // Declarative initialization
   terms,
   guidelines,
+  // 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,
+  // scheduleAppointmentTool, // Commented out - will be added to specific step only
 ]);
 
 // Method 2: Create and register specialized tools
@@ -398,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) {