@falai/agent 0.8.1 → 0.9.0-alpha-2

package/examples/{prisma-persistence.ts → persistence/database-persistence.ts}

@@ -1,20 +1,22 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access */
 /**
- * Example: Using Prisma ORM for Persistence with Session Step
+ * Example: Using Prisma ORM for Persistence with New Session Management
  *
- * This example shows how to use @falai/agent with Prisma for automatic
- * session step persistence - with the new data-driven architecture!
+ * This example demonstrates the new automatic session management features:
+ * - Automatic session creation and loading with sessionId
+ * - Built-in conversation history management
+ * - Simplified server-side usage patterns
+ * - SessionManager API for direct session control
  */
 
 import {
   Agent,
   GeminiProvider,
   PrismaAdapter,
-  createMessageEvent,
-  EventSource,
   END_ROUTE,
-} from "../src/index";
+} from "../../src";
 
-// @ts-ignore
+// @ts-expect-error - PrismaClient is not typed
 import { PrismaClient } from "@prisma/client";
 
 /**
@@ -76,41 +78,28 @@ async function example() {
   // Initialize Prisma client
   const prisma = new PrismaClient();
 
-  const userId = "user_123";
-
   /**
-   * Create Agent with Persistence - New Session-Based Pattern! ✨
+   * Server-Style Usage: Create Agent per request with sessionId
+   * This is the recommended pattern for server environments
    */
-  const agent = new Agent<ConversationContext>({
+  const sessionId = "session_user123_booking"; // Could be from request params
+
+  const agent = new Agent<ConversationContext, FlightBookingData>({
     name: "Travel Assistant",
     description: "A helpful travel booking assistant",
     goal: "Help users book flights with ease",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
-      model: "models/gemini-2.0-flash-exp",
+      model: "models/gemini-2.5-flash",
     }),
     context: {
-      userId,
+      userId: "user_123",
       userName: "Alice",
     },
-    // ✨ Just pass the adapter - that's it!
     persistence: {
-      adapter: new PrismaAdapter({ prisma }),
-      autoSave: true, // Auto-saves session step after each response
-      userId,
+      adapter: new PrismaAdapter<ConversationContext>({ prisma }),
+      autoSave: true, // Auto-saves session after each response
     },
-  });
-
-  /**
-   * Create a route with data extraction schema
-   */
-  const flightRoute = agent.createRoute<FlightBookingData>({
-    title: "Book a Flight",
-    description: "Help user book a flight ticket",
-    conditions: [
-      "User wants to book a flight",
-      "User mentions travel, flying, or booking tickets",
-    ],
     schema: {
       type: "object",
       properties: {
@@ -141,222 +130,173 @@ async function example() {
       },
       required: ["destination", "departureDate", "passengers", "cabinClass"],
     },
+    sessionId, // ✨ Agent will automatically load or create this session
+  });
+
+  /**
+   * Create a route with data extraction schema
+   */
+  const flightRoute = agent.createRoute({
+    title: "Book a Flight",
+    description: "Help user book a flight ticket",
+    conditions: [
+      "User wants to book a flight",
+      "User mentions travel, flying, or booking tickets",
+    ],
   });
 
   // Step flow with smart data collecting and custom IDs
   const askDestination = flightRoute.initialStep.nextStep({
     id: "ask_destination", // Custom step ID for easier tracking
-    instructions: "Ask where they want to fly",
+    prompt: "Ask where they want to fly",
     collect: ["destination"],
-    skipIf: (data) => !!data.destination,
+    skipIf: (data: Partial<FlightBookingData>) => !!data.destination,
   });
 
   const askDates = askDestination.nextStep({
     id: "ask_dates", // Custom step ID
-    instructions: "Ask about travel dates",
+    prompt: "Ask about travel dates",
     collect: ["departureDate", "returnDate"],
-    skipIf: (data) => !!data.departureDate,
+    skipIf: (data: Partial<FlightBookingData>) => !!data.departureDate,
     requires: ["destination"],
   });
 
   const askPassengers = askDates.nextStep({
     id: "ask_passengers", // Custom step ID
-    instructions: "Ask how many passengers",
+    prompt: "Ask how many passengers",
     collect: ["passengers"],
-    skipIf: (data) => !!data.passengers,
+    skipIf: (data: Partial<FlightBookingData>) => !!data.passengers,
     requires: ["destination", "departureDate"],
   });
 
   const askCabinClass = askPassengers.nextStep({
     id: "ask_cabin_class", // Custom step ID
-    instructions: "Ask about cabin class preference",
+    prompt: "Ask about cabin class preference",
     collect: ["cabinClass"],
-    skipIf: (data) => !!data.cabinClass,
+    skipIf: (data: Partial<FlightBookingData>) => !!data.cabinClass,
     requires: ["destination", "departureDate", "passengers"],
   });
 
   const confirmBooking = askCabinClass.nextStep({
     id: "confirm_booking", // Custom step ID
-    instructions: "Present options and confirm booking details",
+    prompt: "Present options and confirm booking details",
     requires: ["destination", "departureDate", "passengers", "cabinClass"],
   });
 
   confirmBooking.nextStep({ step: END_ROUTE });
 
   /**
-   * Get persistence manager from agent
+   * Session is automatically loaded/created by Agent constructor
+   * Access it through agent.session
    */
-  const persistence = agent.getPersistenceManager();
+  console.log("✨ Session ready:", agent.session.id);
+  console.log("📊 Session data:", agent.session.getData());
+  console.log("📜 Conversation history:", agent.session.getHistory().length, "messages");
 
-  if (!persistence) {
-    throw new Error("Persistence not configured");
+  // Set some initial data if this is a new session
+  if (!agent.session.getData()?.cabinClass) {
+    await agent.session.setData({ cabinClass: "economy" });
   }
 
   /**
-   * Create or find a session - New Pattern!
-   */
-  let sessionResult =
-    await persistence.createSessionWithStep<FlightBookingData>({
-      userId,
-      agentName: "Travel Assistant",
-      initialData: {
-        cabinClass: "economy", // Default value
-      },
-    });
-
-  let session = sessionResult.sessionStep;
-  const dbSessionId = sessionResult.sessionData.id;
-
-  console.log("✨ Created new session:", dbSessionId);
-  console.log("📊 Session metadata:", {
-    sessionId: session.metadata?.sessionId, // Same as dbSessionId
-    createdAt: session.metadata?.createdAt,
-  });
-  console.log("📊 Initial session step:", {
-    currentRoute: session.currentRoute,
-    data: session.data,
-  });
-
-  /**
-   * Load conversation history
-   */
-  const history = await persistence.loadSessionHistory(dbSessionId);
-  console.log(`📜 Loaded ${history.length} messages from history`);
-
-  /**
-   * Turn 1: User provides multiple fields at once
+   * Turn 1: Simple message-based conversation
+   * SessionManager automatically handles history and persistence
    */
   console.log("\n--- Turn 1 ---");
-  const userMessage1 = createMessageEvent(
-    EventSource.CUSTOMER,
-    "Alice",
-    "I want to fly to Paris on June 15 with 2 people"
-  );
-
-  history.push(userMessage1);
-
+  
+  // Add user message to session history and get response
+  await agent.session.addMessage("user", "I want to fly to Paris on June 15 with 2 people", "Alice");
+  
   const response1 = await agent.respond({
-    history,
-    session, // Pass session step
+    history: agent.session.getHistory(), // Use session-managed history
   });
 
   console.log("🤖 Agent:", response1.message);
-  console.log("📊 Session step after turn 1:", {
-    sessionId: response1.session?.metadata?.sessionId,
+  console.log("📊 Session after turn 1:", {
+    sessionId: agent.session.id,
     currentRoute: response1.session?.currentRoute?.title,
-    currentStepId: response1.session?.currentStep?.id, // Custom ID like "ask_destination"
-    currentStepDescription: response1.session?.currentStep?.description,
-    data: response1.session?.data,
-  });
-
-  // Save user message
-  await persistence.saveMessage({
-    sessionId: dbSessionId,
-    userId,
-    role: "user",
-    content: userMessage1.data.message,
-    event: userMessage1,
-  });
-
-  // Save agent message (session step is auto-saved by Agent!)
-  await persistence.saveMessage({
-    sessionId: dbSessionId,
-    userId,
-    role: "agent",
-    content: response1.message,
-    route: response1.session?.currentRoute?.id,
-    step: response1.session?.currentStep?.id,
+    currentStepId: response1.session?.currentStep?.id,
+    data: agent.session.getData(),
   });
 
-  // Update session for next turn
-  session = response1.session!;
+  // Add agent response to session history
+  await agent.session.addMessage("assistant", response1.message);
 
   /**
    * Turn 2: User changes their mind
    */
   console.log("\n--- Turn 2 ---");
-  const userMessage2 = createMessageEvent(
-    EventSource.CUSTOMER,
-    "Alice",
-    "Actually, make that Tokyo instead, and premium class"
-  );
-
-  history.push(
-    createMessageEvent(
-      EventSource.AI_AGENT,
-      "Travel Assistant",
-      response1.message
-    )
-  );
-  history.push(userMessage2);
+  
+  await agent.session.addMessage("user", "Actually, make that Tokyo instead, and premium class", "Alice");
 
   const response2 = await agent.respond({
-    history,
-    session, // Pass updated session
+    history: agent.session.getHistory(),
   });
 
   console.log("🤖 Agent:", response2.message);
-  console.log("📊 Session step after turn 2:", {
+  console.log("📊 Session after turn 2:", {
     currentRoute: response2.session?.currentRoute?.title,
     currentStep: response2.session?.currentStep?.id,
-    data: response2.session?.data,
-  });
-
-  // Save messages
-  await persistence.saveMessage({
-    sessionId: dbSessionId,
-    userId,
-    role: "user",
-    content: userMessage2.data.message,
-    event: userMessage2,
-  });
-
-  await persistence.saveMessage({
-    sessionId: dbSessionId,
-    userId,
-    role: "agent",
-    content: response2.message,
-    route: response2.session?.currentRoute?.id,
-    step: response2.session?.currentStep?.id,
+    data: agent.session.getData(),
   });
 
-  session = response2.session!;
+  await agent.session.addMessage("assistant", response2.message);
 
   if (response2.isRouteComplete) {
     console.log("\n✅ Flight booking complete!");
-    await sendFlightConfirmation(
-      agent.getData(session.id) as FlightBookingData
-    );
+    await sendFlightConfirmation(agent.session.getData());
   }
 
   /**
-   * Load session step from database (demonstrates persistence)
+   * Demonstrate session recovery - create new Agent instance with same sessionId
    */
-  console.log("\n--- Loading Session from Database ---");
-  const loadedSession = await persistence.loadSessionState<FlightBookingData>(
-    dbSessionId
-  );
-
-  console.log("📥 Loaded session step:", {
-    currentRoute: loadedSession?.currentRoute?.title,
-    currentStep: loadedSession?.currentStep?.id,
-    data: loadedSession?.data,
+  console.log("\n--- Session Recovery (New Agent Instance) ---");
+  
+  const newAgent = new Agent<ConversationContext, FlightBookingData>({
+    name: "Travel Assistant",
+    provider: new GeminiProvider({
+      apiKey: process.env.GEMINI_API_KEY!,
+      model: "models/gemini-2.5-flash",
+    }),
+    context: {
+      userId: "user_123",
+      userName: "Alice",
+    },
+    // NEW: Agent-level schema (same as original agent)
+    schema: {
+      type: "object",
+      properties: {
+        destination: { type: "string" },
+        departureDate: { type: "string" },
+        returnDate: { type: "string" },
+        passengers: { type: "number", minimum: 1, maximum: 9 },
+        cabinClass: { type: "string", enum: ["economy", "premium", "business", "first"] },
+      },
+      required: ["destination", "departureDate", "passengers", "cabinClass"],
+    },
+    persistence: {
+      adapter: new PrismaAdapter<ConversationContext>({ prisma }),
+    },
+    sessionId, // Same sessionId - will load existing session
   });
 
-  /**
-   * Query sessions and messages
-   */
-  const userSessions = await persistence.getUserSessions(userId);
-  console.log(`\n👤 User has ${userSessions.length} total sessions`);
-
-  const messages = await persistence.getSessionMessages(dbSessionId);
-  console.log(`💬 Session has ${messages.length} messages`);
+  console.log("📥 Recovered session:", {
+    sessionId: newAgent.session.id,
+    historyLength: newAgent.session.getHistory().length,
+    data: newAgent.session.getData(),
+  });
 
   /**
-   * Complete the session
+   * Continue conversation with recovered session
    */
-  await persistence.completeSession(dbSessionId);
-  console.log("✅ Session completed");
+  await newAgent.session.addMessage("user", "Can you confirm my booking details?");
+  
+  const confirmResponse = await newAgent.respond({
+    history: newAgent.session.getHistory(),
+  });
+  
+  console.log("🤖 Confirmation:", confirmResponse.message);
+  await newAgent.session.addMessage("assistant", confirmResponse.message);
 
   /**
    * Cleanup
@@ -365,11 +305,11 @@ async function example() {
 }
 
 /**
- * Advanced Example: Session Step with Lifecycle Hooks
+ * Advanced Example: SessionManager with History Management
  */
 async function advancedExample() {
   const prisma = new PrismaClient();
-  const userId = "user_456";
+  const sessionId = "session_user456_onboarding";
 
   interface UserContext {
     userId: string;
@@ -380,26 +320,28 @@ async function advancedExample() {
     };
   }
 
-  const agent = new Agent<UserContext>({
+  const agent = new Agent<UserContext, OnboardingData>({
     name: "Onboarding Assistant",
     description: "Help new users get started",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
-      model: "models/gemini-2.0-flash-exp",
+      model: "models/gemini-2.5-flash",
     }),
     context: {
-      userId,
+      userId: "user_456",
       userName: "Bob",
       preferences: {
         currency: "USD",
         language: "en",
       },
     },
-    // Lifecycle hooks for session step enrichment
+    // Lifecycle hooks for data enrichment
     hooks: {
-      // Enrich collected data before saving
-      onDataUpdate: async (data, previous) => {
-        console.log("🔄 Collected data updated:", { data, previous });
+      onDataUpdate: async (
+        data: Partial<OnboardingData>,
+        previous: Partial<OnboardingData>
+      ) => {
+        console.log("🔄 Data updated:", { data, previous });
 
         // Normalize phone numbers
         if (data.phoneNumber) {
@@ -411,25 +353,22 @@ async function advancedExample() {
           console.warn("⚠️ Invalid email detected");
         }
 
-        return data;
+        return data as OnboardingData;
       },
 
-      // Update context when session step changes
-      onContextUpdate: async (newContext, oldContext) => {
+      onContextUpdate: async (
+        newContext: UserContext,
+        oldContext: UserContext
+      ) => {
         console.log("🔄 Context updated:", { newContext, oldContext });
+        return Promise.resolve();
       },
     },
     persistence: {
-      adapter: new PrismaAdapter({ prisma }),
+      adapter: new PrismaAdapter<UserContext>({ prisma }),
       autoSave: true,
-      userId,
     },
-  });
-
-  // Create onboarding route
-  const onboardingRoute = agent.createRoute<OnboardingData>({
-    title: "User Onboarding",
-    description: "Collect user information for account setup",
+    sessionId,
     schema: {
       type: "object",
       properties: {
@@ -442,153 +381,159 @@ async function advancedExample() {
     },
   });
 
+  // Create onboarding route
+  const onboardingRoute = agent.createRoute({
+    title: "User Onboarding",
+    description: "Collect user information for account setup",
+  });
+
   onboardingRoute.initialStep
     .nextStep({
-      instructions: "Welcome and ask for name",
+      prompt: "Welcome and ask for name",
       collect: ["fullName"],
-      skipIf: (data) => !!data.fullName,
+      skipIf: (data: Partial<OnboardingData>) => !!data.fullName,
     })
     .nextStep({
-      instructions: "Ask for email",
+      prompt: "Ask for email",
       collect: ["email"],
-      skipIf: (data) => !!data.email,
+      skipIf: (data: Partial<OnboardingData>) => !!data.email,
     })
     .nextStep({
-      instructions: "Ask for phone number (optional)",
+      prompt: "Ask for phone number (optional)",
       collect: ["phoneNumber"],
     })
     .nextStep({
-      instructions: "Ask for country",
+      prompt: "Ask for country",
       collect: ["country"],
-      skipIf: (data) => !!data.country,
+      skipIf: (data: Partial<OnboardingData>) => !!data.country,
     })
     .nextStep({
-      instructions: "Confirm and complete onboarding",
+      prompt: "Confirm and complete onboarding",
     })
     .nextStep({ step: END_ROUTE });
 
-  const persistence = agent.getPersistenceManager()!;
-
-  // Create session with step
-  const { sessionData, sessionStep } =
-    await persistence.createSessionWithStep<OnboardingData>({
-      userId,
-      agentName: "Onboarding Assistant",
-    });
-
-  console.log("✨ Created onboarding session:", sessionData.id);
+  console.log("✨ Onboarding session ready:", agent.session.id);
 
-  // Simulate conversation
-  const history = [];
-  let session = sessionStep;
+  // Demonstrate history override for context setting
+  const contextHistory = [
+    { role: "system" as const, content: "User is starting onboarding process" },
+    { role: "user" as const, content: "I'd like to create an account" },
+  ];
 
   const response = await agent.respond({
-    history: [
-      createMessageEvent(EventSource.CUSTOMER, "Bob", "Hi, I'm new here!"),
-    ],
-    session,
+    history: contextHistory, // Override session history for this response
   });
 
   console.log("🤖 Agent:", response.message);
-  console.log("📊 Data so far:", response.session?.data);
+  console.log("📊 Data collected:", agent.session.getData());
+
+  // Add to session history for future responses
+  await agent.session.addMessage("user", "I'd like to create an account");
+  await agent.session.addMessage("assistant", response.message);
 
-  await persistence.saveMessage({
-    sessionId: sessionData.id,
-    userId,
-    role: "agent",
-    content: response.message,
+  // Continue with session-managed history
+  await agent.session.addMessage("user", "My name is Bob Johnson and email is bob@example.com");
+  
+  const response2 = await agent.respond({
+    history: agent.session.getHistory(),
   });
 
-  if (response.isRouteComplete) {
+  console.log("🤖 Agent:", response2.message);
+  console.log("📊 Normalized data:", agent.session.getData());
+  // Shows normalized phone and email
+
+  if (response2.isRouteComplete) {
     console.log("\n✅ Onboarding complete!");
-    await sendOnboardingEmail(agent.getData(sessionData.id) as OnboardingData);
+    await sendOnboardingEmail(agent.session.getData());
   }
 
-  console.log("✅ Session step automatically saved to database!");
-
   await prisma.$disconnect();
 }
 
 /**
- * Minimal Example - Quick Start
+ * Minimal Example - Server Endpoint Pattern
  */
-async function quickStart() {
+async function serverEndpointExample() {
   const prisma = new PrismaClient();
 
-  const agent = new Agent({
+  // Simulate server endpoint receiving request
+  const requestData = {
+    sessionId: "session_user789_support", // From client
+    message: "I need help, my name is John and my email is john@example.com",
+  };
+
+  // Define contact form schema
+  const contactFormSchema = {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      email: { type: "string" },
+      message: { type: "string" },
+    },
+    required: ["name", "email", "message"],
+  };
+
+  // Create agent with sessionId (loads existing or creates new)
+  const agent = new Agent<unknown, ContactFormData>({
     name: "Support Agent",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
-      model: "models/gemini-2.0-flash-exp",
+      model: "models/gemini-2.5-flash",
     }),
+    // NEW: Agent-level schema
+    schema: contactFormSchema,
     persistence: {
-      adapter: new PrismaAdapter({ prisma }),
-      userId: "user_789",
-      autoSave: true, // ✨ Automatically saves session step!
+      adapter: new PrismaAdapter<unknown>({ prisma }),
+      autoSave: true,
     },
+    sessionId: requestData.sessionId, // ✨ Automatic session management
   });
 
   // Create a simple contact form route
-  const contactRoute = agent.createRoute<ContactFormData>({
+  const contactRoute = agent.createRoute({
     title: "Contact Form",
-    schema: {
-      type: "object",
-      properties: {
-        name: { type: "string" },
-        email: { type: "string" },
-        message: { type: "string" },
-      },
-      required: ["name", "email", "message"],
-    },
   });
 
   contactRoute.initialStep
     .nextStep({
-      instructions: "Collect all information",
+      prompt: "Collect all information",
       collect: ["name", "email", "message"],
     })
     .nextStep({
-      instructions: "Confirm submission",
+      prompt: "Confirm submission",
     })
     .nextStep({ step: END_ROUTE });
 
-  const persistence = agent.getPersistenceManager()!;
-
-  // Create session with step support
-  const { sessionData, sessionStep } =
-    await persistence.createSessionWithStep<ContactFormData>({
-      userId: "user_789",
-      agentName: "Support Agent",
-    });
-
-  // Chat!
+  // Add user message and respond
+  await agent.session.addMessage("user", requestData.message);
+  
   const response = await agent.respond({
-    history: [
-      createMessageEvent(
-        EventSource.CUSTOMER,
-        "User",
-        "I need help, my name is John and my email is john@example.com"
-      ),
-    ],
-    session: sessionStep,
+    history: agent.session.getHistory(),
   });
 
-  console.log("✅ Response:", response.message);
-  console.log("📊 Data:", response.session?.data);
+  await agent.session.addMessage("assistant", response.message);
+
+  // Return response (like in a REST API)
+  const apiResponse = {
+    message: response.message,
+    sessionId: agent.session.id,
+    isComplete: response.isRouteComplete,
+    data: agent.session.getData(),
+  };
+
+  console.log("✅ API Response:", apiResponse);
 
   if (response.isRouteComplete) {
     console.log("\n✅ Contact form submitted!");
-    await logContactForm(agent.getData(sessionData.id) as ContactFormData);
+    await logContactForm(agent.session.getData());
   }
 
-  console.log("💾 Session step auto-saved to Prisma!");
-
   await prisma.$disconnect();
+  return apiResponse;
 }
 
 /**
  * Mock function to send a flight confirmation email.
- * @param data - The flight booking data.
  */
 async function sendFlightConfirmation(
   data: Partial<FlightBookingData> | undefined
@@ -606,7 +551,6 @@ async function sendFlightConfirmation(
 
 /**
  * Mock function to send an onboarding email.
- * @param data - The onboarding data.
  */
 async function sendOnboardingEmail(data: Partial<OnboardingData> | undefined) {
   console.log("\n" + "=".repeat(60));
@@ -620,7 +564,6 @@ async function sendOnboardingEmail(data: Partial<OnboardingData> | undefined) {
 
 /**
  * Mock function to log a contact form submission.
- * @param data - The contact form data.
  */
 async function logContactForm(data: Partial<ContactFormData> | undefined) {
   console.log("\n" + "=".repeat(60));
@@ -637,4 +580,4 @@ if (require.main === module) {
   example().catch(console.error);
 }
 
-export { example, advancedExample, quickStart };
+export { example, advancedExample, serverEndpointExample };