@falai/agent 1.2.8 → 2.0.0

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

@@ -1,296 +0,0 @@
-/**
- * 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

@@ -1,318 +0,0 @@
-/**
- * Route Transitions Example
- *
- * Demonstrates how to use onComplete to automatically transition between routes
- * after a route completes, enabling flows like:
- * - 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 {
-  Agent,
-  GeminiProvider,
-  History,
-  type SessionState,
-} from "../../src/index";
-
-// Type definitions for our unified data collection
-interface UnifiedBookingData {
-  // Booking fields
-  hotelName: string;
-  date: string;
-  guests: number;
-  // Feedback fields
-  rating: number;
-  comments?: string;
-}
-
-async function main() {
-  // 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<any, UnifiedBookingData>({
-    name: "HotelBot",
-    description: "A hotel booking assistant with feedback collection",
-    provider: new GeminiProvider({
-      apiKey: process.env.GEMINI_API_KEY!,
-      model: "models/gemini-2.5-flash",
-    }),
-    debug: true,
-    schema: unifiedSchema,
-  });
-
-  // Route 1: Hotel Booking with automatic transition to feedback
-  agent.createRoute({
-    title: "Book Hotel",
-    description: "Collects hotel booking information",
-    // 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
-    steps: [
-      {
-        id: "ask_hotel",
-        description: "Ask for hotel preference",
-        prompt: "Which hotel would you like to book?",
-        collect: ["hotelName"],
-        // String-only skipIf for AI context
-        skipIf: "hotel already selected",
-      },
-      {
-        id: "ask_date",
-        description: "Ask for booking date",
-        prompt: "What date would you like to book for?",
-        collect: ["date"],
-        requires: ["hotelName"],
-        // Function-only skipIf for programmatic check
-        skipIf: (data) => !!data.context.date,
-      },
-      {
-        id: "ask_guests",
-        description: "Ask for number of guests",
-        prompt: "How many guests will be staying?",
-        collect: ["guests"],
-        requires: ["hotelName", "date"],
-        // Mixed skipIf: AI context + programmatic logic
-        skipIf: [
-          "guest count already provided",
-          (data) => data.context.guests !== undefined
-        ],
-      },
-      {
-        id: "confirm_booking",
-        description: "Confirm the booking",
-        prompt:
-          "Confirm the booking with a summary of the hotel, date, and number of guests. Be enthusiastic!",
-        requires: ["hotelName", "date", "guests"],
-      },
-    ],
-    // Automatic transition to feedback collection when booking completes
-    onComplete: "Collect Feedback",
-  });
-
-  // Route 2: Feedback Collection
-  agent.createRoute({
-    title: "Collect Feedback",
-    description: "Collects user feedback after booking",
-    // 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
-    optionalFields: ["comments"],
-    // Sequential steps for feedback collection
-    steps: [
-      {
-        id: "ask_rating",
-        description: "Ask for rating",
-        prompt: "How would you rate your booking experience from 1 to 5?",
-        collect: ["rating"],
-        // Mixed skipIf: AI context + programmatic check
-        skipIf: [
-          "rating already provided",
-          (data) => data.context.rating !== undefined
-        ],
-      },
-      {
-        id: "ask_comments",
-        description: "Ask for comments",
-        prompt:
-          "Would you like to share any additional comments about your experience?",
-        collect: ["comments"],
-      },
-      {
-        id: "thank_feedback",
-        description: "Thank user for feedback",
-        prompt:
-          "Thank the user warmly for their feedback and let them know their input is valuable",
-        requires: ["rating"],
-      },
-    ],
-    // End conversation after feedback is collected
-    onComplete: undefined, // No transition - conversation ends
-  });
-
-  console.log("\n=== Route Transitions Example ===\n");
-
-  // Conversation 1: User provides all booking info at once
-  let session: SessionState | undefined;
-  let history: History = [
-    {
-      role: "user" as const,
-      content: "I want to book the Grand Hotel for 2 guests on December 25th",
-      name: "Alice",
-    },
-  ];
-
-  console.log("User:", history[0].content);
-
-  // First response - should handle booking
-  const response1 = await agent.respond({ history, session });
-  console.log("\nBot:", response1.message);
-  console.log("Route complete?", response1.isRouteComplete);
-  console.log(
-    "Pending transition?",
-    response1.session?.pendingTransition?.targetRouteId
-  );
-  console.log("Collected data:", response1.session?.data);
-
-  session = response1.session;
-  history = [
-    ...history,
-    {
-      role: "assistant" as const,
-      content: response1.message,
-    },
-  ] as History;
-
-  // Second response - should auto-transition to a feedback route
-  history = [
-    ...history,
-    {
-      role: "user" as const,
-      content: "Yes, please proceed!",
-      name: "Alice",
-    },
-  ];
-  console.log("\nUser:", "Yes, please proceed!");
-
-  const response2 = await agent.respond({ history, session });
-  console.log("\nBot:", response2.message);
-  console.log("Current route:", response2.session?.currentRoute?.title);
-  console.log("Route complete?", response2.isRouteComplete);
-
-  session = response2.session;
-  history = [
-    ...history,
-    {
-      role: "assistant" as const,
-      content: response2.message,
-    },
-  ];
-
-  // Third response - provide rating
-  history = [
-    ...history,
-    {
-      role: "user" as const,
-      content: "I'd rate it 5 stars! The process was very smooth.",
-      name: "Alice",
-    },
-  ];
-  console.log("\nUser:", "I'd rate it 5 stars! The process was very smooth.");
-
-  const response3 = await agent.respond({ history, session });
-  console.log("\nBot:", response3.message);
-  console.log("Current route:", response3.session?.currentRoute?.title);
-  console.log("Collected data:", response3.session?.data);
-  console.log("Route complete?", response3.isRouteComplete);
-
-  console.log("\n=== Manual Transition Example ===\n");
-
-  // Demonstrate manual transition using agent.nextStepRoute()
-  let session2: SessionState | undefined;
-  let history2: History = [
-    {
-      role: "user" as const,
-      content:
-        "I want to book the Sunset Resort for 4 people on New Year's Eve",
-      name: "Bob",
-    },
-  ];
-
-  console.log("User:", history2[0].content);
-
-  const manualResponse = await agent.respond({
-    history: history2,
-    session: session2,
-  });
-  console.log("\nBot:", manualResponse.message);
-  console.log("Route complete?", manualResponse.isRouteComplete);
-
-  if (manualResponse.isRouteComplete && manualResponse.session) {
-    // Manually trigger transition instead of auto-transition
-    console.log("\n[Manually transitioning to feedback route...]");
-    session2 = await agent.nextStepRoute(
-      "Collect Feedback",
-      manualResponse.session,
-      "if booking was successful"
-    );
-    console.log(
-      "Pending transition set:",
-      session2.pendingTransition?.targetRouteId
-    );
-
-    history2 = [
-      ...history2,
-      {
-        role: "assistant" as const,
-        content: manualResponse.message,
-      },
-      {
-        role: "user" as const,
-        content: "Great!",
-        name: "Bob",
-      },
-    ];
-
-    const feedbackResponse = await agent.respond({
-      history: history2,
-      session: session2,
-    });
-    console.log("\nBot:", feedbackResponse.message);
-    console.log(
-      "Current route:",
-      feedbackResponse.session?.currentRoute?.title
-    );
-  }
-
-  console.log("\n=== Done ===\n");
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main().catch(console.error);
-}