@falai/agent 0.9.2 → 1.0.1

package/examples/advanced-patterns/route-lifecycle-hooks.ts

@@ -4,6 +4,14 @@
  *
  * Demonstrates how to use rules and prohibitions to control agent behavior
  * in different conversation routes (e.g., WhatsApp bot with different styles)
+ * 
+ * NEW: Enhanced with complex ConditionTemplate patterns:
+ * - Mixed conditions: ["AI context", (ctx) => keyword_detection]
+ * - Route skipIf: Dynamic route exclusion based on message analysis
+ * - Function-only conditions: (ctx) => sophisticated_routing_logic
+ * - String-only conditions: "simple AI context for general chat"
+ * - Emergency routing with never-skip logic (skipIf: false)
+ * - Performance patterns for real-time condition evaluation
  */
 
 import { Agent, type History, END_ROUTE, OpenAIProvider } from "../../src";
@@ -112,7 +120,23 @@ const agent = new Agent<unknown, ServiceData>({
 agent.createRoute({
   title: "Quick Support",
   description: "Fast answers for common questions",
-  conditions: ["User has a simple question", "User wants quick help"],
+  // Mixed condition: AI context + programmatic validation
+  when: [
+    "User has a simple question", 
+    "User wants quick help",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('quick') || message.includes('simple') || message.length < 50;
+    }
+  ],
+  // Skip if user seems to need detailed help
+  skipIf: [
+    "user needs detailed or complex assistance",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('detailed') || message.includes('complex') || message.length > 100;
+    }
+  ],
   rules: [
     "Keep messages extremely short (1-2 lines maximum)",
     "Use bullet points for lists",
@@ -130,9 +154,21 @@ agent.createRoute({
 agent.createRoute({
   title: "Sales Consultation",
   description: "Help customer discover needs and present solutions",
-  conditions: [
-    "User is interested in buying",
-    "User wants product information",
+  // Function-only condition for programmatic sales detection
+  when: (ctx) => {
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return message.includes('buy') || message.includes('purchase') || 
+           message.includes('price') || message.includes('cost') ||
+           message.includes('product') || message.includes('interested');
+  },
+  // Skip if user is having technical issues
+  skipIf: [
+    "user has technical problems that need solving first",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('broken') || message.includes('error') || 
+             message.includes('not working') || message.includes('problem');
+    }
   ],
   rules: [
     "Ask open-ended questions to discover needs",
@@ -169,7 +205,22 @@ agent.createRoute({
 agent.createRoute({
   title: "Technical Support",
   description: "Help with technical issues and troubleshooting",
-  conditions: ["User has technical problem", "User needs step-by-step help"],
+  // Mixed condition: AI context + technical keyword detection
+  when: [
+    "User has technical problem", 
+    "User needs step-by-step help",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('help') || message.includes('problem') || 
+             message.includes('error') || message.includes('not working') ||
+             message.includes('broken') || message.includes('fix');
+    }
+  ],
+  // Skip if user is just browsing or asking about sales
+  skipIf: (ctx) => {
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return message.includes('price') || message.includes('buy') || message.includes('cost');
+  },
   rules: [
     "Provide clear, numbered steps",
     "Use simple language for technical concepts",
@@ -209,7 +260,19 @@ techSupportRoute.initialStep
 agent.createRoute({
   title: "Emergency Support",
   description: "Handle urgent customer issues",
-  conditions: ["Customer is frustrated", "Urgent issue", "Service down"],
+  // Mixed condition: AI context + urgency detection
+  when: [
+    "Customer is frustrated", 
+    "Urgent issue", 
+    "Service down",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      const urgentWords = ['urgent', 'emergency', 'critical', 'down', 'broken', 'frustrated', 'angry'];
+      return urgentWords.some(word => message.includes(word)) || message.includes('!!!');
+    }
+  ],
+  // Never skip emergency support
+  skipIf: ()=>false,
   rules: [
     "Acknowledge the urgency immediately",
     "Express empathy and understanding",
@@ -229,7 +292,14 @@ agent.createRoute({
 agent.createRoute({
   title: "General Chat",
   description: "Casual conversation and general questions",
-  conditions: ["User is just chatting", "Greeting", "General question"],
+  // String-only condition for AI context
+  when: "User is just chatting, greeting, or asking general questions",
+  // Skip if user has specific needs that other routes can handle
+  skipIf: (ctx) => {
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return message.includes('help') || message.includes('buy') || 
+           message.includes('problem') || message.includes('urgent');
+  },
   rules: [
     "Be friendly and conversational",
     "Use emojis naturally 😊",
@@ -262,7 +332,7 @@ async function demonstrateRulesAndProhibitions() {
   agent.createRoute({
     title: "Quick Support",
     description: "Fast answers for common questions",
-    conditions: ["User has a simple question", "User wants quick help"],
+    when: ["User has a simple question", "User wants quick help"],
     rules: [
       "Keep messages extremely short (1-2 lines maximum)",
       "Use bullet points for lists",
@@ -280,7 +350,7 @@ async function demonstrateRulesAndProhibitions() {
   agent.createRoute({
     title: "Sales Consultation",
     description: "Help customer discover needs and present solutions",
-    conditions: [
+    when: [
       "User is interested in buying",
       "User wants product information",
     ],
@@ -303,7 +373,7 @@ async function demonstrateRulesAndProhibitions() {
   agent.createRoute({
     title: "Technical Support",
     description: "Help with technical issues and troubleshooting",
-    conditions: ["User has technical problem", "User needs step-by-step help"],
+    when: ["User has technical problem", "User needs step-by-step help"],
     rules: [
       "Provide clear, numbered steps",
       "Use simple language for technical concepts",
@@ -343,7 +413,7 @@ async function demonstrateRulesAndProhibitions() {
   agent.createRoute({
     title: "Emergency Support",
     description: "Handle urgent customer issues",
-    conditions: ["Customer is frustrated", "Urgent issue", "Service down"],
+    when: ["Customer is frustrated", "Urgent issue", "Service down"],
     rules: [
       "Acknowledge the urgency immediately",
       "Express empathy and understanding",
@@ -363,7 +433,7 @@ async function demonstrateRulesAndProhibitions() {
   agent.createRoute({
     title: "General Chat",
     description: "Casual conversation and general questions",
-    conditions: ["User is just chatting", "Greeting", "General question"],
+    when: ["User is just chatting", "Greeting", "General question"],
     rules: [
       "Be friendly and conversational",
       "Use emojis naturally 😊",

package/examples/advanced-patterns/streaming-responses.ts

@@ -361,7 +361,7 @@ async function modernStreamingWithRoutes() {
   const supportRoute = agent.createRoute({
     title: "Product Support",
     description: "Help users with product questions",
-    conditions: ["User asks about product features or issues"],
+    when: ["User asks about product features or issues"],
   });
 
   supportRoute.initialStep.nextStep({
@@ -372,7 +372,7 @@ async function modernStreamingWithRoutes() {
   agent.createRoute({
     title: "Collect Feedback",
     description: "Collect user feedback on their support experience",
-    conditions: ["User wants to provide feedback"],
+    when: ["User wants to provide feedback"],
     // NEW: Required fields for route completion
     requiredFields: ["rating"],
     // NEW: Optional fields

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

@@ -135,7 +135,7 @@ For example: "Research the impact of artificial intelligence on healthcare, comp
 const askTopic = researchRoute.initialStep.nextStep({
   prompt: "What topic would you like me to research?",
   collect: ["topic"],
-  skipIf: (data) => !!data.topic,
+  skipIf: (ctx) => !!ctx.data?.topic,
 });
 
 const askDepth = askTopic.nextStep({
@@ -143,14 +143,14 @@ const askDepth = askTopic.nextStep({
     "How deep should I go with this research? (overview, detailed, or comprehensive)",
   collect: ["depth"],
   requires: ["topic"],
-  skipIf: (data) => !!data.depth,
+  skipIf: (ctx) => !!ctx.data?.depth,
 });
 
 const askSources = askDepth.nextStep({
   prompt: "How many sources should I analyze? (1-20, default is 5)",
   collect: ["sources"],
   requires: ["topic"],
-  skipIf: (data) => data.sources !== undefined,
+  skipIf: (ctx) => ctx.data?.sources !== undefined,
 });
 
 const askFormat = askSources.nextStep({
@@ -158,7 +158,7 @@ const askFormat = askSources.nextStep({
     "What format would you prefer for the results? (summary, bullet_points, or structured)",
   collect: ["format"],
   requires: ["topic"],
-  skipIf: (data) => !!data.format,
+  skipIf: (ctx) => !!ctx.data?.format,
 });
 
 askFormat.nextStep({

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

@@ -131,7 +131,7 @@ async function main() {
   const weatherRoute = agent.createRoute({
     title: "Check Weather",
     description: "Help user check weather for a location",
-    conditions: ["User wants to know the weather"],
+    when: ["User wants to know the weather"],
   });
 
   // Step 1: Collect location

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

@@ -0,0 +1,365 @@
+/**
+ * Function-Only Conditions Example
+ * 
+ * This example demonstrates using function-only conditions for programmatic routing.
+ * Function conditions are perfect when you need precise, deterministic routing logic
+ * based on data, state, or complex business rules.
+ * 
+ * Key concepts:
+ * - Function conditions provide programmatic evaluation only
+ * - Return boolean values for routing decisions
+ * - Perfect for data-driven routing scenarios
+ * - Ideal for complex business logic and state-based routing
+ */
+
+import {
+  Agent,
+  GeminiProvider,
+  type Guideline,
+} from "../../src/index";
+
+// Context for an e-commerce system
+interface EcommerceContext {
+  userId: string;
+  userTier: "bronze" | "silver" | "gold" | "platinum";
+  accountBalance: number;
+  region: string;
+  isBusinessAccount: boolean;
+}
+
+// Order data schema
+interface OrderData {
+  productId?: string;
+  quantity?: number;
+  totalAmount?: number;
+  shippingMethod?: "standard" | "express" | "overnight";
+  paymentMethod?: "credit" | "debit" | "paypal" | "crypto";
+  discountApplied?: boolean;
+  orderComplete?: boolean;
+}
+
+const orderSchema = {
+  type: "object",
+  properties: {
+    productId: { type: "string" },
+    quantity: { type: "number", minimum: 1 },
+    totalAmount: { type: "number", minimum: 0 },
+    shippingMethod: { type: "string", enum: ["standard", "express", "overnight"] },
+    paymentMethod: { type: "string", enum: ["credit", "debit", "paypal", "crypto"] },
+    discountApplied: { type: "boolean" },
+    orderComplete: { type: "boolean" },
+  },
+};
+
+// Create agent with function-only condition examples
+const agent = new Agent<EcommerceContext, OrderData>({
+  name: "EcommerceBot",
+  description: "An e-commerce bot that uses programmatic logic for routing decisions",
+  provider: new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY || "demo-key",
+    model: "models/gemini-2.5-flash",
+  }),
+  context: {
+    userId: "user_12345",
+    userTier: "gold",
+    accountBalance: 1500.00,
+    region: "US",
+    isBusinessAccount: false,
+  },
+  schema: orderSchema,
+});
+
+// Guidelines with function-only conditions for programmatic logic
+const guidelines: Guideline<EcommerceContext>[] = [
+  {
+    // Function-only condition - check user tier for premium features
+    condition: (ctx) => ctx.context?.userTier === "platinum",
+    action: "Offer premium features like white-glove service, priority support, and exclusive products",
+    tags: ["premium", "vip"],
+  },
+  {
+    // Function-only condition - check account balance for payment options
+    condition: (ctx) => (ctx.context?.accountBalance || 0) < 100,
+    action: "Suggest payment plans or financing options for large purchases",
+    tags: ["financing", "payment"],
+  },
+  {
+    // Function-only condition - check business account status
+    condition: (ctx) => ctx.context?.isBusinessAccount === true,
+    action: "Offer bulk pricing, invoicing options, and business-specific features",
+    tags: ["business", "bulk"],
+  },
+];
+
+// Add guidelines to agent
+guidelines.forEach(guideline => agent.createGuideline(guideline));
+
+// Route 1: VIP Customer Route - Function-only condition
+agent.createRoute({
+  title: "VIP Customer Service",
+  description: "Special handling for premium customers",
+  // Function-only condition - programmatic tier check
+  when: (ctx) => ctx.context?.userTier === "platinum" || ctx.context?.userTier === "gold",
+  // Skip if customer has active issues
+  skipIf: (ctx) => (ctx.data?.totalAmount || 0) > (ctx.context?.accountBalance || 0),
+  steps: [
+    {
+      id: "vip_greeting",
+      description: "Provide VIP greeting and priority service",
+      prompt: "Welcome back! As a valued VIP customer, you have access to our premium services. How can I assist you today?",
+    },
+  ],
+});
+
+// Route 2: Large Order Processing - Function-only condition
+agent.createRoute({
+  title: "Large Order Processing",
+  description: "Handle high-value orders with special processing",
+  // Function-only condition - check order value
+  when: (ctx) => (ctx.data?.totalAmount || 0) > 1000,
+  // Skip if insufficient balance
+  skipIf: (ctx) => (ctx.data?.totalAmount || 0) > (ctx.context?.accountBalance || 0) * 2,
+  requiredFields: ["productId", "quantity", "totalAmount"],
+  optionalFields: ["shippingMethod", "paymentMethod"],
+  steps: [
+    {
+      id: "verify_large_order",
+      description: "Verify large order details",
+      prompt: "I see you're placing a large order. Let me verify the details and check for any available discounts.",
+      collect: ["productId", "quantity", "totalAmount"],
+    },
+    {
+      id: "apply_bulk_discount",
+      description: "Apply bulk discounts if eligible",
+      prompt: "Based on your order size, you're eligible for bulk pricing. Let me apply the best available discount.",
+      requires: ["totalAmount"],
+    },
+  ],
+});
+
+// Route 3: Business Account Route - Function-only condition
+agent.createRoute({
+  title: "Business Account Services",
+  description: "Specialized services for business customers",
+  // Function-only condition - check business account status
+  when: (ctx) => ctx.context?.isBusinessAccount === true,
+  // Skip if personal shopping (small quantities)
+  skipIf: (ctx) => (ctx.data?.quantity || 0) < 10,
+  steps: [
+    {
+      id: "business_options",
+      description: "Present business-specific options",
+      prompt: "I see you're shopping with a business account. Would you like to see bulk pricing, invoicing options, or set up recurring orders?",
+    },
+  ],
+});
+
+// Route 4: Regional Compliance Route - Function-only condition
+agent.createRoute({
+  title: "Regional Compliance",
+  description: "Handle region-specific requirements and restrictions",
+  // Function-only condition - check region for compliance
+  when: (ctx) => ctx.context?.region === "EU" || ctx.context?.region === "CA",
+  // Skip if already compliant
+  skipIf: (ctx) => ctx.data?.orderComplete === true,
+  steps: [
+    {
+      id: "compliance_check",
+      description: "Verify regional compliance requirements",
+      prompt: "I need to verify some regional compliance requirements for your order. This will just take a moment.",
+    },
+  ],
+});
+
+// Route 5: Payment Method Route - Function-only condition
+agent.createRoute({
+  title: "Payment Processing",
+  description: "Handle payment method selection and processing",
+  // Function-only condition - check if payment method is needed
+  when: (ctx) => !ctx.data?.paymentMethod && (ctx.data?.totalAmount || 0) > 0,
+  // Skip if order is already complete
+  skipIf: (ctx) => ctx.data?.orderComplete === true,
+  requiredFields: ["paymentMethod"],
+  steps: [
+    {
+      id: "select_payment_method",
+      description: "Help customer select payment method",
+      prompt: "What payment method would you like to use for this order?",
+      collect: ["paymentMethod"],
+    },
+    {
+      id: "process_payment",
+      description: "Process the payment",
+      prompt: "Processing your payment now. Please wait a moment...",
+      requires: ["paymentMethod", "totalAmount"],
+    },
+  ],
+});
+
+// Route 6: Shipping Options Route - Function-only condition
+agent.createRoute({
+  title: "Shipping Selection",
+  description: "Handle shipping method selection based on customer tier and order value",
+  // Function-only condition - check if shipping is needed
+  when: (ctx) => Boolean(!ctx.data?.shippingMethod && ctx.data?.productId),
+  // Skip if digital product (no shipping needed)
+  skipIf: (ctx) => Boolean(ctx.data?.productId?.startsWith("digital_")),
+  optionalFields: ["shippingMethod"],
+  steps: [
+    {
+      id: "shipping_options",
+      description: "Present shipping options based on customer tier",
+      prompt: "Let me show you the available shipping options for your order.",
+      collect: ["shippingMethod"],
+      // Function-only when condition for step
+      when: (ctx) => {
+        // VIP customers get free express shipping
+        if (ctx.context?.userTier === "platinum" || ctx.context?.userTier === "gold") {
+          return true;
+        }
+        // Regular customers need to choose
+        return (ctx.data?.totalAmount || 0) > 50;
+      },
+    },
+  ],
+});
+
+// Route 7: Order Completion Route - Function-only condition
+agent.createRoute({
+  title: "Order Completion",
+  description: "Finalize and complete the order",
+  // Function-only condition - check if order is ready to complete
+  when: (ctx) => {
+    return !!(ctx.data?.productId &&
+      ctx.data?.quantity &&
+      ctx.data?.totalAmount &&
+      ctx.data?.paymentMethod &&
+      !ctx.data?.orderComplete);
+  },
+  // Never skip order completion
+  skipIf: ()=>false,
+  steps: [
+    {
+      id: "finalize_order",
+      description: "Complete the order",
+      prompt: "Perfect! Let me finalize your order now.",
+      requires: ["productId", "quantity", "totalAmount", "paymentMethod"],
+    },
+  ],
+});
+
+// Demonstration function
+async function demonstrateFunctionOnlyConditions() {
+  console.log("=== Function-Only Conditions Demo ===\n");
+  console.log("This demo shows how function conditions enable precise, programmatic routing decisions.\n");
+
+  const testScenarios = [
+    {
+      name: "VIP Customer",
+      context: { userTier: "platinum" as const, accountBalance: 5000, region: "US", isBusinessAccount: false },
+      message: "I'd like to place an order",
+      expectedRoute: "VIP Customer Service"
+    },
+    {
+      name: "Large Order",
+      context: { userTier: "silver" as const, accountBalance: 2000, region: "US", isBusinessAccount: false },
+      data: { totalAmount: 1500 },
+      message: "I want to buy this expensive item",
+      expectedRoute: "Large Order Processing"
+    },
+    {
+      name: "Business Account",
+      context: { userTier: "bronze" as const, accountBalance: 1000, region: "US", isBusinessAccount: true },
+      message: "I need to place a bulk order for my company",
+      expectedRoute: "Business Account Services"
+    },
+    {
+      name: "EU Customer",
+      context: { userTier: "silver" as const, accountBalance: 800, region: "EU", isBusinessAccount: false },
+      message: "I want to place an order",
+      expectedRoute: "Regional Compliance"
+    },
+    {
+      name: "Payment Needed",
+      context: { userTier: "bronze" as const, accountBalance: 500, region: "US", isBusinessAccount: false },
+      data: { productId: "prod_123", quantity: 2, totalAmount: 200 },
+      message: "How do I pay for this?",
+      expectedRoute: "Payment Processing"
+    },
+    {
+      name: "Shipping Selection",
+      context: { userTier: "gold" as const, accountBalance: 1200, region: "US", isBusinessAccount: false },
+      data: { productId: "prod_456", quantity: 1, totalAmount: 150, paymentMethod: "credit" as const },
+      message: "What shipping options do I have?",
+      expectedRoute: "Shipping Selection"
+    },
+  ];
+
+  for (const scenario of testScenarios) {
+    console.log(`🔍 Testing: ${scenario.name}`);
+    console.log(`📝 Message: "${scenario.message}"`);
+
+    // Create agent with specific context for this scenario
+    const testAgent = new Agent<EcommerceContext, OrderData>({
+      name: "TestBot",
+      description: "Test bot for function conditions",
+      provider: new GeminiProvider({
+        apiKey: process.env.GEMINI_API_KEY || "demo-key",
+        model: "models/gemini-2.5-flash",
+      }),
+      context: {
+        userId: "test_user",
+        ...scenario.context,
+      },
+      schema: orderSchema,
+    });
+
+    // Copy routes from main agent
+    agent.getRoutes().forEach(route => {
+      testAgent.createRoute(route.toOptions());
+    });
+
+    try {
+      const response = await testAgent.respond({
+        history: [
+          {
+            role: "user",
+            content: scenario.message,
+            name: "Customer",
+          },
+        ],
+        session: scenario.data ? { id: "test-scenario", data: scenario.data } : undefined,
+      });
+
+      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 Function-Only Conditions:");
+  console.log("   - Precise, deterministic routing logic");
+  console.log("   - Access to full context and data for decisions");
+  console.log("   - Complex business rules and state-based routing");
+  console.log("   - Type-safe condition evaluation");
+  console.log("   - Perfect for data-driven applications");
+}
+
+// Run demonstration
+async function main() {
+  try {
+    await demonstrateFunctionOnlyConditions();
+  } catch (error) {
+    console.error("Error:", error);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}
+
+export { agent, demonstrateFunctionOnlyConditions };