@falai/agent 0.6.3 → 0.6.5

package/examples/redis-persistence.ts

@@ -16,6 +16,7 @@ import {
   EventSource,
   MessageEventData,
   Event,
+  END_STATE,
 } from "../src/index";
 // @ts-ignore
 import Redis from "ioredis";
@@ -46,6 +47,17 @@ interface SupportTicketData {
   description: string;
 }
 
+interface QuickChatData {
+  topic: string;
+  sentiment: "positive" | "neutral" | "negative";
+}
+
+interface OrderData {
+  productId: string;
+  quantity: number;
+  shippingAddress: string;
+}
+
 async function example() {
   // Initialize Redis client
   const redis = new Redis();
@@ -137,7 +149,8 @@ async function example() {
     .transitionTo({
       chatState: "Confirm and create ticket",
       requiredData: ["issue", "category", "description"],
-    });
+    })
+    .transitionTo({ state: END_STATE });
 
   const persistence = agent.getPersistenceManager();
   if (!persistence) return;
@@ -231,6 +244,13 @@ async function example() {
     content: response2.message,
   });
 
+  if (response2.isRouteComplete) {
+    console.log("\n✅ Support ticket route complete!");
+    await fileSupportTicket(
+      agent.getExtractedData(session.id) as SupportTicketData
+    );
+  }
+
   // Load session state from Redis (demonstrates persistence)
   console.log("\n--- Loading Session from Redis ---");
   const loadedSession = await persistence.loadSessionState<SupportTicketData>(
@@ -260,11 +280,6 @@ async function example() {
 async function highThroughputExample() {
   const redis = new Redis();
 
-  interface QuickChatData {
-    topic: string;
-    sentiment: "positive" | "neutral" | "negative";
-  }
-
   const agent = new Agent({
     name: "Chat Bot",
     description: "Fast chat responses",
@@ -303,10 +318,12 @@ async function highThroughputExample() {
     },
   });
 
-  chatRoute.initialState.transitionTo({
-    chatState: "Chat and extract topic/sentiment",
-    gather: ["topic", "sentiment"],
-  });
+  chatRoute.initialState
+    .transitionTo({
+      chatState: "Chat and extract topic/sentiment",
+      gather: ["topic", "sentiment"],
+    })
+    .transitionTo({ state: END_STATE });
 
   const persistence = agent.getPersistenceManager()!;
 
@@ -331,6 +348,14 @@ async function highThroughputExample() {
 
   console.log("🤖 Response:", response.message);
   console.log("📊 Extracted:", response.session?.extracted);
+
+  if (response.isRouteComplete) {
+    console.log("\n✅ Chat analytics route complete!");
+    await logChatAnalytics(
+      agent.getExtractedData(sessionData.id) as QuickChatData
+    );
+  }
+
   console.log("💾 Session state cached in Redis!");
 
   await redis.quit();
@@ -343,12 +368,6 @@ async function highThroughputExample() {
 async function sessionRecoveryExample() {
   const redis = new Redis();
 
-  interface OrderData {
-    productId: string;
-    quantity: number;
-    shippingAddress: string;
-  }
-
   const agent = new Agent({
     name: "Order Assistant",
     ai: new GeminiProvider({
@@ -383,7 +402,8 @@ async function sessionRecoveryExample() {
     .transitionTo({
       chatState: "Ask for shipping address",
       gather: ["shippingAddress"],
-    });
+    })
+    .transitionTo({ state: END_STATE });
 
   const persistence = agent.getPersistenceManager()!;
 
@@ -446,11 +466,63 @@ async function sessionRecoveryExample() {
 
   console.log("🤖 Response:", response2.message);
   console.log("📊 Final extracted data:", response2.session?.extracted);
+
+  if (response2.isRouteComplete) {
+    console.log("\n✅ Order placement complete!");
+    await processOrder(
+      agent.getExtractedData(sessionId) as unknown as OrderData
+    );
+  }
+
   console.log("✅ Order complete with recovered session!");
 
   await redis.quit();
 }
 
+/**
+ * Mock function to file a support ticket.
+ * @param data - The support ticket data.
+ */
+async function fileSupportTicket(data: SupportTicketData) {
+  console.log("\n" + "=".repeat(60));
+  console.log("🎫 Filing Support Ticket...");
+  console.log("=".repeat(60));
+  console.log("Ticket Details:", JSON.stringify(data, null, 2));
+  console.log(
+    `   - Filing ticket for issue: ${data.issue} with priority: ${data.priority}`
+  );
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log("✨ Ticket filed successfully!");
+}
+
+/**
+ * Mock function to log chat analytics.
+ * @param data - The chat data.
+ */
+async function logChatAnalytics(data: QuickChatData) {
+  console.log("\n" + "=".repeat(60));
+  console.log("📊 Logging Chat Analytics...");
+  console.log("=".repeat(60));
+  console.log("Chat Details:", JSON.stringify(data, null, 2));
+  console.log(`   - Logging chat with topic: ${data.topic}`);
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  console.log("✨ Analytics logged!");
+}
+
+/**
+ * Mock function to process an order.
+ * @param data - The order data.
+ */
+async function processOrder(data: OrderData) {
+  console.log("\n" + "=".repeat(60));
+  console.log("📦 Processing Order...");
+  console.log("=".repeat(60));
+  console.log("Order Details:", JSON.stringify(data, null, 2));
+  console.log(`   - Processing order for product: ${data.productId}`);
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log("✨ Order processed successfully!");
+}
+
 // Run the example
 if (require.main === module) {
   example().catch(console.error);

package/examples/rules-prohibitions.ts

@@ -8,26 +8,37 @@
 
 import {
   Agent,
-  createMessageEvent,
+  type Event,
+  type MessageEventData,
+  EventKind,
   EventSource,
-  createSession,
-} from "../src/index";
-import { AnthropicProvider } from "../src/providers";
+  END_STATE,
+} from "../src";
+import { OpenAIProvider } from "../src/providers/OpenAIProvider";
 
-// Initialize AI provider
-const ai = new AnthropicProvider({
-  apiKey: process.env.ANTHROPIC_API_KEY || "your-api-key-here",
-  model: "claude-sonnet-4-5",
+/**
+ * Configuration for the AI provider
+ */
+const ai = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY || "your-api-key-here",
+  model: "gpt-5",
 });
 
-// Create WhatsApp support bot with different styles per route
+/**
+ * Create a new agent instance with predefined routes and rules/prohibitions.
+ */
 const agent = new Agent({
-  name: "SupportBot",
-  description: "Customer support assistant for WhatsApp",
+  name: "CustomerServiceAgent",
+  description:
+    "A versatile customer service agent that adapts its behavior based on the conversation's context.",
+  goal: "Provide excellent customer service by following route-specific rules and prohibitions.",
   ai,
+  debug: true,
 });
 
-// Route 1: Quick Support - Short, direct messages
+/**
+ * Add routes to the agent.
+ */
 agent.createRoute({
   title: "Quick Support",
   description: "Fast answers for common questions",
@@ -46,7 +57,6 @@ agent.createRoute({
   ],
 });
 
-// Route 2: Sales Consultation - Conversational, engaging
 agent.createRoute({
   title: "Sales Consultation",
   description: "Help customer discover needs and present solutions",
@@ -70,7 +80,6 @@ agent.createRoute({
   ],
 });
 
-// Route 3: Technical Support - Detailed, step-by-step
 agent.createRoute({
   title: "Technical Support",
   description: "Help with technical issues and troubleshooting",
@@ -90,7 +99,27 @@ agent.createRoute({
   ],
 });
 
-// Route 4: Emergency Support - Calm, reassuring, action-oriented
+// Add a stateful feedback flow to the Technical Support route
+const techSupportRoute = agent
+  .getRoutes()
+  .find((r) => r.title === "Technical Support")!;
+techSupportRoute.initialState
+  .transitionTo({
+    chatState: "Provide step-by-step technical assistance.",
+  })
+  .transitionTo({
+    chatState: "Ask for a rating of the support provided (1-5).",
+    gather: ["feedbackRating"],
+  })
+  .transitionTo({
+    chatState: "Ask for any additional comments.",
+    gather: ["feedbackComments"],
+  })
+  .transitionTo({
+    chatState: "Thank the user for their feedback.",
+  })
+  .transitionTo({ state: END_STATE });
+
 agent.createRoute({
   title: "Emergency Support",
   description: "Handle urgent customer issues",
@@ -111,7 +140,6 @@ agent.createRoute({
   ],
 });
 
-// Route 5: General Chat - Friendly, casual, helpful
 agent.createRoute({
   title: "General Chat",
   description: "Casual conversation and general questions",
@@ -129,151 +157,284 @@ agent.createRoute({
   ],
 });
 
-// Demonstration function
+/**
+ * Demonstration function to show how the agent responds to different scenarios.
+ */
 async function demonstrateRulesAndProhibitions() {
-  console.log("\n=== Rules & Prohibitions Demo ===\n");
-
-  // Example 1: Quick Support - Should be short and direct
-  console.log("1️⃣  Quick Support Route (short, direct)");
-  const history1 = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Alice",
-      "What are your business hours?"
-    ),
+  const agent = new Agent({
+    name: "CustomerServiceAgent",
+    description:
+      "A versatile customer service agent that adapts its behavior based on the conversation's context.",
+    goal: "Provide excellent customer service by following route-specific rules and prohibitions.",
+    ai,
+    debug: true,
+  });
+
+  // Add domains
+  agent.createRoute({
+    title: "Quick Support",
+    description: "Fast answers for common questions",
+    conditions: ["User has a simple question", "User wants quick help"],
+    rules: [
+      "Keep messages extremely short (1-2 lines maximum)",
+      "Use bullet points for lists",
+      "Maximum 1 emoji per message 👍",
+      "Be direct and to the point",
+    ],
+    prohibitions: [
+      "Never send long paragraphs",
+      "Do not over-explain",
+      "Never use more than 2 emojis",
+      "Do not ask follow-up questions unless necessary",
+    ],
+  });
+
+  agent.createRoute({
+    title: "Sales Consultation",
+    description: "Help customer discover needs and present solutions",
+    conditions: [
+      "User is interested in buying",
+      "User wants product information",
+    ],
+    rules: [
+      "Ask open-ended questions to discover needs",
+      "Use storytelling when presenting solutions",
+      "Emoji to reinforce positive emotions 😊✨",
+      "Present value before mentioning price",
+      "Make customer feel special and understood",
+    ],
+    prohibitions: [
+      "Never talk about price before showing value",
+      "Do not pressure or push",
+      "Avoid technical jargon",
+      "Never send more than 2 messages without waiting for response",
+      "Do not make promises you cannot keep",
+    ],
+  });
+
+  agent.createRoute({
+    title: "Technical Support",
+    description: "Help with technical issues and troubleshooting",
+    conditions: ["User has technical problem", "User needs step-by-step help"],
+    rules: [
+      "Provide clear, numbered steps",
+      "Use simple language for technical concepts",
+      "Confirm understanding after each major step",
+      "Offer screenshots or visual aids when helpful",
+      "Be patient and thorough",
+    ],
+    prohibitions: [
+      "Never skip steps or assume knowledge",
+      "Do not use excessive technical terms without explanation",
+      "Never blame the user for the issue",
+      "Do not rush through explanations",
+    ],
+  });
+
+  // Add a stateful feedback flow to the Technical Support route
+  const techSupportRoute = agent
+    .getRoutes()
+    .find((r) => r.title === "Technical Support")!;
+  techSupportRoute.initialState
+    .transitionTo({
+      chatState: "Provide step-by-step technical assistance.",
+    })
+    .transitionTo({
+      chatState: "Ask for a rating of the support provided (1-5).",
+      gather: ["feedbackRating"],
+    })
+    .transitionTo({
+      chatState: "Ask for any additional comments.",
+      gather: ["feedbackComments"],
+    })
+    .transitionTo({
+      chatState: "Thank the user for their feedback.",
+    })
+    .transitionTo({ state: END_STATE });
+
+  agent.createRoute({
+    title: "Emergency Support",
+    description: "Handle urgent customer issues",
+    conditions: ["Customer is frustrated", "Urgent issue", "Service down"],
+    rules: [
+      "Acknowledge the urgency immediately",
+      "Express empathy and understanding",
+      "Provide concrete next steps",
+      "Set clear expectations on resolution time",
+      "Keep customer updated",
+    ],
+    prohibitions: [
+      "Never downplay the customer's concern",
+      "Do not use emojis (keep it professional)",
+      'Never say "calm down" or similar dismissive phrases',
+      "Do not transfer without explaining why",
+      "Never make excuses or blame others",
+    ],
+  });
+
+  agent.createRoute({
+    title: "General Chat",
+    description: "Casual conversation and general questions",
+    conditions: ["User is just chatting", "Greeting", "General question"],
+    rules: [
+      "Be friendly and conversational",
+      "Use emojis naturally 😊",
+      "Mirror the customer's tone and energy",
+      "Keep it light and positive",
+    ],
+    prohibitions: [
+      "Do not be overly formal",
+      "Never ignore the customer's mood",
+      "Do not push products unless asked",
+    ],
+  });
+
+  console.info("\n=== Rules & Prohibitions Demo ===\n");
+
+  // --- Quick Support ---
+  console.info("1️⃣  Quick Support Route (short, direct)");
+  const quickSupportHistory: Event[] = [
+    {
+      kind: EventKind.MESSAGE,
+      source: EventSource.CUSTOMER,
+      data: {
+        participant: { display_name: "User" },
+        message: "How do I reset my password?",
+      },
+    },
   ];
-
-  // Initialize session state for multi-turn conversation
-  let session = createSession();
-
-  const response1 = await agent.respond({ history: history1, session });
-  console.log(`Route: ${response1.session?.currentRoute?.title}`);
-  console.log(`Response: ${response1.message}`);
-  console.log(`Expected: Short, direct, max 1 emoji\n`);
-
-  // Update session with progress
-  session = response1.session!;
-
-  // Example 2: Sales Consultation - Should be engaging and value-focused
-  console.log("2️⃣  Sales Consultation Route (conversational, value-first)");
-  const history2 = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Bob",
-      "I'm interested in your premium plan"
-    ),
+  const response1 = await agent.respond({ history: quickSupportHistory });
+  console.info(`Route: ${response1.session?.currentRoute?.title}`);
+  console.info(`Response: ${response1.message}`);
+  console.info(`Expected: Short, direct, max 1 emoji\n`);
+
+  // --- Sales Consultation ---
+  console.info("2️⃣  Sales Consultation Route (conversational, value-first)");
+  const salesHistory: Event[] = [
+    {
+      kind: EventKind.MESSAGE,
+      source: EventSource.CUSTOMER,
+      data: {
+        message: "How much does your premium plan cost?",
+        participant: { display_name: "User" },
+      },
+    },
   ];
-
-  const response2 = await agent.respond({ history: history2, session });
-  console.log(`Route: ${response2.session?.currentRoute?.title}`);
-  console.log(`Response: ${response2.message}`);
-  console.log(`Expected: Ask about needs, show value before price\n`);
-
-  // Update session again
-  session = response2.session!;
-
-  // Example 3: Technical Support - Should be detailed and step-by-step
-  console.log("3️⃣  Technical Support Route (detailed, step-by-step)");
-  const history3 = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Charlie",
-      "My app keeps crashing when I try to login"
-    ),
+  const response2 = await agent.respond({ history: salesHistory });
+  console.info(`Route: ${response2.session?.currentRoute?.title}`);
+  console.info(`Response: ${response2.message}`);
+  console.info(`Expected: Ask about needs, show value before price\n`);
+
+  // --- Technical Support ---
+  console.info("3️⃣  Technical Support Route (detailed, step-by-step)");
+  const techSupportHistory: Event[] = [
+    {
+      kind: EventKind.MESSAGE,
+      source: EventSource.CUSTOMER,
+      data: {
+        message: "My new headphones won't connect to Bluetooth.",
+        participant: { display_name: "User" },
+      },
+    },
   ];
+  const response3 = await agent.respond({ history: techSupportHistory });
+  console.info(`Route: ${response3.session?.currentRoute?.title}`);
+  console.info(`Response: ${response3.message}`);
+  console.info(`Expected: Clear steps, simple language, patient\n`);
+  if (response3.isRouteComplete) {
+    console.info("\n✅ Technical support feedback collected!");
+  }
 
-  const response3 = await agent.respond({ history: history3, session });
-  console.log(`Route: ${response3.session?.currentRoute?.title}`);
-  console.log(`Response: ${response3.message}`);
-  console.log(`Expected: Clear steps, simple language, patient\n`);
-
-  // Update session again
-  session = response3.session!;
-
-  // Example 4: Emergency Support - Should be calm and action-oriented
-  console.log("4️⃣  Emergency Support Route (urgent, professional)");
-  const history4 = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Diana",
-      "This is urgent! My payment failed and I need access NOW!"
-    ),
+  // --- Emergency Support ---
+  console.info("4️⃣  Emergency Support Route (urgent, professional)");
+  const emergencyHistory: Event[] = [
+    {
+      kind: EventKind.MESSAGE,
+      source: EventSource.CUSTOMER,
+      data: {
+        message: "My account has been compromised!",
+        participant: { display_name: "User" },
+      },
+    },
   ];
-
-  const response4 = await agent.respond({ history: history4, session });
-  console.log(`Route: ${response4.session?.currentRoute?.title}`);
-  console.log(`Response: ${response4.message}`);
-  console.log(`Expected: Acknowledge urgency, no emojis, concrete steps\n`);
-
-  // Update session again
-  session = response4.session!;
-
-  // Example 5: General Chat - Should be friendly and casual
-  console.log("5️⃣  General Chat Route (friendly, casual)");
-  const history5 = [
-    createMessageEvent(EventSource.CUSTOMER, "Eve", "Hey! How's it going?"),
+  const response4 = await agent.respond({ history: emergencyHistory });
+  console.info(`Route: ${response4.session?.currentRoute?.title}`);
+  console.info(`Response: ${response4.message}`);
+  console.info(`Expected: Acknowledge urgency, no emojis, concrete steps\n`);
+
+  // --- General Chat ---
+  console.info("5️⃣  General Chat Route (friendly, casual)");
+  const generalHistory: Event[] = [
+    {
+      kind: EventKind.MESSAGE,
+      source: EventSource.CUSTOMER,
+      data: {
+        message: "What's the weather like today?",
+        participant: { display_name: "User" },
+      },
+    } as Event<MessageEventData>,
   ];
-
-  const response5 = await agent.respond({ history: history5, session });
-  console.log(`Route: ${response5.session?.currentRoute?.title}`);
-  console.log(`Response: ${response5.message}`);
-  console.log(`Expected: Friendly, emojis, mirrors customer tone\n`);
+  const response5 = await agent.respond({ history: generalHistory });
+  console.info(`Route: ${response5.session?.currentRoute?.title}`);
+  console.info(`Response: ${response5.message}`);
+  console.info(`Expected: Friendly, emojis, mirrors customer tone\n`);
 }
 
-// Inspect route configurations
-console.log("\n📋 Route Configurations:\n");
-for (const route of agent.getRoutes()) {
-  console.log(`\n🛤️  ${route.title}`);
-
+/**
+ * Inspect route configurations.
+ */
+console.info("\n📋 Route Configurations:\n");
+agent.getRoutes().forEach((route) => {
+  console.info(`\n🛤️  ${route.title}`);
   const rules = route.getRules();
+  const prohibitions = route.getProhibitions();
+
   if (rules.length > 0) {
-    console.log(`  ✅ Rules (${rules.length}):`);
-    rules.forEach((rule, i) => console.log(`     ${i + 1}. ${rule}`));
+    console.info(`  ✅ Rules (${rules.length}):`);
+    rules.forEach((rule, i) => console.info(`     ${i + 1}. ${rule}`));
   }
 
-  const prohibitions = route.getProhibitions();
   if (prohibitions.length > 0) {
-    console.log(`  ❌ Prohibitions (${prohibitions.length}):`);
+    console.info(`  ❌ Prohibitions (${prohibitions.length}):`);
     prohibitions.forEach((prohibition, i) =>
-      console.log(`     ${i + 1}. ${prohibition}`)
+      console.info(`     ${i + 1}. ${prohibition}`)
     );
   }
-}
-
-// Benefits explanation
-console.log(`
-\n💡 Benefits of Rules & Prohibitions:
-
-1️⃣  **Context-Specific Behavior**
-   - Each route can have completely different communication styles
-   - WhatsApp support: short messages
-   - Sales: engaging, story-driven
-   - Technical: detailed, step-by-step
-
-2️⃣  **Brand Consistency**
-   - Rules ensure the agent always follows brand guidelines
-   - Prohibitions prevent off-brand behavior
-   - Different routes for different contexts
-
-3️⃣  **User Experience**
-   - Emergency route: professional, no emojis
-   - General chat: friendly, casual
-   - Technical support: patient, thorough
-
-4️⃣  **Automatic Enforcement**
-   - Rules are applied in the AI prompt automatically
-   - No manual checking needed
-   - Consistent behavior across all conversations
+});
 
-5️⃣  **Easy to Update**
-   - Change rules without changing code
-   - A/B test different communication styles
-   - Iterate based on customer feedback
+/**
+ * Benefits explanation.
+ */
+console.info(`
+💡 This demo shows how rules and prohibitions, combined with routing,
+   allow a single agent to handle diverse scenarios with tailored,
+   context-appropriate behavior.
 `);
 
+/**
+ * Mock function to log support feedback.
+ * @param data - The feedback data.
+ */
+async function logSupportFeedback(
+  _context: undefined,
+  _history: Event[],
+  _session: undefined,
+  data: { feedbackRating: number; feedbackComments: string }
+) {
+  console.info("\n" + "=".repeat(60));
+  console.info("📝 Logging Support Feedback...");
+  console.info("=".repeat(60));
+  console.info("Feedback Details:", JSON.stringify(data, null, 2));
+  console.info(`   - Rating: ${data.feedbackRating}`);
+  console.info(`   - Comments: ${data.feedbackComments}`);
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  console.info("✨ Feedback logged successfully!");
+  return { success: true };
+}
+
 // Run demonstration
 if (import.meta.url === `file://${process.argv[1]}`) {
-  demonstrateRulesAndProhibitions().catch(console.error);
+  demonstrateRulesAndProhibitions().catch((err) => console.error(err));
 }
 
 export { agent };