@falai/agent 0.8.1 → 0.9.0-alpha-2

package/examples/{opensearch-persistence.ts → integrations/search-integration.ts}

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-argument */
 /**
  * Example: Using OpenSearch for Persistence with Session Step
  *
@@ -12,15 +13,15 @@ import {
   Agent,
   GeminiProvider,
   OpenSearchAdapter,
-  createMessageEvent,
-  EventSource,
-  MessageEventData,
-  Event,
   END_ROUTE,
-} from "../src/index";
-// @ts-ignore
+} from "../../src";
+
+// @ts-expect-error - Client is not typed
 import { Client } from "@opensearch-project/opensearch";
 
+const client = new Client({
+  url:{}
+})
 /**
  * Setup Steps:
  *
@@ -48,6 +49,17 @@ interface ComplaintData {
   requestedResolution?: string;
 }
 
+interface AnalyticsContext {
+  userId: string;
+  department: string;
+}
+
+interface TicketData {
+  ticketType: string;
+  priority: string;
+  tags: string[];
+}
+
 async function example() {
   // Initialize OpenSearch client
   const client = new Client({
@@ -64,7 +76,7 @@ async function example() {
   const userId = "user_123";
 
   // Create adapter
-  const adapter = new OpenSearchAdapter(client, {
+  const adapter = new OpenSearchAdapter<ConversationContext>(client, {
     indices: {
       sessions: "agent_sessions",
       messages: "agent_messages",
@@ -76,20 +88,52 @@ async function example() {
   // Initialize indices
   await adapter.initialize();
 
+  // Define complaint schema
+  const complaintSchema = {
+    type: "object",
+    properties: {
+      category: {
+        type: "string",
+        description: "Complaint category",
+      },
+      severity: {
+        type: "string",
+        enum: ["low", "medium", "high", "critical"],
+        default: "medium",
+        description: "Severity level",
+      },
+      description: {
+        type: "string",
+        description: "Detailed complaint description",
+      },
+      affectedService: {
+        type: "string",
+        description: "Which service is affected",
+      },
+      requestedResolution: {
+        type: "string",
+        description: "What resolution the customer wants",
+      },
+    },
+    required: ["category", "severity", "description"],
+  };
+
   // Create agent with OpenSearch persistence
-  const agent = new Agent<ConversationContext>({
+  const agent = new Agent<ConversationContext, ComplaintData>({
     name: "Customer Service Agent",
     description: "Handle customer complaints with full-text search",
     goal: "Resolve customer issues efficiently",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
-      model: "models/gemini-2.0-flash-exp",
+      model: "models/gemini-2.5-flash",
     }),
     context: {
       userId,
       userName: "Alice",
       department: "customer_service",
     },
+    // NEW: Agent-level schema
+    schema: complaintSchema,
     persistence: {
       adapter,
       autoSave: true, // Auto-save session step with collected data
@@ -98,7 +142,7 @@ async function example() {
   });
 
   // Create complaint handling route
-  const complaintRoute = agent.createRoute<ComplaintData>({
+  const complaintRoute = agent.createRoute({
     title: "Handle Customer Complaint",
     description: "Process and resolve customer complaints",
     conditions: [
@@ -106,155 +150,125 @@ async function example() {
       "User reports an issue or problem",
       "User is dissatisfied",
     ],
-    schema: {
-      type: "object",
-      properties: {
-        category: {
-          type: "string",
-          description: "Complaint category",
-        },
-        severity: {
-          type: "string",
-          enum: ["low", "medium", "high", "critical"],
-          default: "medium",
-          description: "Severity level",
-        },
-        description: {
-          type: "string",
-          description: "Detailed complaint description",
-        },
-        affectedService: {
-          type: "string",
-          description: "Which service is affected",
-        },
-        requestedResolution: {
-          type: "string",
-          description: "What resolution the customer wants",
-        },
-      },
-      required: ["category", "severity", "description"],
-    },
+    // NEW: Required fields for route completion
+    requiredFields: ["category", "severity", "description"],
+    // NEW: Optional fields that enhance the experience
+    optionalFields: ["affectedService", "requestedResolution"],
   });
 
   // Step flow
   complaintRoute.initialStep
     .nextStep({
-      instructions: "Understand the complaint",
+      prompt: "Understand the complaint",
       collect: ["category", "severity", "description"],
-      skipIf: (data) => !!data.description,
+      skipIf: (data: Partial<ComplaintData>) => !!data.description,
     })
     .nextStep({
-      instructions: "Identify affected service",
+      prompt: "Identify affected service",
       collect: ["affectedService"],
-      skipIf: (data) => !!data.affectedService,
+      skipIf: (data: Partial<ComplaintData>) => !!data.affectedService,
       requires: ["description"],
     })
     .nextStep({
-      instructions: "Ask for desired resolution",
+      prompt: "Ask for desired resolution",
       collect: ["requestedResolution"],
-      skipIf: (data) => !!data.requestedResolution,
+      skipIf: (data: Partial<ComplaintData>) => !!data.requestedResolution,
       requires: ["category", "description"],
     })
     .nextStep({
-      instructions: "Propose solution and close complaint",
+      prompt: "Propose solution and close complaint",
       requires: ["category", "description"],
     })
     .nextStep({ step: END_ROUTE });
 
-  const persistence = agent.getPersistenceManager();
-  if (!persistence) return;
-
-  // Create session with step
-  const { sessionData, sessionStep } =
-    await persistence.createSessionWithStep<ComplaintData>({
-      userId,
-      agentName: "Customer Service Agent",
-      initialData: {
-        severity: "medium",
-      },
-    });
-
-  console.log("✨ Session created in OpenSearch:", sessionData.id);
-
-  // Conversation flow
-  const history: Event<MessageEventData>[] = [];
-  let session = sessionStep;
+  // Session is automatically managed by the agent
+  console.log("✨ Session ready:", agent.session.id);
+  
+  // Set initial data
+  await agent.session.setData({ severity: "medium" });
 
   // Turn 1
   console.log("\n--- Turn 1 ---");
-  const message1 = createMessageEvent(
-    EventSource.CUSTOMER,
-    "Alice",
-    "I'm very upset! Your app keeps crashing when I try to make a payment. This is critical!"
+  
+  await agent.session.addMessage(
+    "user",
+    "I'm very upset! Your app keeps crashing when I try to make a payment. This is critical!",
+    "Alice"
   );
-  history.push(message1);
-
-  const response1 = await agent.respond({ history, session });
-
-  console.log("🤖 Agent:", response1.message);
-  console.log("📊 Data:", response1.session?.data);
 
-  await persistence.saveMessage({
-    sessionId: sessionData.id,
-    role: "user",
-    content: message1.data.message,
-    event: message1,
+  const response1 = await agent.respond({ 
+    history: agent.session.getHistory() 
   });
 
-  await persistence.saveMessage({
-    sessionId: sessionData.id,
-    role: "agent",
-    content: response1.message,
-    route: response1.session?.currentRoute?.id,
-    step: response1.session?.currentStep?.id,
-  });
-
-  session = response1.session!;
+  console.log("🤖 Agent:", response1.message);
+  console.log("📊 Data:", agent.session.getData());
+  
+  await agent.session.addMessage("assistant", response1.message);
 
   // Turn 2
   console.log("\n--- Turn 2 ---");
-  history.push(
-    createMessageEvent(EventSource.AI_AGENT, "Agent", response1.message)
-  );
-
-  const message2 = createMessageEvent(
-    EventSource.CUSTOMER,
-    "Alice",
-    "It's the payment service. I want a full refund and compensation!"
+  
+  await agent.session.addMessage(
+    "user",
+    "It's the payment service. I want a full refund and compensation!",
+    "Alice"
   );
-  history.push(message2);
 
-  const response2 = await agent.respond({ history, session });
+  const response2 = await agent.respond({ 
+    history: agent.session.getHistory() 
+  });
 
   console.log("🤖 Agent:", response2.message);
-  console.log("📊 Data:", response2.session?.data);
+  console.log("📊 Data:", agent.session.getData());
 
-  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✅ Complaint route complete!");
-    await createSupportTicket(agent.getData(session.id) as ComplaintData);
+    await createSupportTicket(agent.session.getData() as ComplaintData);
   }
 
-  // Load session from OpenSearch
-  console.log("\n--- Loading Session from OpenSearch ---");
-  const loadedSession = await persistence.loadSessionState<ComplaintData>(
-    sessionData.id
-  );
+  // Demonstrate session recovery with new agent instance
+  console.log("\n--- Session Recovery Example ---");
+  const sessionId = agent.session.id;
+  
+  const recoveredAgent = new Agent<ConversationContext, ComplaintData>({
+    name: "Customer Service Agent",
+    provider: new GeminiProvider({
+      apiKey: process.env.GEMINI_API_KEY!,
+      model: "models/gemini-2.5-flash",
+    }),
+    context: {
+      userId,
+      userName: "Alice",
+      department: "customer_service",
+    },
+    persistence: {
+      adapter,
+      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({
+    title: "Handle Customer Complaint",
+    description: "Process and resolve customer complaints",
+    conditions: [
+      "User has a complaint",
+      "User reports an issue or problem",
+      "User is dissatisfied",
+    ],
+    // NEW: Required fields for route completion
+    requiredFields: ["category", "severity", "description"],
+    // NEW: Optional fields
+    optionalFields: ["affectedService", "requestedResolution"],
+  });
+
+  console.log("📥 Recovered session:", {
+    sessionId: recoveredAgent.session.id,
+    historyLength: recoveredAgent.session.getHistory().length,
+    data: recoveredAgent.session.getData(),
   });
 
   // Demonstrate full-text search
@@ -292,9 +306,6 @@ async function example() {
   });
 
   console.log("📊 Session statistics:", aggResults.body.aggregations);
-
-  // Complete session
-  await persistence.completeSession(sessionData.id);
   console.log("\n✅ Session completed and indexed!");
 
   // Cleanup
@@ -313,7 +324,7 @@ async function analyticsExample() {
     auth: { username: "admin", password: "admin" },
   });
 
-  const adapter = new OpenSearchAdapter(client, {
+  const adapter = new OpenSearchAdapter<ConversationContext>(client, {
     indices: {
       sessions: "support_sessions",
       messages: "support_messages",
@@ -329,12 +340,27 @@ async function analyticsExample() {
     tags: string[];
   }
 
-  const agent = new Agent({
+  const ticketSchema = {
+    type: "object",
+    properties: {
+      ticketType: { type: "string" },
+      priority: { type: "string" },
+      tags: {
+        type: "array",
+        items: { type: "string" },
+      },
+    },
+    required: ["ticketType", "priority"],
+  };
+
+  const agent = new Agent<ConversationContext, TicketData>({
     name: "Support Analyzer",
     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: ticketSchema,
     persistence: {
       adapter,
       autoSave: true,
@@ -342,57 +368,61 @@ async function analyticsExample() {
     },
   });
 
-  const ticketRoute = agent.createRoute<TicketData>({
+  const ticketRoute = agent.createRoute({
     title: "Analyze Support Ticket",
-    schema: {
-      type: "object",
-      properties: {
-        ticketType: { type: "string" },
-        priority: { type: "string" },
-        tags: {
-          type: "array",
-          items: { type: "string" },
-        },
-      },
-      required: ["ticketType", "priority"],
-    },
+    // NEW: Required fields for route completion
+    requiredFields: ["ticketType", "priority"],
+    // NEW: Optional fields
+    optionalFields: ["tags"],
   });
 
   ticketRoute.initialStep.nextStep({
-    instructions: "Analyze and categorize ticket",
+    prompt: "Analyze and categorize ticket",
     collect: ["ticketType", "priority", "tags"],
   });
 
-  const persistence = agent.getPersistenceManager()!;
-
-  // Create multiple sessions
+  // Create multiple sessions with different agents
   for (let i = 0; i < 3; i++) {
-    const { sessionData, sessionStep } =
-      await persistence.createSessionWithStep<TicketData>({
+    const sessionAgent = new Agent<AnalyticsContext, TicketData>({
+      name: "Support Analyzer",
+      provider: new GeminiProvider({
+        apiKey: process.env.GEMINI_API_KEY!,
+        model: "models/gemini-2.5-flash",
+      }),
+      context: {
         userId: "analyst_001",
-        agentName: "Support Analyzer",
-      });
-
-    const response = await agent.respond({
-      history: [
-        createMessageEvent(
-          EventSource.CUSTOMER,
-          "User",
-          `Support ticket ${i + 1}: ${
-            ["Billing issue", "Technical problem", "Feature request"][i]
-          }`
-        ),
-      ],
-      session: sessionStep,
+        department: "support",
+      },
+      // NEW: Agent-level schema
+      schema: ticketSchema,
+      persistence: {
+        adapter: new OpenSearchAdapter<AnalyticsContext>(client),
+        autoSave: true,
+      },
     });
 
-    await persistence.saveMessage({
-      sessionId: sessionData.id,
-      role: "agent",
-      content: response.message,
+    // Create the ticket route on each agent
+    sessionAgent.createRoute({
+      title: "Analyze Support Ticket",
+      // NEW: Required fields for route completion
+      requiredFields: ["ticketType", "priority"],
+      // NEW: Optional fields
+      optionalFields: ["tags"],
     });
 
-    await persistence.completeSession(sessionData.id);
+    const ticketContent = `Support ticket ${i + 1}: ${
+      ["Billing issue", "Technical problem", "Feature request"][i]
+    }`;
+
+    await sessionAgent.session.addMessage("user", ticketContent, "User");
+
+    const response = await sessionAgent.respond({
+      history: sessionAgent.session.getHistory(),
+    });
+
+    await sessionAgent.session.addMessage("assistant", response.message);
+
+    console.log(`✅ Processed ticket ${i + 1}: ${response.message}`);
   }
 
   // Search across all sessions
@@ -412,7 +442,8 @@ async function analyticsExample() {
   console.log("\n--- Analyze Collected data ---");
   const sessions = allSessions.body.hits.hits;
 
-  sessions.forEach((hit: any) => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  sessions.forEach((hit: Record<string, any>) => {
     const collectedData = hit._source.collectedData;
     console.log(`Session ${hit._id}:`, {
       data: collectedData?.data,
@@ -437,20 +468,18 @@ async function timeSeriesExample() {
     auth: { username: "admin", password: "admin" },
   });
 
-  const adapter = new OpenSearchAdapter(client);
+  const adapter = new OpenSearchAdapter<ConversationContext>(client);
   await adapter.initialize();
 
-  const agent = new Agent({
+  new Agent<ConversationContext, unknown>({
     name: "Metrics Agent",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
-      model: "models/gemini-2.0-flash-exp",
+      model: "models/gemini-2.5-flash",
     }),
     persistence: { adapter, userId: "metrics_user" },
   });
 
-  const persistence = agent.getPersistenceManager()!;
-
   // Query sessions over time
   const timeQuery = await client.search({
     index: "agent_sessions",
@@ -480,15 +509,14 @@ async function timeSeriesExample() {
 
 /**
  * Mock function to create a support ticket.
- * @param data - The complaint data from the completed route.
  */
-async function createSupportTicket(data: ComplaintData) {
+async function createSupportTicket(data: ComplaintData | undefined) {
   console.log("\n" + "=".repeat(60));
   console.log("🎫 Creating Support Ticket...");
   console.log("=".repeat(60));
   console.log("Ticket Details:", JSON.stringify(data, null, 2));
   console.log(
-    `   - Creating ticket for category: ${data.category} with severity: ${data.severity}`
+    `   - Creating ticket for category: ${data?.category} with severity: ${data?.severity}`
   );
   await new Promise((resolve) => setTimeout(resolve, 1000));
   console.log("✨ Ticket created successfully!");