@falai/agent 0.8.1 → 0.9.0-alpha-1

package/examples/{redis-persistence.ts → persistence/redis-persistence.ts}

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access */
 /**
  * Example: Using Redis for Persistence with Session Step
  *
@@ -12,13 +13,11 @@ import {
   Agent,
   GeminiProvider,
   RedisAdapter,
-  createMessageEvent,
-  EventSource,
-  MessageEventData,
-  Event,
   END_ROUTE,
-} from "../src/index";
-// @ts-ignore
+  MessageRole,
+  type HistoryItem,
+} from "../../src";
+// @ts-expect-error - Redis is not typed
 import Redis from "ioredis";
 
 /**
@@ -60,6 +59,7 @@ interface OrderData {
 
 async function example() {
   // Initialize Redis client
+
   const redis = new Redis();
 
   const userId = "user_123";
@@ -71,7 +71,7 @@ async function example() {
     goal: "Help users resolve issues quickly",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
-      model: "models/gemini-2.0-flash-exp",
+      model: "models/gemini-2.5-flash",
     }),
     context: {
       userId,
@@ -80,7 +80,7 @@ async function example() {
     },
     // ✨ Redis adapter with custom options
     persistence: {
-      adapter: new RedisAdapter({
+      adapter: new RedisAdapter<ChatContext>({
         redis,
         keyPrefix: "support:", // Custom prefix
         sessionTTL: 24 * 60 * 60, // 24 hours
@@ -130,145 +130,145 @@ async function example() {
   // Step flow
   ticketRoute.initialStep
     .nextStep({
-      instructions: "Ask what the issue is",
+      prompt: "Ask what the issue is",
       collect: ["issue", "category"],
       skipIf: (data) => !!data.issue && !!data.category,
     })
     .nextStep({
-      instructions: "Ask for priority",
+      prompt: "Ask for priority",
       collect: ["priority"],
       skipIf: (data) => !!data.priority,
       requires: ["issue", "category"],
     })
     .nextStep({
-      instructions: "Ask for detailed description",
+      prompt: "Ask for detailed description",
       collect: ["description"],
       skipIf: (data) => !!data.description,
       requires: ["issue", "category"],
     })
     .nextStep({
-      instructions: "Confirm and create ticket",
+      prompt: "Confirm and create ticket",
       requires: ["issue", "category", "description"],
     })
     .nextStep({ step: END_ROUTE });
 
-  const persistence = agent.getPersistenceManager();
-  if (!persistence) return;
+  // Session is automatically managed by the agent with Redis persistence
+  console.log("✨ Session ready:", agent.session.id);
 
-  // Create session with step support
-  const { sessionData, sessionStep } =
-    await persistence.createSessionWithStep<SupportTicketData>({
-      userId,
-      agentName: "Support Assistant",
-      initialData: {
-        priority: "medium", // Default priority
-      },
-    });
+  // Set initial data
+  await agent.session.setData<SupportTicketData>({ priority: "medium" });
 
-  console.log("✨ Session created in Redis:", sessionData.id);
-  console.log("📊 Initial step:", {
-    data: sessionStep.data,
-  });
+  console.log("📊 Initial data:", agent.session.getData<SupportTicketData>());
 
   // Turn 1: User provides issue
-  const history: Event<MessageEventData>[] = [];
-  let session = sessionStep;
+  console.log("\n--- Turn 1 ---");
 
-  const message1 = createMessageEvent(
-    EventSource.CUSTOMER,
-    "Alice",
-    "I can't log into my account, it's a technical issue and it's urgent!"
+  await agent.session.addMessage(
+    "user",
+    "I can't log into my account, it's a technical issue and it's urgent!",
+    "Alice"
   );
-  history.push(message1);
+  const history = agent.session.getHistory();
 
   const response1 = await agent.respond({
     history,
-    session,
   });
 
-  console.log("\n--- Turn 1 ---");
   console.log("🤖 Agent:", response1.message);
-  console.log("📊 Collected data:", response1.session?.data);
 
-  // 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,
-    step: response1.session?.currentStep?.id,
-  });
-
-  session = response1.session!;
+  await agent.session.addMessage("assistant", response1.message);
+  console.log("📊 Collected data:", agent.session.getData<SupportTicketData>());
 
   // 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"
+  console.log("\n--- Turn 2 ---");
+  
+  await agent.session.addMessage(
+    "user",
+    "I keep getting 'Invalid credentials' error even though I reset my password",
+    "Alice"
   );
-  history.push(message2);
 
   const response2 = await agent.respond({
-    history,
-    session,
+    history: agent.session.getHistory(),
   });
 
-  console.log("\n--- Turn 2 ---");
   console.log("🤖 Agent:", response2.message);
-  console.log("📊 Collected data:", response2.session?.data);
+  console.log("📊 Collected data:", agent.session.getData<SupportTicketData>());
 
-  await persistence.saveMessage({
-    sessionId: sessionData.id,
-    role: "user",
-    content: message2.data.message,
-  });
-
-  await persistence.saveMessage({
-    sessionId: sessionData.id,
-    role: "agent",
-    content: response2.message,
-  });
+  await agent.session.addMessage("assistant", response2.message);
 
   if (response2.isRouteComplete) {
     console.log("\n✅ Support ticket route complete!");
-    await fileSupportTicket(agent.getData(session.id) as SupportTicketData);
+    await fileSupportTicket(agent.session.getData<SupportTicketData>() as SupportTicketData);
   }
 
-  // Load session step from Redis (demonstrates persistence)
-  console.log("\n--- Loading Session from Redis ---");
-  const loadedSession = await persistence.loadSessionState<SupportTicketData>(
-    sessionData.id
-  );
+  // Demonstrate session recovery with new agent instance
+  console.log("\n--- Session Recovery Example ---");
+  const sessionId = agent.session.id;
+  
+  const recoveredAgent = new Agent<ChatContext>({
+    name: "Support Assistant",
+    provider: new GeminiProvider({
+      apiKey: process.env.GEMINI_API_KEY!,
+      model: "models/gemini-2.5-flash",
+    }),
+    context: {
+      userId,
+      userName: "Alice",
+      chatType: "support",
+    },
+    persistence: {
+      adapter: new RedisAdapter<ChatContext>({
+        redis,
+        keyPrefix: "support:",
+        sessionTTL: 24 * 60 * 60,
+        messageTTL: 7 * 24 * 60 * 60,
+      }),
+      autoSave: true,
+    },
+    sessionId, // Same sessionId - will load existing session
+  });
 
-  console.log("📥 Loaded session:", {
-    currentRoute: loadedSession?.currentRoute?.title,
-    data: loadedSession?.data,
+  // Recreate the same route on recovered agent
+  recoveredAgent.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",
+    ],
+    schema: {
+      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"],
+    },
   });
 
-  // Get messages
-  const messages = await persistence.getSessionMessages(sessionData.id);
-  console.log(`\n💬 ${messages.length} messages in session`);
+  console.log("📥 Recovered session:", {
+    sessionId: recoveredAgent.session.id,
+    historyLength: recoveredAgent.session.getHistory().length,
+    data: recoveredAgent.session.getData<SupportTicketData>(),
+  });
 
-  // Complete session
-  await persistence.completeSession(sessionData.id);
-  console.log("✅ Session completed");
+  console.log("✅ Session recovery complete!");
 
   // Cleanup
+
   await redis.quit();
 }
 
@@ -278,15 +278,15 @@ async function example() {
 async function highThroughputExample() {
   const redis = new Redis();
 
-  const agent = new Agent({
+  const agent = new Agent<QuickChatData>({
     name: "Chat Bot",
     description: "Fast chat responses",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
-      model: "models/gemini-2.0-flash-exp",
+      model: "models/gemini-2.5-flash",
     }),
     persistence: {
-      adapter: new RedisAdapter({
+      adapter: new RedisAdapter<QuickChatData>({
         redis,
         keyPrefix: "chat:",
         sessionTTL: 60 * 60, // 1 hour for quick chats
@@ -318,41 +318,32 @@ async function highThroughputExample() {
 
   chatRoute.initialStep
     .nextStep({
-      instructions: "Chat and extract topic/sentiment",
+      prompt: "Chat and extract topic/sentiment",
       collect: ["topic", "sentiment"],
     })
     .nextStep({ step: END_ROUTE });
 
-  const persistence = agent.getPersistenceManager()!;
-
-  // Create session
-  const { sessionData, sessionStep } =
-    await persistence.createSessionWithStep<QuickChatData>({
-      userId: "user_456",
-      agentName: "Chat Bot",
-    });
+  // Session is automatically managed by the agent
+  console.log("✨ Session ready:", agent.session.id);
 
   // Quick chat interaction
+  await agent.session.addMessage("user", "I'm loving the new features you added!", "User");
+
   const response = await agent.respond({
-    history: [
-      createMessageEvent(
-        EventSource.CUSTOMER,
-        "User",
-        "I'm loving the new features you added!"
-      ),
-    ],
-    session: sessionStep,
+    history: agent.session.getHistory(),
   });
 
   console.log("🤖 Response:", response.message);
-  console.log("📊 Data:", response.session?.data);
+  console.log("📊 Data:", agent.session.getData<QuickChatData>());
+
+  await agent.session.addMessage("assistant", response.message);
 
   if (response.isRouteComplete) {
     console.log("\n✅ Chat analytics route complete!");
-    await logChatAnalytics(agent.getData(sessionData.id) as QuickChatData);
+    await logChatAnalytics(agent.session.getData<QuickChatData>() as QuickChatData);
   }
 
-  console.log("💾 Session step cached in Redis!");
+  console.log("💾 Session automatically saved to Redis!");
 
   await redis.quit();
 }
@@ -364,14 +355,14 @@ async function highThroughputExample() {
 async function sessionRecoveryExample() {
   const redis = new Redis();
 
-  const agent = new Agent({
+  const agent = new Agent<OrderData>({
     name: "Order Assistant",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
-      model: "models/gemini-2.0-flash-exp",
+      model: "models/gemini-2.5-flash",
     }),
     persistence: {
-      adapter: new RedisAdapter({ redis }),
+      adapter: new RedisAdapter<OrderData>({ redis }),
       autoSave: true,
       userId: "user_789",
     },
@@ -392,80 +383,70 @@ async function sessionRecoveryExample() {
 
   orderRoute.initialStep
     .nextStep({
-      instructions: "Ask what to order",
+      prompt: "Ask what to order",
       collect: ["productId", "quantity"],
     })
     .nextStep({
-      instructions: "Ask for shipping address",
+      prompt: "Ask for shipping address",
       collect: ["shippingAddress"],
     })
     .nextStep({ step: END_ROUTE });
 
-  const persistence = agent.getPersistenceManager()!;
-
-  // Start a new session
-  const { sessionData, sessionStep } =
-    await persistence.createSessionWithStep<OrderData>({
-      userId: "user_789",
-      agentName: "Order Assistant",
-    });
-
-  const sessionId = sessionData.id;
-
+  // Session is automatically managed by the agent
+  const sessionId = agent.session.id;
   console.log("✨ New order session:", sessionId);
 
   // First interaction
+  await agent.session.addMessage("user", "I want to order product ABC123, 2 units", "User");
+
   const response1 = await agent.respond({
-    history: [
-      createMessageEvent(
-        EventSource.CUSTOMER,
-        "User",
-        "I want to order product ABC123, 2 units"
-      ),
-    ],
-    session: sessionStep,
+    history: agent.session.getHistory(),
   });
 
   console.log("🤖 Response:", response1.message);
-  console.log("📊 Data so far:", response1.session?.data);
+  console.log("📊 Data so far:", agent.session.getData<OrderData>());
+
+  await agent.session.addMessage("assistant", response1.message);
 
   // --- 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 step:", {
-    currentRoute: recoveredSession?.currentRoute?.title,
-    data: recoveredSession?.data,
+  // Create new agent instance with same sessionId (simulates reconnection)
+  const reconnectedAgent = new Agent<OrderData>({
+    name: "Order Assistant",
+    provider: new GeminiProvider({
+      apiKey: process.env.GEMINI_API_KEY!,
+      model: "models/gemini-2.5-flash",
+    }),
+    persistence: {
+      adapter: new RedisAdapter<OrderData>({ redis }),
+      autoSave: true,
+    },
+    sessionId, // Same sessionId - will load existing session
+    routes: [orderRoute],
   });
 
-  // Load message history
-  const history = await persistence.loadSessionHistory(sessionId);
-  console.log(`📜 Loaded ${history.length} messages from history`);
+  console.log("📥 Recovered session:", {
+    sessionId: reconnectedAgent.session.id,
+    historyLength: reconnectedAgent.session.getHistory().length,
+    data: reconnectedAgent.session.getData<OrderData>(),
+  });
 
   // Continue conversation
-  history.push(
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "Ship to 123 Main St, New York"
-    )
-  );
+  await reconnectedAgent.session.addMessage("user", "Ship to 123 Main St, New York", "User");
 
-  const response2 = await agent.respond({
-    history,
-    session: recoveredSession!,
+  const response2 = await reconnectedAgent.respond({
+    history: reconnectedAgent.session.getHistory(),
   });
 
   console.log("🤖 Response:", response2.message);
-  console.log("📊 Final collected data:", response2.session?.data);
+  console.log("📊 Final collected data:", reconnectedAgent.session.getData<OrderData>());
+
+  await reconnectedAgent.session.addMessage("assistant", response2.message);
 
   if (response2.isRouteComplete) {
     console.log("\n✅ Order placement complete!");
-    await processOrder(agent.getData(sessionId) as unknown as OrderData);
+    await processOrder(reconnectedAgent.session.getData<OrderData>() as OrderData);
   }
 
   console.log("✅ Order complete with recovered session!");
@@ -475,15 +456,14 @@ async function sessionRecoveryExample() {
 
 /**
  * Mock function to file a support ticket.
- * @param data - The support ticket data.
  */
-async function fileSupportTicket(data: SupportTicketData) {
+async function fileSupportTicket(data: SupportTicketData | undefined) {
   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}`
+    `   - Filing ticket for issue: ${data?.issue} with priority: ${data?.priority}`
   );
   await new Promise((resolve) => setTimeout(resolve, 1000));
   console.log("✨ Ticket filed successfully!");
@@ -505,14 +485,13 @@ async function logChatAnalytics(data: QuickChatData) {
 
 /**
  * Mock function to process an order.
- * @param data - The order data.
  */
-async function processOrder(data: OrderData) {
+async function processOrder(data: OrderData | undefined) {
   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}`);
+  console.log(`   - Processing order for product: ${data?.productId}`);
   await new Promise((resolve) => setTimeout(resolve, 1000));
   console.log("✨ Order processed successfully!");
 }