@falai/agent 0.9.0-alpha-2 → 0.9.2

package/examples/core-concepts/basic-agent.ts

@@ -13,9 +13,10 @@
 import {
   Agent,
   GeminiProvider,
+  Tool,
+  ValidationError,
   type Term,
   type Guideline,
-  type Tool,
   type RouteOptions,
 } from "../../src/index";
 
@@ -40,98 +41,71 @@ interface LabData {
   resultsNeeded: boolean;
 }
 
-// Define tools using the new Tool interface
-const getInsuranceProviders: Tool<HealthcareContext, HealthcareData, [], string[]> = {
+// Define tools using unified Tool interface
+const getInsuranceProvidersTool: Tool<HealthcareContext, HealthcareData> = {
   id: "healthcare_insurance_providers",
   description: "Retrieves list of accepted insurance providers",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: () => {
+  handler: async (context, args) => {
     return {
-      data: ["MegaCare Insurance", "HealthFirst", "WellnessPlus"],
+      data: "Available insurance providers: MegaCare Insurance, HealthFirst, WellnessPlus",
     };
   },
 };
 
-const getAvailableSlots: Tool<
-  HealthcareContext,
-  HealthcareData,
-  [],
-  { date: string; time: string }[]
-> = {
+const getAvailableSlotsTool: Tool<HealthcareContext, HealthcareData> = {
   id: "healthcare_available_slots",
   description: "Gets available appointment slots",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: () => {
+  handler: async (context, args) => {
     return {
-      data: [
-        { date: "2025-10-20", time: "10:00 AM" },
-        { date: "2025-10-20", time: "2:00 PM" },
-        { date: "2025-10-21", time: "1:00 PM" },
-      ],
+      data: "Available slots: Oct 20 at 10:00 AM, Oct 20 at 2:00 PM, Oct 21 at 1:00 PM",
     };
   },
 };
 
-const getLabResults: Tool<
-  HealthcareContext,
-  HealthcareData,
-  [],
-  { report: string; status: string }
-> = {
+const getLabResultsTool: Tool<HealthcareContext, HealthcareData> = {
   id: "healthcare_lab_results",
   description: "Retrieves patient lab results",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: ({ context, data }) => {
+  handler: async (toolContext, args) => {
     // Tools can access collected data and context
-    if (data?.testType) {
+    if (toolContext.data?.testType) {
       return {
-        data: {
-          report: `${data.testType} results for ${context.patientName}`,
-          status: "All values within normal range",
-        },
+        data: `${toolContext.data.testType} results for ${toolContext.context.patientName}: All values within normal range`,
       };
     }
 
     return {
-      data: {
-        report: `Lab results for ${context.patientName}`,
-        status: "All values within normal range",
-      },
+      data: `Lab results for ${toolContext.context.patientName}: All values within normal range`,
     };
   },
 };
 
-const scheduleAppointment: Tool<
-  HealthcareContext,
-  HealthcareData,
-  [],
-  { confirmation: string }
-> = {
+const scheduleAppointmentTool: Tool<HealthcareContext, HealthcareData> = {
   id: "healthcare_schedule_appointment",
   description: "Schedules patient appointments",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: ({ data }) => {
+  handler: async (context, args) => {
     // Tools access collected appointment data
-    if (!data?.preferredDate || !data?.preferredTime) {
-      return { data: { confirmation: "Please provide appointment details" } };
+    if (!context.data?.preferredDate || !context.data?.preferredTime) {
+      return { data: "Please provide appointment details" };
     }
 
     return {
-      data: {
-        confirmation: `Appointment scheduled for ${data.preferredDate} at ${data.preferredTime}`,
-      },
+      data: `Appointment scheduled for ${context.data.preferredDate} at ${context.data.preferredTime}`,
     };
   },
 };
@@ -175,7 +149,7 @@ const guidelines: Guideline<HealthcareContext>[] = [
   },
 ];
 
-const routes: RouteOptions<HealthcareContext, HealthcareData>[] = [
+const routes = [
   {
     id: "route_schedule_appointment",
     title: "Schedule Appointment",
@@ -221,27 +195,13 @@ const routes: RouteOptions<HealthcareContext, HealthcareData>[] = [
         id: "schedule_appointment",
         description: "Schedule the appointment",
         prompt: "I'll schedule your appointment now.",
-        tools: [scheduleAppointment], // Use the scheduling tool
+        tools: ["healthcare_schedule_appointment"], // Reference by ID
         requires: ["preferredDate", "preferredTime"],
-        prepare: getInsuranceProviders, // Use existing tool to prepare insurance info
-        finalize: {
-          // Inline tool to handle appointment finalization
-          id: "finalize_appointment",
-          description: "Complete the appointment booking process",
-          parameters: { type: "object", properties: {} },
-          handler: ({ context, data }) => {
-            console.log(`✅ Appointment finalized for ${context.patientName}`);
-            console.log(`📅 Details: ${JSON.stringify(data, null, 2)}`);
-
-            // Could send confirmation email, update calendar, etc.
-            return {
-              data: `Appointment confirmed for ${context.patientName}`,
-            };
-          },
-        },
+        prepare: "healthcare_insurance_providers", // Reference by ID
+        finalize: "finalize_appointment", // Reference by ID - will be registered later
       },
     ],
-    tools: [getAvailableSlots], // Route-level tools available to all steps
+    tools: ["healthcare_available_slots"], // Reference by ID
   },
   {
     id: "route_check_lab_results",
@@ -260,7 +220,7 @@ const routes: RouteOptions<HealthcareContext, HealthcareData>[] = [
         tags: ["escalation"],
       },
     ],
-    tools: [getLabResults], // Route-level tools
+    tools: ["healthcare_lab_results"], // Reference by ID
   },
   {
     title: "General Healthcare Questions",
@@ -334,8 +294,87 @@ const agent = new Agent<HealthcareContext, HealthcareData>({
   // Declarative initialization
   terms,
   guidelines,
-  tools: [getInsuranceProviders], // Agent-level tools
-  routes,
+});
+
+// Demonstrate different tool registration approaches
+
+// Method 1: Register tools for ID-based reference in routes
+agent.tool.registerMany([
+  getInsuranceProvidersTool,
+  getAvailableSlotsTool,
+  getLabResultsTool,
+  scheduleAppointmentTool,
+]);
+
+// Method 2: Create and register specialized tools
+const appointmentValidator = agent.tool.createValidation({
+  id: "validate_appointment",
+  fields: ["appointmentType", "preferredDate", "preferredTime"] as const,
+  validator: async (context, data) => {
+    const errors: ValidationError[] = [];
+    if (!data.appointmentType) errors.push({ 
+      field: "appointmentType", 
+      value: data.appointmentType,
+      message: "Appointment type is required",
+      schemaPath: "appointmentType"
+    });
+    if (!data.preferredDate) errors.push({ 
+      field: "preferredDate", 
+      value: data.preferredDate,
+      message: "Preferred date is required",
+      schemaPath: "preferredDate"
+    });
+    if (!data.preferredTime) errors.push({ 
+      field: "preferredTime", 
+      value: data.preferredTime,
+      message: "Preferred time is required",
+      schemaPath: "preferredTime"
+    });
+    
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings: [],
+    };
+  },
+});
+
+// Method 3: Create data enrichment tool
+const patientDataEnricher = agent.tool.createDataEnrichment({
+  id: "enrich_patient_data",
+  fields: ["appointmentType", "symptoms"] as const,
+  enricher: async (context, data) => {
+    // Add urgency classification based on symptoms - return fields that exist in HealthcareData
+    const urgentKeywords = ["chest pain", "difficulty breathing", "severe", "emergency"];
+    const hasUrgentSymptoms = data.symptoms && urgentKeywords.some(keyword => 
+      data.symptoms!.toLowerCase().includes(keyword)
+    );
+    
+    return {
+      urgency: hasUrgentSymptoms ? "high" : "medium", // This matches the urgency field in HealthcareData
+    };
+  },
+});
+
+// Method 4: Create tool using tool.create()
+const finalizeAppointmentTool = agent.tool.create({
+  id: "finalize_appointment",
+  description: "Complete the appointment booking process",
+  parameters: { type: "object", properties: {} },
+  handler: async (context, args) => {
+    console.log(`✅ Appointment finalized for ${context.context.patientName}`);
+    console.log(`📅 Details: ${JSON.stringify(context.data, null, 2)}`);
+
+    // Could send confirmation email, update calendar, etc.
+    return {
+      data: `Appointment confirmed for ${context.context.patientName}`,
+    };
+  },
+});
+
+// Add routes after tools are registered
+routes.forEach((route: any) => {
+  agent.createRoute(route);
 });
 
 // You can still add more dynamically after construction

package/examples/core-concepts/modern-streaming-api.ts

@@ -0,0 +1,309 @@
+/**
+ * Example: Modern Streaming API
+ * 
+ * This example demonstrates the new agent.stream() method introduced in the
+ * ResponseModal refactor. The modern API provides automatic session management
+ * and a simpler interface compared to the legacy respondStream() method.
+ */
+
+import {
+  Agent,
+  AnthropicProvider,
+  OpenAIProvider,
+} from "../../src/index";
+
+// Context type for our examples
+interface UserContext {
+  userId: string;
+  preferences: {
+    language?: string;
+    verbosity: "concise" | "detailed";
+  };
+}
+
+async function basicModernStreaming() {
+  console.log("\n🚀 Example 1: Basic Modern Streaming API\n");
+
+  const provider = new AnthropicProvider({
+    apiKey: process.env.ANTHROPIC_API_KEY || "",
+    model: "claude-sonnet-4-5",
+  });
+
+  const agent = new Agent<UserContext, unknown>({
+    name: "ModernStreamingAgent",
+    description: "Demonstrates the new stream() API",
+    context: {
+      userId: "user123",
+      preferences: {
+        language: "English",
+        verbosity: "concise",
+      },
+    },
+    provider,
+  });
+
+  try {
+    console.log("📤 Using modern stream() API...\n");
+    console.log("Response: ");
+
+    // NEW: Simple streaming with automatic session management
+    for await (const chunk of agent.stream("What is machine learning?")) {
+      if (chunk.delta) {
+        process.stdout.write(chunk.delta);
+      }
+
+      if (chunk.done) {
+        console.log("\n\n✅ Stream complete!");
+        console.log(`📊 Session has ${agent.session.getHistory().length} messages`);
+        console.log("💡 Session history was automatically managed!");
+      }
+    }
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+async function streamingWithOptions() {
+  console.log("\n🚀 Example 2: Streaming with Options\n");
+
+  const provider = new OpenAIProvider({
+    apiKey: process.env.OPENAI_API_KEY || "",
+    model: "gpt-4",
+  });
+
+  const agent = new Agent<UserContext, unknown>({
+    name: "OptionsStreamingAgent",
+    description: "Demonstrates streaming with options",
+    context: {
+      userId: "user456",
+      preferences: {
+        language: "English",
+        verbosity: "detailed",
+      },
+    },
+    provider,
+  });
+
+  try {
+    console.log("📤 Streaming with context override and abort signal...\n");
+    console.log("Response: ");
+
+    // Create abort controller for cancellation
+    const abortController = new AbortController();
+    
+    // Cancel after 10 seconds
+    setTimeout(() => {
+      console.log("\n⚠️ Aborting stream...");
+      abortController.abort();
+    }, 10000);
+
+    // Stream with options
+    for await (const chunk of agent.stream("Explain quantum computing in detail", {
+      contextOverride: {
+        preferences: { verbosity: "concise" } // Override to be more concise
+      },
+      signal: abortController.signal
+    })) {
+      if (chunk.delta) {
+        process.stdout.write(chunk.delta);
+      }
+
+      if (chunk.done) {
+        console.log("\n\n✅ Stream complete!");
+        console.log("💡 Context was overridden for this response only");
+        clearTimeout();
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      console.log("\n🛑 Stream was successfully aborted!");
+    } else {
+      console.error("❌ Error:", error);
+    }
+  }
+}
+
+async function conversationFlow() {
+  console.log("\n🚀 Example 3: Multi-turn Conversation Flow\n");
+
+  const provider = new AnthropicProvider({
+    apiKey: process.env.ANTHROPIC_API_KEY || "",
+    model: "claude-sonnet-4-5",
+  });
+
+  const agent = new Agent<UserContext, unknown>({
+    name: "ConversationAgent",
+    description: "Demonstrates multi-turn conversations",
+    context: {
+      userId: "user789",
+      preferences: {
+        language: "English",
+        verbosity: "detailed",
+      },
+    },
+    provider,
+  });
+
+  const messages = [
+    "What is TypeScript?",
+    "How is it different from JavaScript?",
+    "Can you give me a simple example?",
+    "Thank you for the explanation!"
+  ];
+
+  try {
+    console.log("📤 Multi-turn conversation with automatic session management...\n");
+
+    for (let i = 0; i < messages.length; i++) {
+      console.log(`\n${"=".repeat(60)}`);
+      console.log(`💬 Turn ${i + 1}: ${messages[i]}`);
+      console.log(`${"=".repeat(60)}`);
+      console.log("Response: ");
+
+      // Each stream() call automatically manages the session
+      for await (const chunk of agent.stream(messages[i])) {
+        if (chunk.delta) {
+          process.stdout.write(chunk.delta);
+        }
+
+        if (chunk.done) {
+          console.log(`\n📊 Session now has ${agent.session.getHistory().length} messages`);
+        }
+      }
+    }
+
+    console.log("\n✅ Conversation complete!");
+    console.log("💡 All session management was handled automatically");
+    console.log(`📊 Final session has ${agent.session.getHistory().length} messages`);
+
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+async function migrationComparison() {
+  console.log("\n🚀 Example 4: Migration from respondStream() to stream()\n");
+
+  const provider = new AnthropicProvider({
+    apiKey: process.env.ANTHROPIC_API_KEY || "",
+    model: "claude-sonnet-4-5",
+  });
+
+  const agent = new Agent<UserContext, unknown>({
+    name: "MigrationAgent",
+    description: "Shows migration from old to new API",
+    context: {
+      userId: "migration-user",
+      preferences: {
+        language: "English",
+        verbosity: "concise",
+      },
+    },
+    provider,
+  });
+
+  const userMessage = "What are the benefits of TypeScript?";
+
+  try {
+    // ========================================================================
+    // OLD WAY: respondStream() - Manual session management
+    // ========================================================================
+    console.log("🔸 OLD WAY: Using respondStream() with manual session management");
+    console.log("Code: agent.respondStream({ history: agent.session.getHistory() })");
+    console.log("Response: ");
+
+    // Manual session management required
+    await agent.session.addMessage("user", userMessage);
+    
+    let oldResponse = "";
+    for await (const chunk of agent.respondStream({ 
+      history: agent.session.getHistory() 
+    })) {
+      if (chunk.delta) {
+        process.stdout.write(chunk.delta);
+        oldResponse += chunk.delta;
+      }
+
+      if (chunk.done) {
+        // Manual history update required
+        await agent.session.addMessage("assistant", oldResponse);
+        console.log("\n   ✅ Manual session update completed");
+      }
+    }
+
+    console.log("\n" + "=".repeat(60));
+
+    // ========================================================================
+    // NEW WAY: stream() - Automatic session management
+    // ========================================================================
+    console.log("🔸 NEW WAY: Using stream() with automatic session management");
+    console.log("Code: agent.stream('message')");
+    console.log("Response: ");
+
+    // Automatic session management - just pass the message!
+    for await (const chunk of agent.stream("Can you elaborate on the type safety benefits?")) {
+      if (chunk.delta) {
+        process.stdout.write(chunk.delta);
+      }
+
+      if (chunk.done) {
+        console.log("\n   ✅ Automatic session update - no manual work needed!");
+      }
+    }
+
+    console.log("\n📊 Migration Benefits:");
+    console.log("   ✅ Simpler API: agent.stream('message') vs complex parameters");
+    console.log("   ✅ Automatic session management - no manual addMessage() calls");
+    console.log("   ✅ Same performance and features as respondStream()");
+    console.log("   ✅ Backward compatibility - respondStream() still works");
+    console.log("   ✅ Consistent with chat() API patterns");
+
+    console.log(`\n📊 Final session has ${agent.session.getHistory().length} messages`);
+
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+async function main() {
+  console.log("🚀 Modern Streaming API Examples");
+  console.log("=".repeat(60));
+
+  const examples = [
+    { name: "Basic Modern Streaming", fn: basicModernStreaming },
+    { name: "Streaming with Options", fn: streamingWithOptions },
+    { name: "Multi-turn Conversation", fn: conversationFlow },
+    { name: "Migration Comparison", fn: migrationComparison },
+  ];
+
+  console.log("\nAvailable Examples:");
+  examples.forEach((ex, i) => {
+    console.log(`  ${i + 1}. ${ex.name}`);
+  });
+
+  console.log("\n💡 Key Benefits of Modern stream() API:");
+  console.log("   - Simple interface: agent.stream('message')");
+  console.log("   - Automatic session management");
+  console.log("   - No manual history updates needed");
+  console.log("   - Same performance as respondStream()");
+  console.log("   - Full backward compatibility maintained");
+
+  console.log("\n" + "=".repeat(60));
+
+  // Run examples if API key is available
+  if (process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY) {
+    await basicModernStreaming();
+    await migrationComparison();
+  } else {
+    console.log(
+      "\n⚠️  Set ANTHROPIC_API_KEY or OPENAI_API_KEY to run examples."
+    );
+  }
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}
+
+export { main };

package/examples/core-concepts/schema-driven-extraction.ts

@@ -23,22 +23,22 @@ interface UserProfileData {
   newsletterOptIn: boolean;
 }
 
-// Define a tool that uses the collected data
-const saveUserProfile: Tool<unknown, UserProfileData, [], string> = {
+// Define a tool that uses the collected data - using unified Tool interface
+const saveUserProfileTool: Tool<unknown, UserProfileData> = {
   id: "save_user_profile",
   description: "Save the collected user profile information",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: ({ data }) => {
-    console.log("Saving user profile:", data);
+  handler: async (context, args) => {
+    console.log("Saving user profile:", context.data);
 
     // Simulate saving to database
-    console.log("Profile data:", data);
+    console.log("Profile data:", context.data);
 
     return {
-      data: `Profile saved successfully! Welcome ${data?.name}!`,
+      data: `Profile saved successfully! Welcome ${context.data?.name}!`,
     };
   },
 };
@@ -99,6 +99,9 @@ const agent = new Agent<unknown, UserProfileData>({
   schema: userProfileSchema,
 });
 
+// Add tool using unified interface
+agent.addTool(saveUserProfileTool);
+
 // Create a route that collects profile information step by step
 agent.createRoute({
   title: "User Profile Collection",
@@ -163,7 +166,7 @@ agent.createRoute({
       description: "Save the collected profile",
       prompt:
         "Thanks for providing your information! Let me save your profile.",
-      tools: [saveUserProfile],
+      tools: ["save_user_profile"], // Reference by ID
       requires: ["name", "email"],
     },
   ],