@falai/agent 1.2.7 → 2.0.0

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

@@ -1,309 +0,0 @@
-/**
- * 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

@@ -1,332 +0,0 @@
-/**
- * Schema-Driven Data Extraction Example
- *
- * This example demonstrates how to use JSON Schema to define data contracts
- * and extract structured data reliably from conversations.
- *
- * Key concepts:
- * - Schema-first data definition
- * - Type-safe data extraction
- * - Automatic validation
- * - NEW: Flexible ConditionTemplate patterns for routing and step control:
- *   - String-only conditions: "user wants to register" (AI context only)
- *   - Function-only conditions: (ctx) => ctx.data?.complete (programmatic only)
- *   - Mixed arrays: ["user provided info", (ctx) => !!ctx.data?.name] (hybrid)
- *   - Enhanced skipIf conditions for smart flow control
- */
-
-import { Agent, GeminiProvider, type Tool } from "../../src/index";
-
-// Define the data structure we want to collect
-interface UserProfileData {
-  name: string;
-  email: string;
-  age: number;
-  interests: string[];
-  preferredContact: "email" | "phone" | "sms";
-  newsletterOptIn: boolean;
-}
-
-// 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: async (context, args) => {
-    console.log("Saving user profile:", context.data);
-
-    // Simulate saving to database
-    console.log("Profile data:", context.data);
-
-    return {
-      data: `Profile saved successfully! Welcome ${context.data?.name}!`,
-    };
-  },
-};
-
-// Define the schema for data validation and extraction
-const userProfileSchema = {
-  type: "object",
-  properties: {
-    name: {
-      type: "string",
-      description: "The user's full name",
-      minLength: 2,
-      maxLength: 100,
-    },
-    email: {
-      type: "string",
-      format: "email",
-      description: "The user's email address",
-    },
-    age: {
-      type: "number",
-      description: "The user's age in years",
-      minimum: 13,
-      maximum: 120,
-    },
-    interests: {
-      type: "array",
-      items: { type: "string" },
-      description: "User's interests and hobbies",
-      minItems: 1,
-      maxItems: 10,
-    },
-    preferredContact: {
-      type: "string",
-      enum: ["email", "phone", "sms"],
-      description: "Preferred contact method",
-      default: "email",
-    },
-    newsletterOptIn: {
-      type: "boolean",
-      description: "Whether user wants to receive newsletters",
-      default: false,
-    },
-  },
-  required: ["name", "email"],
-};
-
-// Create the agent with agent-level schema
-const agent = new Agent<unknown, UserProfileData>({
-  name: "ProfileBot",
-  description:
-    "A bot that collects user profile information using schema-driven extraction",
-  provider: new GeminiProvider({
-    apiKey: process.env.GEMINI_API_KEY!,
-    model: "models/gemini-2.5-flash",
-  }),
-  // NEW: Agent-level schema definition
-  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",
-  description: "Collect comprehensive user profile information",
-  // Mixed condition: AI context + programmatic validation
-  when: [
-    "user wants to create a profile or register",
-    (ctx) => {
-      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
-      return message.includes('profile') || message.includes('register') || message.includes('sign up');
-    }
-  ],
-  // Skip if user already has a complete profile
-  skipIf: (ctx) => Boolean(ctx.data?.name && ctx.data?.email && ctx.data?.age),
-  // NEW: Required fields for route completion (instead of schema)
-  requiredFields: ["name", "email"],
-  // NEW: Optional fields that enhance the experience
-  optionalFields: ["age", "interests", "preferredContact", "newsletterOptIn"],
-  // Use sequential steps for a linear flow with smart skipIf conditions
-  steps: [
-    {
-      id: "ask_name",
-      description: "Ask for user's name",
-      prompt: "Hi! I'd like to create a profile for you. What's your name?",
-      collect: ["name"],
-      // String-only skipIf for AI context
-      skipIf: "user already provided their name",
-    },
-    {
-      id: "ask_email",
-      description: "Ask for user's email",
-      prompt: "What's your email address?",
-      collect: ["email"],
-      requires: ["name"],
-      // Function-only skipIf for programmatic logic
-      skipIf: (ctx) => !!ctx.data?.email,
-    },
-    {
-      id: "ask_age",
-      description: "Ask for user's age (optional)",
-      prompt: "How old are you? (optional)",
-      collect: ["age"],
-      requires: ["name", "email"],
-      // Mixed skipIf: AI context + programmatic check
-      skipIf: [
-        "age already collected",
-        (ctx) => ctx.data?.age !== undefined
-      ],
-    },
-    {
-      id: "ask_interests",
-      description: "Ask for user's interests (optional)",
-      prompt: "What are your interests or hobbies? (optional)",
-      collect: ["interests"],
-      requires: ["name", "email"],
-      // Mixed skipIf with complex logic
-      skipIf: [
-        "interests already provided",
-        (ctx) => !!(ctx.data?.interests && ctx.data.interests.length > 0)
-      ],
-    },
-    {
-      id: "ask_contact_preference",
-      description: "Ask for preferred contact method",
-      prompt: "What's your preferred contact method?",
-      collect: ["preferredContact"],
-      requires: ["name", "email"],
-      // Function-only skipIf
-      skipIf: (ctx) => !!ctx.data?.preferredContact,
-    },
-    {
-      id: "ask_newsletter",
-      description: "Ask about newsletter subscription",
-      prompt: "Would you like to subscribe to our newsletter?",
-      collect: ["newsletterOptIn"],
-      requires: ["name", "email"],
-      // String-only skipIf for simple cases
-      skipIf: "newsletter preference already collected",
-    },
-    {
-      id: "save_profile",
-      description: "Save the collected profile",
-      prompt:
-        "Thanks for providing your information! Let me save your profile.",
-      tools: ["save_user_profile"], // Reference by ID
-      requires: ["name", "email"],
-    },
-  ],
-});
-
-// Example conversation demonstrating schema-driven extraction
-async function demonstrateSchemaExtraction() {
-  console.log("=== Schema-Driven Data Extraction Demo ===\n");
-
-  // First message - user provides name and email
-  console.log("User: Hi, I'm John Doe and my email is john@example.com");
-  const response1 = await agent.respond({
-    history: [
-      {
-        role: "user",
-        content: "Hi, I'm John Doe and my email is john@example.com",
-        name: "John",
-      },
-    ],
-  });
-
-  console.log("Bot:", response1.message);
-  console.log(
-    "Collected data:",
-    JSON.stringify(response1.session?.data as Partial<UserProfileData>, null, 2)
-  );
-
-  // Second message - user provides more information
-  console.log(
-    "\nUser: I'm 30 years old and I like hiking, reading, and photography"
-  );
-  const response2 = await agent.respond({
-    history: [
-      {
-        role: "user",
-        content: "Hi, I'm John Doe and my email is john@example.com",
-        name: "John",
-      },
-      {
-        role: "assistant",
-        content: response1.message,
-      },
-      {
-        role: "user",
-        content: "I'm 30 years old and I like hiking, reading, and photography",
-        name: "John",
-      },
-    ],
-    session: response1.session,
-  });
-
-  console.log("Bot:", response2.message);
-  console.log(
-    "Collected data:",
-    JSON.stringify(response2.session?.data as Partial<UserProfileData>, null, 2)
-  );
-
-  // Third message - user provides contact preference and completes profile
-  console.log(
-    "\nUser: Please contact me by email and yes, I'd like the newsletter"
-  );
-  const response3 = await agent.respond({
-    history: [
-      {
-        role: "user",
-        content: "Hi, I'm John Doe and my email is john@example.com",
-        name: "John",
-      },
-      {
-        role: "assistant",
-        content: response1.message,
-      },
-      {
-        role: "user",
-        content: "I'm 30 years old and I like hiking, reading, and photography",
-        name: "John",
-      },
-      {
-        role: "assistant",
-        content: response2.message,
-      },
-      {
-        role: "user",
-        content: "Please contact me by email and yes, I'd like the newsletter",
-        name: "John",
-      },
-    ],
-    session: response2.session,
-  });
-
-  console.log("Bot:", response3.message);
-  console.log(
-    "Final collected data:",
-    JSON.stringify(response3.session?.data as Partial<UserProfileData>, null, 2)
-  );
-  console.log("Route complete:", response3.isRouteComplete);
-}
-
-// Demonstrate with a single comprehensive message
-async function demonstrateSmartSkipping() {
-  console.log("\n=== Smart Skipping Demo ===\n");
-
-  console.log("User provides everything in one message:");
-  console.log(
-    "User: I'm Sarah Johnson, sarah@email.com, 28 years old. I enjoy cooking, travel, and music. Contact me by phone and yes to newsletter."
-  );
-
-  const response = await agent.respond({
-    history: [
-      {
-        role: "user",
-        content:
-          "I'm Sarah Johnson, sarah@email.com, 28 years old. I enjoy cooking, travel, and music. Contact me by phone and yes to newsletter.",
-        name: "Sarah",
-      },
-    ],
-  });
-
-  console.log("Bot:", response.message);
-  console.log(
-    "Collected data:",
-    JSON.stringify(response.session?.data as Partial<UserProfileData>, null, 2)
-  );
-  console.log("Route complete:", response.isRouteComplete);
-}
-
-// Run the demonstrations
-async function main() {
-  try {
-    await demonstrateSchemaExtraction();
-    await demonstrateSmartSkipping();
-  } catch (error) {
-    console.error("Error:", error);
-  }
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main().catch(console.error);
-}