@falai/agent 0.9.2 → 1.0.0

package/docs/guides/migration/flexible-routing-conditions.md

@@ -0,0 +1,375 @@
+# Migration Guide: Flexible Routing Conditions
+
+This guide helps you migrate from the previous routing condition system to the new `ConditionTemplate` system introduced in version X.X.X.
+
+## Overview of Changes
+
+The routing system has been enhanced with a new `ConditionTemplate` type that supports:
+
+- **String conditions**: AI context for routing decisions
+- **Function conditions**: Programmatic boolean evaluation  
+- **Array conditions**: Mix of strings and functions with logical operators
+- **Route skipIf**: New functionality to exclude routes dynamically
+- **Enhanced Step conditions**: More flexible step control
+
+## Breaking Changes
+
+### 1. Route Conditions → Route When
+
+**Before:**
+```typescript
+agent.createRoute({
+  title: "Customer Support",
+  conditions: ["User needs help", "User asks questions"],
+  // ...
+});
+```
+
+**After:**
+```typescript
+agent.createRoute({
+  title: "Customer Support", 
+  when: ["User needs help", "User asks questions"], // Renamed from 'conditions'
+  // ...
+});
+```
+
+**Migration:** Simply rename `conditions` to `when` in all route definitions.
+
+### 2. Step When Conditions
+
+**Before:**
+```typescript
+// String-based when condition
+step.nextStep({
+  when: "User wants to continue",
+  prompt: "Let's continue..."
+});
+
+// Function-based when condition (returned string)
+step.nextStep({
+  when: (ctx) => ctx.data?.readyToContinue ? "Ready to proceed" : null,
+  prompt: "Let's continue..."
+});
+```
+
+**After:**
+```typescript
+// String-based when condition (unchanged)
+step.nextStep({
+  when: "User wants to continue",
+  prompt: "Let's continue..."
+});
+
+// Function-based when condition (now returns boolean)
+step.nextStep({
+  when: (ctx) => ctx.data?.readyToContinue === true, // Returns boolean
+  prompt: "Let's continue..."
+});
+
+// Mixed array condition (new capability)
+step.nextStep({
+  when: [
+    "User is ready to proceed", // AI context
+    (ctx) => ctx.data?.readyToContinue === true // Programmatic check
+  ],
+  prompt: "Let's continue..."
+});
+```
+
+**Migration:** Update function-based `when` conditions to return boolean instead of string.
+
+### 3. Step SkipIf Conditions
+
+**Before:**
+```typescript
+step.nextStep({
+  skipIf: (data) => data.alreadyCompleted === true, // Function only
+  prompt: "Complete this step"
+});
+```
+
+**After:**
+```typescript
+// Function-only skipIf (unchanged signature, but now uses full context)
+step.nextStep({
+  skipIf: (ctx) => ctx.data?.alreadyCompleted === true, // Full context access
+  prompt: "Complete this step"
+});
+
+// String-only skipIf (new capability)
+step.nextStep({
+  skipIf: "Step already completed",
+  prompt: "Complete this step"
+});
+
+// Mixed array skipIf (new capability)
+step.nextStep({
+  skipIf: [
+    "Step already completed", // AI context
+    (ctx) => ctx.data?.alreadyCompleted === true // Programmatic check
+  ],
+  prompt: "Complete this step"
+});
+```
+
+**Migration:** Update `skipIf` functions to use full `TemplateContext` instead of just data.
+
+### 4. Guideline Conditions
+
+**Before:**
+```typescript
+agent.addGuideline({
+  condition: "User seems frustrated", // Template type
+  action: "Be extra helpful"
+});
+
+agent.addGuideline({
+  condition: (ctx) => `User type is ${ctx.userType}`, // Function returning string
+  action: "Adjust tone accordingly"
+});
+```
+
+**After:**
+```typescript
+// String condition (unchanged)
+agent.addGuideline({
+  condition: "User seems frustrated",
+  action: "Be extra helpful"
+});
+
+// Function condition (now returns boolean)
+agent.addGuideline({
+  condition: (ctx) => ctx.data?.userType === 'premium', // Returns boolean
+  action: "Provide premium support"
+});
+
+// Mixed array condition (new capability)
+agent.addGuideline({
+  condition: [
+    "User needs special assistance", // AI context
+    (ctx) => ctx.data?.userType === 'premium' // Programmatic check
+  ],
+  action: "Provide premium support with priority handling"
+});
+```
+
+**Migration:** Update function-based guideline conditions to return boolean instead of string.
+
+## New Features
+
+### Route SkipIf
+
+Routes can now be excluded from consideration:
+
+```typescript
+agent.createRoute({
+  title: "Premium Features",
+  when: ["User wants premium features"],
+  skipIf: [
+    "Premium features are under maintenance", // AI context
+    (ctx) => ctx.context?.maintenanceMode === true // Programmatic check
+  ],
+  // ...
+});
+```
+
+### Enhanced Context Access
+
+All condition functions now receive full `TemplateContext`:
+
+```typescript
+interface TemplateContext<TContext, TData> {
+  context?: TContext;     // Agent context
+  session?: SessionState<TData>; // Session state
+  history?: Event[];      // Conversation history
+  data?: Partial<TData>;  // Convenience alias for session.data
+}
+
+// Use in conditions
+const condition = (ctx) => {
+  return ctx.context?.userTier === 'premium' && 
+         ctx.data?.issueType === 'billing' &&
+         ctx.session?.currentRoute?.id !== 'billing_route';
+};
+```
+
+## Migration Steps
+
+### Step 1: Update Route Definitions
+
+```typescript
+// Before
+const routes = [
+  {
+    title: "Support",
+    conditions: ["User needs help"],
+    // ...
+  }
+];
+
+// After  
+const routes = [
+  {
+    title: "Support", 
+    when: ["User needs help"], // Renamed
+    // ...
+  }
+];
+```
+
+### Step 2: Update Function-Based Conditions
+
+```typescript
+// Before - functions returned strings
+when: (ctx) => ctx.data?.ready ? "User is ready" : null,
+skipIf: (data) => data.completed === true,
+
+// After - functions return booleans
+when: (ctx) => ctx.data?.ready === true,
+skipIf: (ctx) => ctx.data?.completed === true,
+```
+
+### Step 3: Update Guideline Conditions
+
+```typescript
+// Before
+guidelines: [
+  {
+    condition: (ctx) => `User is ${ctx.userType}`,
+    action: "Adjust tone"
+  }
+]
+
+// After
+guidelines: [
+  {
+    condition: (ctx) => ctx.data?.userType === 'premium',
+    action: "Provide premium tone and service"
+  }
+]
+```
+
+### Step 4: Leverage New Capabilities
+
+```typescript
+// Add Route skipIf where appropriate
+agent.createRoute({
+  title: "Payment Processing",
+  when: ["User wants to make payment"],
+  skipIf: [
+    "Payment system is down", // AI context
+    (ctx) => ctx.context?.paymentSystemDown === true // Programmatic
+  ]
+});
+
+// Use mixed array conditions for complex logic
+step.nextStep({
+  when: [
+    "User is ready for advanced features", // AI context
+    (ctx) => ctx.data?.experienceLevel === 'advanced', // Programmatic
+    (ctx) => ctx.context?.featuresEnabled === true // Context check
+  ],
+  prompt: "Let's explore advanced features"
+});
+```
+
+## Testing Your Migration
+
+### 1. Verify Route Selection
+
+Test that routes are selected correctly with new `when` conditions:
+
+```typescript
+// Test route selection
+const response = await agent.respond("I need help with billing");
+expect(response.session?.currentRoute?.title).toBe("Billing Support");
+```
+
+### 2. Test SkipIf Logic
+
+Verify that routes and steps are properly skipped:
+
+```typescript
+// Test route skipIf
+const contextWithMaintenance = { maintenanceMode: true };
+const response = await agent.respond("I want premium features", {
+  contextOverride: contextWithMaintenance
+});
+// Should not select premium route due to skipIf
+```
+
+### 3. Validate Guideline Activation
+
+Test that guidelines activate correctly with new conditions:
+
+```typescript
+// Test guideline conditions
+const premiumContext = { userType: 'premium' };
+const response = await agent.respond("I need help", {
+  contextOverride: premiumContext  
+});
+// Should apply premium guidelines
+```
+
+## Common Issues
+
+### Issue 1: Function Conditions Not Working
+
+**Problem:** Function conditions that previously returned strings now need to return booleans.
+
+**Solution:**
+```typescript
+// Wrong
+when: (ctx) => ctx.data?.ready ? "User is ready" : null,
+
+// Correct  
+when: (ctx) => ctx.data?.ready === true,
+```
+
+### Issue 2: SkipIf Context Access
+
+**Problem:** `skipIf` functions now receive full context instead of just data.
+
+**Solution:**
+```typescript
+// Wrong
+skipIf: (data) => data.completed,
+
+// Correct
+skipIf: (ctx) => ctx.data?.completed === true,
+```
+
+### Issue 3: Guideline Condition Types
+
+**Problem:** Guideline conditions that returned strings need to return booleans.
+
+**Solution:**
+```typescript
+// Wrong
+condition: (ctx) => `User is ${ctx.userType}`,
+
+// Correct
+condition: (ctx) => ctx.data?.userType === 'premium',
+```
+
+## Benefits of Migration
+
+After migration, you'll have access to:
+
+- **Hybrid Logic**: Combine AI understanding with programmatic precision
+- **Better Performance**: Functions execute first, strings only used when needed  
+- **Route Exclusion**: Use `skipIf` to dynamically exclude routes
+- **Enhanced Context**: Access full context in all condition functions
+- **Flexible Arrays**: Mix strings and functions for optimal control
+
+## Support
+
+If you encounter issues during migration:
+
+1. Check the [API Reference](../../api/README.md) for updated interfaces
+2. Review [examples](../../../examples/) for migration patterns
+3. Test incrementally - migrate one route at a time
+4. Use TypeScript for compile-time validation of new signatures
+
+The new `ConditionTemplate` system provides much more flexibility while maintaining backward compatibility where possible.

package/docs/guides/migration/multi-step-execution.md

@@ -0,0 +1,303 @@
+# Multi-Step Execution Migration Guide
+
+This guide covers the behavioral changes from single-step to multi-step execution and provides migration guidance for existing routes.
+
+## Overview
+
+Multi-step execution is a **major behavioral change** that allows multiple consecutive steps to execute in a single LLM call. While the public API shape remains compatible, the execution semantics differ from the previous single-step model.
+
+## Key Behavioral Changes
+
+### Before: Single-Step Execution
+
+Previously, each `.respond()` call executed exactly one step:
+
+```typescript
+// Turn 1
+const response1 = await agent.respond("Book Grand Hotel for 2 on Friday");
+// Executes: ask-hotel step
+// Response: "What date would you like to book?"
+
+// Turn 2
+const response2 = await agent.respond("Friday");
+// Executes: ask-date step
+// Response: "How many guests?"
+
+// Turn 3
+const response3 = await agent.respond("2 people");
+// Executes: ask-guests step
+// Response: "Booking confirmed!"
+
+// Total: 3 LLM calls
+```
+
+### After: Multi-Step Execution
+
+Now, multiple steps can execute in a single call when data requirements are satisfied:
+
+```typescript
+// Turn 1
+const response = await agent.respond("Book Grand Hotel for 2 on Friday");
+// Pre-extraction captures: { hotel: "Grand Hotel", date: "Friday", guests: 2 }
+// Executes: ask-hotel, ask-date, ask-guests steps (all in one batch)
+// Response: "Booking confirmed for 2 guests at Grand Hotel on Friday!"
+
+// Total: 1 LLM call
+```
+
+## What Changed
+
+| Aspect | Before | After |
+|--------|--------|-------|
+| Steps per call | Always 1 | 1 or more (batched) |
+| LLM calls | One per step | One per batch |
+| Pre-extraction | Per-step | Before batch determination |
+| Response fields | Basic | Includes `executedSteps`, `stoppedReason` |
+| Hook execution | Per-step | All prepare hooks, then LLM, then all finalize hooks |
+
+## Migration Checklist
+
+### 1. Review Hook Dependencies
+
+If your hooks depend on being called between steps, they may need adjustment:
+
+```typescript
+// Before: Hooks called between each step
+const step1 = {
+  finalize: async (ctx, data) => {
+    // This ran before step2's prepare
+    await saveProgress(data);
+  }
+};
+
+const step2 = {
+  prepare: async (ctx, data) => {
+    // This expected step1's finalize to have run
+    const progress = await loadProgress();
+  }
+};
+
+// After: All prepare hooks run first, then all finalize hooks
+// If step1 and step2 are batched together:
+// 1. step1.prepare runs
+// 2. step2.prepare runs
+// 3. LLM call
+// 4. step1.finalize runs
+// 5. step2.finalize runs
+
+// Migration: Use session data instead of external state
+const step1 = {
+  finalize: async (ctx, data) => {
+    // Store in session data, not external state
+    data.step1Complete = true;
+  }
+};
+
+const step2 = {
+  prepare: async (ctx, data) => {
+    // Check session data
+    if (!data.step1Complete) {
+      // Handle case where step1 hasn't finalized yet
+    }
+  }
+};
+```
+
+### 2. Update Response Handling
+
+Check for new response fields:
+
+```typescript
+// Before
+const response = await agent.respond(message);
+console.log(response.message);
+console.log(response.isRouteComplete);
+
+// After - additional fields available
+const response = await agent.respond(message);
+console.log(response.message);
+console.log(response.isRouteComplete);
+console.log(response.executedSteps);    // NEW: Array of executed steps
+console.log(response.stoppedReason);    // NEW: Why execution stopped
+console.log(response.error);            // NEW: Error details if any
+```
+
+### 3. Review SkipIf Conditions
+
+SkipIf conditions now affect batch determination:
+
+```typescript
+// Before: skipIf evaluated when entering step
+const step = {
+  skipIf: (data) => {
+    // Called when transitioning to this step
+    return data.alreadyHaveInfo;
+  }
+};
+
+// After: skipIf evaluated during batch determination
+// If skipIf returns true, step is skipped and next step is evaluated
+// If skipIf throws, step is treated as non-skippable (included in batch)
+
+// Migration: Ensure skipIf is pure and doesn't have side effects
+const step = {
+  skipIf: (data) => {
+    // GOOD: Pure function
+    return data.alreadyHaveInfo;
+  }
+};
+
+// AVOID: Side effects in skipIf
+const badStep = {
+  skipIf: (data) => {
+    // BAD: Side effect
+    logSkipCheck(data);
+    return data.alreadyHaveInfo;
+  }
+};
+```
+
+### 4. Handle Partial Execution
+
+Errors may leave partial progress:
+
+```typescript
+// Before: Single step, all or nothing
+
+// After: Batch may partially complete
+const response = await agent.respond(message);
+
+if (response.stoppedReason === 'prepare_error') {
+  // Some steps may have executed before the error
+  console.log("Executed before error:", response.executedSteps);
+  console.log("Error details:", response.error);
+}
+```
+
+### 5. Update Tests
+
+Tests expecting single-step behavior need updates:
+
+```typescript
+// Before
+test("collects hotel name", async () => {
+  const response = await agent.respond("Book Grand Hotel");
+  expect(response.session.data.hotel).toBe("Grand Hotel");
+  // Assumed only hotel step executed
+});
+
+// After
+test("collects hotel name", async () => {
+  const response = await agent.respond("Book Grand Hotel");
+  expect(response.session.data.hotel).toBe("Grand Hotel");
+  
+  // Check which steps actually executed
+  expect(response.executedSteps).toContainEqual(
+    expect.objectContaining({ id: "ask-hotel" })
+  );
+  
+  // May have executed more steps if data was available
+  expect(response.stoppedReason).toBe("needs_input");
+});
+```
+
+## Before/After Examples
+
+### Example 1: Simple Booking Flow
+
+**Before (3 turns):**
+```
+User: "I want to book a hotel"
+Bot: "Which hotel would you like?"
+User: "Grand Hotel"
+Bot: "What date?"
+User: "Friday"
+Bot: "Booking confirmed!"
+```
+
+**After (potentially 1-2 turns):**
+```
+User: "I want to book Grand Hotel for Friday"
+Bot: "Booking confirmed for Grand Hotel on Friday!"
+```
+
+### Example 2: Partial Information
+
+**Before:**
+```
+User: "Book Grand Hotel"
+Bot: "What date?" (only hotel step executed)
+```
+
+**After:**
+```
+User: "Book Grand Hotel"
+Bot: "What date?" (hotel step executed, stopped at date step)
+// response.executedSteps = [{ id: "ask-hotel" }]
+// response.stoppedReason = "needs_input"
+```
+
+### Example 3: With SkipIf Conditions
+
+**Before:**
+```typescript
+// Each step evaluated individually
+const step1 = { skipIf: (d) => !!d.name };  // Skipped if name exists
+const step2 = { skipIf: (d) => !!d.email }; // Skipped if email exists
+```
+
+**After:**
+```typescript
+// All skipIf conditions evaluated during batch determination
+// If user provides "I'm John, john@example.com":
+// - Pre-extraction: { name: "John", email: "john@example.com" }
+// - step1 skipIf: true (skipped)
+// - step2 skipIf: true (skipped)
+// - Both steps skipped, route may complete immediately
+```
+
+## Opting Out of Batching
+
+If you need single-step behavior for specific steps, use `requires` to create dependencies:
+
+```typescript
+// Force step2 to wait for step1's data
+const step1 = {
+  collect: ["name"],
+};
+
+const step2 = {
+  collect: ["email"],
+  requires: ["name"], // Won't batch with step1
+};
+
+// Now step2 will only execute after step1 completes
+// (in a separate batch/LLM call)
+```
+
+## Debugging Migration Issues
+
+Enable debug mode to see batch behavior:
+
+```typescript
+const agent = new Agent({
+  debug: true,
+  // ...
+});
+
+// Logs will show:
+// [BatchExecutor] Starting batch determination...
+// [BatchExecutor] Including step ask-hotel in batch
+// [BatchExecutor] Step ask-date needs input, stopping batch
+```
+
+## Summary
+
+1. **Multiple steps can now execute together** - reducing LLM calls
+2. **Pre-extraction happens before batch determination** - maximizing batching
+3. **New response fields** - `executedSteps`, `stoppedReason`, `error`
+4. **Hook execution order changed** - all prepare, then LLM, then all finalize
+5. **SkipIf affects batching** - evaluated during batch determination
+6. **Partial progress preserved** - on errors, completed steps are retained
+
+The changes improve efficiency and UX while maintaining API compatibility. Most existing code will work without changes, but reviewing hook dependencies and test expectations is recommended.