@falai/agent 0.6.8 → 0.7.0

package/examples/redis-persistence.ts

@@ -1,9 +1,9 @@
 /**
- * Example: Using Redis for Persistence with Session State
+ * Example: Using Redis for Persistence with Session Step
  *
  * Fast, in-memory persistence perfect for:
  * - High-throughput applications
- * - Session caching with extracted data
+ * - Session caching with collected data
  * - Real-time chat applications
  * - Temporary conversation storage
  */
@@ -16,7 +16,7 @@ import {
   EventSource,
   MessageEventData,
   Event,
-  END_STATE,
+  END_ROUTE,
 } from "../src/index";
 // @ts-ignore
 import Redis from "ioredis";
@@ -86,12 +86,12 @@ async function example() {
         sessionTTL: 24 * 60 * 60, // 24 hours
         messageTTL: 7 * 24 * 60 * 60, // 7 days
       }),
-      autoSave: true, // Auto-save session state
+      autoSave: true, // Auto-save session step
       userId,
     },
   });
 
-  // Create support ticket route with data gathering
+  // Create support ticket route with data collecting
   const ticketRoute = agent.createRoute<SupportTicketData>({
     title: "Create Support Ticket",
     description: "Help user create and track support tickets",
@@ -100,7 +100,7 @@ async function example() {
       "User wants to report a problem",
       "User mentions support, help, or issue",
     ],
-    extractionSchema: {
+    schema: {
       type: "object",
       properties: {
         issue: {
@@ -127,37 +127,37 @@ async function example() {
     },
   });
 
-  // State flow
-  ticketRoute.initialState
-    .transitionTo({
-      chatState: "Ask what the issue is",
-      gather: ["issue", "category"],
+  // Step flow
+  ticketRoute.initialStep
+    .nextStep({
+      instructions: "Ask what the issue is",
+      collect: ["issue", "category"],
       skipIf: (data) => !!data.issue && !!data.category,
     })
-    .transitionTo({
-      chatState: "Ask for priority",
-      gather: ["priority"],
+    .nextStep({
+      instructions: "Ask for priority",
+      collect: ["priority"],
       skipIf: (data) => !!data.priority,
-      requiredData: ["issue", "category"],
+      requires: ["issue", "category"],
     })
-    .transitionTo({
-      chatState: "Ask for detailed description",
-      gather: ["description"],
+    .nextStep({
+      instructions: "Ask for detailed description",
+      collect: ["description"],
       skipIf: (data) => !!data.description,
-      requiredData: ["issue", "category"],
+      requires: ["issue", "category"],
     })
-    .transitionTo({
-      chatState: "Confirm and create ticket",
-      requiredData: ["issue", "category", "description"],
+    .nextStep({
+      instructions: "Confirm and create ticket",
+      requires: ["issue", "category", "description"],
     })
-    .transitionTo({ state: END_STATE });
+    .nextStep({ step: END_ROUTE });
 
   const persistence = agent.getPersistenceManager();
   if (!persistence) return;
 
-  // Create session with state support
-  const { sessionData, sessionState } =
-    await persistence.createSessionWithState<SupportTicketData>({
+  // Create session with step support
+  const { sessionData, sessionStep } =
+    await persistence.createSessionWithStep<SupportTicketData>({
       userId,
       agentName: "Support Assistant",
       initialData: {
@@ -166,13 +166,13 @@ async function example() {
     });
 
   console.log("✨ Session created in Redis:", sessionData.id);
-  console.log("📊 Initial state:", {
-    extracted: sessionState.extracted,
+  console.log("📊 Initial step:", {
+    data: sessionStep.data,
   });
 
   // Turn 1: User provides issue
   const history: Event<MessageEventData>[] = [];
-  let session = sessionState;
+  let session = sessionStep;
 
   const message1 = createMessageEvent(
     EventSource.CUSTOMER,
@@ -188,7 +188,7 @@ async function example() {
 
   console.log("\n--- Turn 1 ---");
   console.log("🤖 Agent:", response1.message);
-  console.log("📊 Extracted data:", response1.session?.extracted);
+  console.log("📊 Collected data:", response1.session?.data);
 
   // Save messages
   await persistence.saveMessage({
@@ -202,7 +202,7 @@ async function example() {
     role: "agent",
     content: response1.message,
     route: response1.session?.currentRoute?.id,
-    state: response1.session?.currentState?.id,
+    step: response1.session?.currentStep?.id,
   });
 
   session = response1.session!;
@@ -230,7 +230,7 @@ async function example() {
 
   console.log("\n--- Turn 2 ---");
   console.log("🤖 Agent:", response2.message);
-  console.log("📊 Extracted data:", response2.session?.extracted);
+  console.log("📊 Collected data:", response2.session?.data);
 
   await persistence.saveMessage({
     sessionId: sessionData.id,
@@ -246,20 +246,18 @@ async function example() {
 
   if (response2.isRouteComplete) {
     console.log("\n✅ Support ticket route complete!");
-    await fileSupportTicket(
-      agent.getExtractedData(session.id) as SupportTicketData
-    );
+    await fileSupportTicket(agent.getData(session.id) as SupportTicketData);
   }
 
-  // Load session state from Redis (demonstrates persistence)
+  // Load session step from Redis (demonstrates persistence)
   console.log("\n--- Loading Session from Redis ---");
-  const loadedSession = await persistence.loadSessionState<SupportTicketData>(
+  const loadedSession = await persistence.loadSessionStep<SupportTicketData>(
     sessionData.id
   );
 
   console.log("📥 Loaded session:", {
     currentRoute: loadedSession?.currentRoute?.title,
-    extracted: loadedSession?.extracted,
+    data: loadedSession?.data,
   });
 
   // Get messages
@@ -275,7 +273,7 @@ async function example() {
 }
 
 /**
- * Advanced Example: High-Throughput Chat with Session State
+ * Advanced Example: High-Throughput Chat with Session Step
  */
 async function highThroughputExample() {
   const redis = new Redis();
@@ -301,7 +299,7 @@ async function highThroughputExample() {
   // Simple chat route that extracts topic and sentiment
   const chatRoute = agent.createRoute<QuickChatData>({
     title: "General Chat",
-    extractionSchema: {
+    schema: {
       type: "object",
       properties: {
         topic: {
@@ -318,18 +316,18 @@ async function highThroughputExample() {
     },
   });
 
-  chatRoute.initialState
-    .transitionTo({
-      chatState: "Chat and extract topic/sentiment",
-      gather: ["topic", "sentiment"],
+  chatRoute.initialStep
+    .nextStep({
+      instructions: "Chat and extract topic/sentiment",
+      collect: ["topic", "sentiment"],
     })
-    .transitionTo({ state: END_STATE });
+    .nextStep({ step: END_ROUTE });
 
   const persistence = agent.getPersistenceManager()!;
 
   // Create session
-  const { sessionData, sessionState } =
-    await persistence.createSessionWithState<QuickChatData>({
+  const { sessionData, sessionStep } =
+    await persistence.createSessionWithStep<QuickChatData>({
       userId: "user_456",
       agentName: "Chat Bot",
     });
@@ -343,20 +341,18 @@ async function highThroughputExample() {
         "I'm loving the new features you added!"
       ),
     ],
-    session: sessionState,
+    session: sessionStep,
   });
 
   console.log("🤖 Response:", response.message);
-  console.log("📊 Extracted:", response.session?.extracted);
+  console.log("📊 Data:", response.session?.data);
 
   if (response.isRouteComplete) {
     console.log("\n✅ Chat analytics route complete!");
-    await logChatAnalytics(
-      agent.getExtractedData(sessionData.id) as QuickChatData
-    );
+    await logChatAnalytics(agent.getData(sessionData.id) as QuickChatData);
   }
 
-  console.log("💾 Session state cached in Redis!");
+  console.log("💾 Session step cached in Redis!");
 
   await redis.quit();
 }
@@ -383,7 +379,7 @@ async function sessionRecoveryExample() {
 
   const orderRoute = agent.createRoute<OrderData>({
     title: "Place Order",
-    extractionSchema: {
+    schema: {
       type: "object",
       properties: {
         productId: { type: "string" },
@@ -394,22 +390,22 @@ async function sessionRecoveryExample() {
     },
   });
 
-  orderRoute.initialState
-    .transitionTo({
-      chatState: "Ask what to order",
-      gather: ["productId", "quantity"],
+  orderRoute.initialStep
+    .nextStep({
+      instructions: "Ask what to order",
+      collect: ["productId", "quantity"],
     })
-    .transitionTo({
-      chatState: "Ask for shipping address",
-      gather: ["shippingAddress"],
+    .nextStep({
+      instructions: "Ask for shipping address",
+      collect: ["shippingAddress"],
     })
-    .transitionTo({ state: END_STATE });
+    .nextStep({ step: END_ROUTE });
 
   const persistence = agent.getPersistenceManager()!;
 
   // Start a new session
-  const { sessionData, sessionState } =
-    await persistence.createSessionWithState<OrderData>({
+  const { sessionData, sessionStep } =
+    await persistence.createSessionWithStep<OrderData>({
       userId: "user_789",
       agentName: "Order Assistant",
     });
@@ -427,23 +423,23 @@ async function sessionRecoveryExample() {
         "I want to order product ABC123, 2 units"
       ),
     ],
-    session: sessionState,
+    session: sessionStep,
   });
 
   console.log("🤖 Response:", response1.message);
-  console.log("📊 Extracted so far:", response1.session?.extracted);
+  console.log("📊 Data so far:", response1.session?.data);
 
   // --- Simulate user disconnecting and reconnecting ---
   console.log("\n--- User Reconnects ---");
 
   // Load session from Redis
-  const recoveredSession = await persistence.loadSessionState<OrderData>(
+  const recoveredSession = await persistence.loadSessionStep<OrderData>(
     sessionId
   );
 
-  console.log("📥 Recovered session state:", {
+  console.log("📥 Recovered session step:", {
     currentRoute: recoveredSession?.currentRoute?.title,
-    extracted: recoveredSession?.extracted,
+    data: recoveredSession?.data,
   });
 
   // Load message history
@@ -465,13 +461,11 @@ async function sessionRecoveryExample() {
   });
 
   console.log("🤖 Response:", response2.message);
-  console.log("📊 Final extracted data:", response2.session?.extracted);
+  console.log("📊 Final collected data:", response2.session?.data);
 
   if (response2.isRouteComplete) {
     console.log("\n✅ Order placement complete!");
-    await processOrder(
-      agent.getExtractedData(sessionId) as unknown as OrderData
-    );
+    await processOrder(agent.getData(sessionId) as unknown as OrderData);
   }
 
   console.log("✅ Order complete with recovered session!");

package/examples/route-transitions.ts

@@ -13,8 +13,8 @@ import {
   GeminiProvider,
   createMessageEvent,
   EventSource,
-  END_STATE,
-  type SessionState,
+  END_ROUTE,
+  type SessionStep,
 } from "../src/index";
 
 // Type definitions for our booking data
@@ -46,7 +46,7 @@ async function main() {
     title: "Book Hotel",
     description: "Collects hotel booking information",
     conditions: ["User wants to book a hotel"],
-    extractionSchema: {
+    schema: {
       type: "object",
       properties: {
         hotelName: { type: "string" },
@@ -56,46 +56,47 @@ async function main() {
       required: ["hotelName", "date", "guests"],
     },
     // Configure completion message at route level
-    endState: {
-      chatState: "Confirm the booking with a summary of the hotel, date, and number of guests. Be enthusiastic!",
+    endStep: {
+      instructions:
+        "Confirm the booking with a summary of the hotel, date, and number of guests. Be enthusiastic!",
     },
     // Option 1: Simple string
     onComplete: "Collect Feedback",
     // Option 2: Object with condition
     // onComplete: {
-    //   transitionTo: "Collect Feedback",
+    //   nextStep: "Collect Feedback",
     //   condition: "if booking was successful"
     // },
     // Option 3: Function with logic
     // onComplete: (session) => {
-    //   if (session.extracted?.guests && session.extracted.guests > 5) {
+    //   if (session.data?.guests && session.data.guests > 5) {
     //     return "VIP Feedback"; // Different feedback for large groups
     //   }
     //   return "Collect Feedback";
     // },
   });
 
-  const askHotel = bookingRoute.initialState.transitionTo({
-    chatState: "Ask which hotel they want to book",
-    gather: ["hotelName"],
-    skipIf: (extracted) => !!extracted.hotelName,
+  const askHotel = bookingRoute.initialStep.nextStep({
+    instructions: "Ask which hotel they want to book",
+    collect: ["hotelName"],
+    skipIf: (data) => !!data.hotelName,
   });
 
-  const askDate = askHotel.transitionTo({
-    chatState: "Ask for the booking date",
-    gather: ["date"],
-    skipIf: (extracted) => !!extracted.date,
+  const askDate = askHotel.nextStep({
+    instructions: "Ask for the booking date",
+    collect: ["date"],
+    skipIf: (data) => !!data.date,
   });
 
-  const askGuests = askDate.transitionTo({
-    chatState: "Ask for the number of guests",
-    gather: ["guests"],
-    skipIf: (extracted) => !!extracted.guests,
+  const askGuests = askDate.nextStep({
+    instructions: "Ask for the number of guests",
+    collect: ["guests"],
+    skipIf: (data) => !!data.guests,
   });
 
-  // No need to specify chatState here - using route-level endState configuration
-  askGuests.transitionTo({
-    state: END_STATE,
+  // No need to specify instructions here - using route-level endStep configuration
+  askGuests.nextStep({
+    step: END_ROUTE,
   });
 
   // Route 2: Feedback Collection
@@ -103,7 +104,7 @@ async function main() {
     title: "Collect Feedback",
     description: "Collects user feedback after booking",
     conditions: ["User wants to provide feedback"],
-    extractionSchema: {
+    schema: {
       type: "object",
       properties: {
         rating: { type: "number" },
@@ -112,31 +113,32 @@ async function main() {
       required: ["rating"],
     },
     // Configure completion message for feedback route
-    endState: {
-      chatState: "Thank the user warmly for their feedback and let them know their input is valuable",
+    endStep: {
+      instructions:
+        "Thank the user warmly for their feedback and let them know their input is valuable",
     },
   });
 
-  const askRating = feedbackRoute.initialState.transitionTo({
-    chatState: "Ask for rating from 1 to 5",
-    gather: ["rating"],
-    skipIf: (extracted) => !!extracted.rating,
+  const askRating = feedbackRoute.initialStep.nextStep({
+    instructions: "Ask for rating from 1 to 5",
+    collect: ["rating"],
+    skipIf: (data) => !!data.rating,
   });
 
-  const askComments = askRating.transitionTo({
-    chatState: "Ask for any additional comments (optional)",
-    gather: ["comments"],
+  const askComments = askRating.nextStep({
+    instructions: "Ask for any additional comments (optional)",
+    collect: ["comments"],
   });
 
-  // No need to specify chatState here - using route-level endState configuration
-  askComments.transitionTo({
-    state: END_STATE,
+  // No need to specify instructions here - using route-level endStep configuration
+  askComments.nextStep({
+    step: END_ROUTE,
   });
 
   console.log("\n=== Route Transitions Example ===\n");
 
   // Conversation 1: User provides all booking info at once
-  let session: SessionState | undefined;
+  let session: SessionStep | undefined;
   let history = [
     createMessageEvent(
       EventSource.CUSTOMER,
@@ -155,12 +157,15 @@ async function main() {
     "Pending transition?",
     response1.session?.pendingTransition?.targetRouteId
   );
-  console.log("Extracted booking data:", response1.session?.extracted);
+  console.log("Data booking data:", response1.session?.data);
 
   session = response1.session;
   history = [
     ...history,
-    { ...createMessageEvent(EventSource.AI_AGENT, "Bot", response1.message), id: "2" },
+    {
+      ...createMessageEvent(EventSource.AI_AGENT, "Bot", response1.message),
+      id: "2",
+    },
   ];
 
   // Second response - should auto-transition to a feedback route
@@ -178,7 +183,10 @@ async function main() {
   session = response2.session;
   history = [
     ...history,
-    { ...createMessageEvent(EventSource.AI_AGENT, "Bot", response2.message), id: "4" },
+    {
+      ...createMessageEvent(EventSource.AI_AGENT, "Bot", response2.message),
+      id: "4",
+    },
   ];
 
   // Third response - provide rating
@@ -195,13 +203,13 @@ async function main() {
   const response3 = await agent.respond({ history, session });
   console.log("\nBot:", response3.message);
   console.log("Current route:", response3.session?.currentRoute?.title);
-  console.log("Extracted feedback data:", response3.session?.extracted);
+  console.log("Data feedback data:", response3.session?.data);
   console.log("Route complete?", response3.isRouteComplete);
 
   console.log("\n=== Manual Transition Example ===\n");
 
-  // Demonstrate manual transition using agent.transitionToRoute()
-  let session2: SessionState | undefined;
+  // Demonstrate manual transition using agent.nextStepRoute()
+  let session2: SessionStep | undefined;
   let history2 = [
     createMessageEvent(
       EventSource.CUSTOMER,
@@ -212,14 +220,17 @@ async function main() {
 
   console.log("User:", history2[0].data.message);
 
-  const manualResponse = await agent.respond({ history: history2, session: session2 });
+  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 = agent.transitionToRoute("Collect Feedback", manualResponse.session);
+    session2 = agent.nextStepRoute("Collect Feedback", manualResponse.session);
     console.log(
       "Pending transition set:",
       session2.pendingTransition?.targetRouteId
@@ -227,13 +238,26 @@ async function main() {
 
     history2 = [
       ...history2,
-      { ...createMessageEvent(EventSource.AI_AGENT, "Bot", manualResponse.message), id: "2" },
+      {
+        ...createMessageEvent(
+          EventSource.AI_AGENT,
+          "Bot",
+          manualResponse.message
+        ),
+        id: "2",
+      },
       createMessageEvent(EventSource.CUSTOMER, "Bob", "Great!"),
     ];
 
-    const feedbackResponse = await agent.respond({ history: history2, session: session2 });
+    const feedbackResponse = await agent.respond({
+      history: history2,
+      session: session2,
+    });
     console.log("\nBot:", feedbackResponse.message);
-    console.log("Current route:", feedbackResponse.session?.currentRoute?.title);
+    console.log(
+      "Current route:",
+      feedbackResponse.session?.currentRoute?.title
+    );
   }
 
   console.log("\n=== Done ===\n");

package/examples/rules-prohibitions.ts

@@ -1,6 +1,6 @@
 /**
  * Rules & Prohibitions Example
- * Updated for v2 architecture with session state management
+ * Updated for v2 architecture with session step management
  *
  * Demonstrates how to use rules and prohibitions to control agent behavior
  * in different conversation routes (e.g., WhatsApp bot with different styles)
@@ -12,7 +12,7 @@ import {
   type MessageEventData,
   EventKind,
   EventSource,
-  END_STATE,
+  END_ROUTE,
 } from "../src";
 import { OpenAIProvider } from "../src/providers/OpenAIProvider";
 
@@ -99,26 +99,26 @@ agent.createRoute({
   ],
 });
 
-// Add a stateful feedback flow to the Technical Support route
+// Add a stepful 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.",
+techSupportRoute.initialStep
+  .nextStep({
+    instructions: "Provide step-by-step technical assistance.",
   })
-  .transitionTo({
-    chatState: "Ask for a rating of the support provided (1-5).",
-    gather: ["feedbackRating"],
+  .nextStep({
+    instructions: "Ask for a rating of the support provided (1-5).",
+    collect: ["feedbackRating"],
   })
-  .transitionTo({
-    chatState: "Ask for any additional comments.",
-    gather: ["feedbackComments"],
+  .nextStep({
+    instructions: "Ask for any additional comments.",
+    collect: ["feedbackComments"],
   })
-  .transitionTo({
-    chatState: "Thank the user for their feedback.",
+  .nextStep({
+    instructions: "Thank the user for their feedback.",
   })
-  .transitionTo({ state: END_STATE });
+  .nextStep({ step: END_ROUTE });
 
 agent.createRoute({
   title: "Emergency Support",
@@ -231,26 +231,26 @@ async function demonstrateRulesAndProhibitions() {
     ],
   });
 
-  // Add a stateful feedback flow to the Technical Support route
+  // Add a stepful 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.",
+  techSupportRoute.initialStep
+    .nextStep({
+      instructions: "Provide step-by-step technical assistance.",
     })
-    .transitionTo({
-      chatState: "Ask for a rating of the support provided (1-5).",
-      gather: ["feedbackRating"],
+    .nextStep({
+      instructions: "Ask for a rating of the support provided (1-5).",
+      collect: ["feedbackRating"],
     })
-    .transitionTo({
-      chatState: "Ask for any additional comments.",
-      gather: ["feedbackComments"],
+    .nextStep({
+      instructions: "Ask for any additional comments.",
+      collect: ["feedbackComments"],
     })
-    .transitionTo({
-      chatState: "Thank the user for their feedback.",
+    .nextStep({
+      instructions: "Thank the user for their feedback.",
     })
-    .transitionTo({ state: END_STATE });
+    .nextStep({ step: END_ROUTE });
 
   agent.createRoute({
     title: "Emergency Support",