@falai/agent 0.4.1 → 0.5.1

package/examples/redis-persistence.ts

@@ -1,14 +1,22 @@
 /**
- * Example: Using Redis for Persistence
+ * Example: Using Redis for Persistence with Session State
  *
  * Fast, in-memory persistence perfect for:
  * - High-throughput applications
- * - Session caching
+ * - Session caching with extracted data
  * - Real-time chat applications
  * - Temporary conversation storage
  */
 
-import { Agent, GeminiProvider, RedisAdapter } from "../src/index";
+import {
+  Agent,
+  GeminiProvider,
+  RedisAdapter,
+  createMessageEvent,
+  EventSource,
+  MessageEventData,
+  Event,
+} from "../src/index";
 // @ts-ignore
 import Redis from "ioredis";
 
@@ -25,65 +33,427 @@ import Redis from "ioredis";
  * 3. Run this example
  */
 
+interface ChatContext {
+  userId: string;
+  userName: string;
+  chatType: "support" | "sales" | "general";
+}
+
+interface SupportTicketData {
+  issue: string;
+  category: "technical" | "billing" | "account" | "other";
+  priority: "low" | "medium" | "high";
+  description: string;
+}
+
 async function example() {
   // Initialize Redis client
   const redis = new Redis();
 
+  const userId = "user_123";
+
   // Create agent with Redis persistence
-  const agent = new Agent({
-    name: "Chat Assistant",
-    description: "Fast, real-time chat assistant",
+  const agent = new Agent<ChatContext>({
+    name: "Support Assistant",
+    description: "Fast, real-time support assistant",
+    goal: "Help users resolve issues quickly",
     ai: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.0-flash-exp",
     }),
+    context: {
+      userId,
+      userName: "Alice",
+      chatType: "support",
+    },
     // ✨ Redis adapter with custom options
     persistence: {
       adapter: new RedisAdapter({
         redis,
-        keyPrefix: "chat:", // Custom prefix
+        keyPrefix: "support:", // Custom prefix
         sessionTTL: 24 * 60 * 60, // 24 hours
         messageTTL: 7 * 24 * 60 * 60, // 7 days
       }),
-      autoSave: true,
-      userId: "user_123",
+      autoSave: true, // Auto-save session state
+      userId,
+    },
+  });
+
+  // Create support ticket route with data gathering
+  const ticketRoute = agent.createRoute<SupportTicketData>({
+    title: "Create Support Ticket",
+    description: "Help user create and track support tickets",
+    conditions: [
+      "User needs help with an issue",
+      "User wants to report a problem",
+      "User mentions support, help, or issue",
+    ],
+    gatherSchema: {
+      type: "object",
+      properties: {
+        issue: {
+          type: "string",
+          description: "Brief summary of the issue",
+        },
+        category: {
+          type: "string",
+          enum: ["technical", "billing", "account", "other"],
+          description: "Issue category",
+        },
+        priority: {
+          type: "string",
+          enum: ["low", "medium", "high"],
+          default: "medium",
+          description: "Issue priority",
+        },
+        description: {
+          type: "string",
+          description: "Detailed description of the issue",
+        },
+      },
+      required: ["issue", "category", "description"],
     },
   });
 
+  // State flow
+  ticketRoute.initialState
+    .transitionTo({
+      chatState: "Ask what the issue is",
+      gather: ["issue", "category"],
+      skipIf: (data) => !!data.issue && !!data.category,
+    })
+    .transitionTo({
+      chatState: "Ask for priority",
+      gather: ["priority"],
+      skipIf: (data) => !!data.priority,
+      requiredData: ["issue", "category"],
+    })
+    .transitionTo({
+      chatState: "Ask for detailed description",
+      gather: ["description"],
+      skipIf: (data) => !!data.description,
+      requiredData: ["issue", "category"],
+    })
+    .transitionTo({
+      chatState: "Confirm and create ticket",
+      requiredData: ["issue", "category", "description"],
+    });
+
   const persistence = agent.getPersistenceManager();
   if (!persistence) return;
 
-  // Create session
-  const session = await persistence.createSession({
-    userId: "user_123",
-    agentName: "Chat Assistant",
-    initialData: { chatType: "support" },
+  // Create session with state support
+  const { sessionData, sessionState } =
+    await persistence.createSessionWithState<SupportTicketData>({
+      userId,
+      agentName: "Support Assistant",
+      initialData: {
+        priority: "medium", // Default priority
+      },
+    });
+
+  console.log("✨ Session created in Redis:", sessionData.id);
+  console.log("📊 Initial state:", {
+    extracted: sessionState.extracted,
+  });
+
+  // Turn 1: User provides issue
+  const history: Event<MessageEventData>[] = [];
+  let session = sessionState;
+
+  const message1 = createMessageEvent(
+    EventSource.CUSTOMER,
+    "Alice",
+    "I can't log into my account, it's a technical issue and it's urgent!"
+  );
+  history.push(message1);
+
+  const response1 = await agent.respond({
+    history,
+    session,
+  });
+
+  console.log("\n--- Turn 1 ---");
+  console.log("🤖 Agent:", response1.message);
+  console.log("📊 Extracted data:", response1.session?.extracted);
+
+  // Save messages
+  await persistence.saveMessage({
+    sessionId: sessionData.id,
+    role: "user",
+    content: message1.data.message,
+  });
+
+  await persistence.saveMessage({
+    sessionId: sessionData.id,
+    role: "agent",
+    content: response1.message,
+    route: response1.session?.currentRoute?.id,
+    state: response1.session?.currentState?.id,
+  });
+
+  session = response1.session!;
+
+  // Turn 2: Provide more details
+  history.push(
+    createMessageEvent(
+      EventSource.AI_AGENT,
+      "Support Assistant",
+      response1.message
+    )
+  );
+
+  const message2 = createMessageEvent(
+    EventSource.CUSTOMER,
+    "Alice",
+    "I keep getting 'Invalid credentials' error even though I reset my password"
+  );
+  history.push(message2);
+
+  const response2 = await agent.respond({
+    history,
+    session,
   });
 
-  console.log("✨ Session created in Redis:", session.id);
+  console.log("\n--- Turn 2 ---");
+  console.log("🤖 Agent:", response2.message);
+  console.log("📊 Extracted data:", response2.session?.extracted);
 
-  // Save a message
   await persistence.saveMessage({
-    sessionId: session.id,
+    sessionId: sessionData.id,
     role: "user",
-    content: "Hello! I need help",
+    content: message2.data.message,
+  });
+
+  await persistence.saveMessage({
+    sessionId: sessionData.id,
+    role: "agent",
+    content: response2.message,
   });
 
-  // Load messages
-  const messages = await persistence.getSessionMessages(session.id);
-  console.log(`💬 ${messages.length} messages in session`);
+  // Load session state from Redis (demonstrates persistence)
+  console.log("\n--- Loading Session from Redis ---");
+  const loadedSession = await persistence.loadSessionState<SupportTicketData>(
+    sessionData.id
+  );
+
+  console.log("📥 Loaded session:", {
+    currentRoute: loadedSession?.currentRoute?.title,
+    extracted: loadedSession?.extracted,
+  });
+
+  // Get messages
+  const messages = await persistence.getSessionMessages(sessionData.id);
+  console.log(`\n💬 ${messages.length} messages in session`);
 
   // Complete session
-  await persistence.completeSession(session.id);
+  await persistence.completeSession(sessionData.id);
   console.log("✅ Session completed");
 
   // Cleanup
   await redis.quit();
 }
 
+/**
+ * Advanced Example: High-Throughput Chat with Session State
+ */
+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",
+    ai: new GeminiProvider({
+      apiKey: process.env.GEMINI_API_KEY!,
+      model: "models/gemini-2.0-flash-exp",
+    }),
+    persistence: {
+      adapter: new RedisAdapter({
+        redis,
+        keyPrefix: "chat:",
+        sessionTTL: 60 * 60, // 1 hour for quick chats
+      }),
+      autoSave: true,
+      userId: "user_456",
+    },
+  });
+
+  // Simple chat route that extracts topic and sentiment
+  const chatRoute = agent.createRoute<QuickChatData>({
+    title: "General Chat",
+    gatherSchema: {
+      type: "object",
+      properties: {
+        topic: {
+          type: "string",
+          description: "Main topic of conversation",
+        },
+        sentiment: {
+          type: "string",
+          enum: ["positive", "neutral", "negative"],
+          description: "User's sentiment",
+        },
+      },
+      required: ["topic", "sentiment"],
+    },
+  });
+
+  chatRoute.initialState.transitionTo({
+    chatState: "Chat and extract topic/sentiment",
+    gather: ["topic", "sentiment"],
+  });
+
+  const persistence = agent.getPersistenceManager()!;
+
+  // Create session
+  const { sessionData, sessionState } =
+    await persistence.createSessionWithState<QuickChatData>({
+      userId: "user_456",
+      agentName: "Chat Bot",
+    });
+
+  // Quick chat interaction
+  const response = await agent.respond({
+    history: [
+      createMessageEvent(
+        EventSource.CUSTOMER,
+        "User",
+        "I'm loving the new features you added!"
+      ),
+    ],
+    session: sessionState,
+  });
+
+  console.log("🤖 Response:", response.message);
+  console.log("📊 Extracted:", response.session?.extracted);
+  console.log("💾 Session state cached in Redis!");
+
+  await redis.quit();
+}
+
+/**
+ * Session Recovery Example
+ * Shows how to resume conversations from Redis
+ */
+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({
+      apiKey: process.env.GEMINI_API_KEY!,
+      model: "models/gemini-2.0-flash-exp",
+    }),
+    persistence: {
+      adapter: new RedisAdapter({ redis }),
+      autoSave: true,
+      userId: "user_789",
+    },
+  });
+
+  const orderRoute = agent.createRoute<OrderData>({
+    title: "Place Order",
+    gatherSchema: {
+      type: "object",
+      properties: {
+        productId: { type: "string" },
+        quantity: { type: "number", minimum: 1 },
+        shippingAddress: { type: "string" },
+      },
+      required: ["productId", "quantity", "shippingAddress"],
+    },
+  });
+
+  orderRoute.initialState
+    .transitionTo({
+      chatState: "Ask what to order",
+      gather: ["productId", "quantity"],
+    })
+    .transitionTo({
+      chatState: "Ask for shipping address",
+      gather: ["shippingAddress"],
+    });
+
+  const persistence = agent.getPersistenceManager()!;
+
+  // Start a new session
+  const { sessionData, sessionState } =
+    await persistence.createSessionWithState<OrderData>({
+      userId: "user_789",
+      agentName: "Order Assistant",
+    });
+
+  const sessionId = sessionData.id;
+
+  console.log("✨ New order session:", sessionId);
+
+  // First interaction
+  const response1 = await agent.respond({
+    history: [
+      createMessageEvent(
+        EventSource.CUSTOMER,
+        "User",
+        "I want to order product ABC123, 2 units"
+      ),
+    ],
+    session: sessionState,
+  });
+
+  console.log("🤖 Response:", response1.message);
+  console.log("📊 Extracted so far:", response1.session?.extracted);
+
+  // --- Simulate user disconnecting and reconnecting ---
+  console.log("\n--- User Reconnects ---");
+
+  // Load session from Redis
+  const recoveredSession = await persistence.loadSessionState<OrderData>(
+    sessionId
+  );
+
+  console.log("📥 Recovered session state:", {
+    currentRoute: recoveredSession?.currentRoute?.title,
+    extracted: recoveredSession?.extracted,
+  });
+
+  // Load message history
+  const history = await persistence.loadSessionHistory(sessionId);
+  console.log(`📜 Loaded ${history.length} messages from history`);
+
+  // Continue conversation
+  history.push(
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "User",
+      "Ship to 123 Main St, New York"
+    )
+  );
+
+  const response2 = await agent.respond({
+    history,
+    session: recoveredSession!,
+  });
+
+  console.log("🤖 Response:", response2.message);
+  console.log("📊 Final extracted data:", response2.session?.extracted);
+  console.log("✅ Order complete with recovered session!");
+
+  await redis.quit();
+}
+
 // Run the example
 if (require.main === module) {
   example().catch(console.error);
 }
 
-export { example };
+export { example, highThroughputExample, sessionRecoveryExample };

package/examples/rules-prohibitions.ts

@@ -1,11 +1,17 @@
 /**
  * Rules & Prohibitions Example
+ * Updated for v2 architecture with session state management
  *
  * Demonstrates how to use rules and prohibitions to control agent behavior
  * in different conversation routes (e.g., WhatsApp bot with different styles)
  */
 
-import { Agent, createMessageEvent, EventSource } from "../src/index";
+import {
+  Agent,
+  createMessageEvent,
+  EventSource,
+  createSession,
+} from "../src/index";
 import { AnthropicProvider } from "../src/providers";
 
 // Initialize AI provider
@@ -137,11 +143,17 @@ async function demonstrateRulesAndProhibitions() {
     ),
   ];
 
-  const response1 = await agent.respond({ history: history1 });
-  console.log(`Route: ${response1.route?.title}`);
+  // 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 = [
@@ -152,11 +164,14 @@ async function demonstrateRulesAndProhibitions() {
     ),
   ];
 
-  const response2 = await agent.respond({ history: history2 });
-  console.log(`Route: ${response2.route?.title}`);
+  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 = [
@@ -167,11 +182,14 @@ async function demonstrateRulesAndProhibitions() {
     ),
   ];
 
-  const response3 = await agent.respond({ history: history3 });
-  console.log(`Route: ${response3.route?.title}`);
+  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 = [
@@ -182,19 +200,22 @@ async function demonstrateRulesAndProhibitions() {
     ),
   ];
 
-  const response4 = await agent.respond({ history: history4 });
-  console.log(`Route: ${response4.route?.title}`);
+  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 response5 = await agent.respond({ history: history5 });
-  console.log(`Route: ${response5.route?.title}`);
+  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`);
 }