@falai/agent 0.9.0 → 1.0.0

package/docs/core/ai-integration/response-processing.md

@@ -118,10 +118,121 @@ agentContext.lastResponseTime = Date.now();
 
 Robust error handling for various failure scenarios:
 
-- **Schema validation failures** - Graceful fallback to manual extraction
-- **Tool execution errors** - Error recovery and user notification
-- **Context update failures** - Rollback and logging
-- **Routing errors** - Safe fallback to default behavior
+### Schema Validation Failures
+
+When AI responses don't match expected schemas, the system gracefully falls back:
+
+```typescript
+const processResponse = async (response: string, schema: JSONSchema) => {
+  try {
+    // Try schema-based extraction first
+    const extracted = await extractWithSchema(response, schema);
+    return { success: true, data: extracted };
+  } catch (schemaError) {
+    console.warn("Schema extraction failed, falling back to manual parsing:", schemaError.message);
+    
+    // Fallback to manual extraction
+    try {
+      const manualData = await manualExtraction(response);
+      return { success: true, data: manualData, fallback: true };
+    } catch (fallbackError) {
+      return { 
+        success: false, 
+        error: `Both schema and manual extraction failed: ${fallbackError.message}` 
+      };
+    }
+  }
+};
+```
+
+### Tool Execution Errors
+
+Tool failures are handled gracefully with proper error propagation:
+
+```typescript
+const executeTool = async (tool: Tool, params: any) => {
+  try {
+    const result = await tool.handler(params);
+    return { success: true, result };
+  } catch (error) {
+    console.error(`Tool ${tool.id} execution failed:`, error);
+    
+    return {
+      success: false,
+      error: error.message,
+      fallbackMessage: "I encountered an issue while processing your request. Please try again."
+    };
+  }
+};
+```
+
+### Context Update Failures
+
+Context updates include rollback mechanisms:
+
+```typescript
+const updateContext = async (newContext: any, previousContext: any) => {
+  try {
+    await persistContext(newContext);
+    return { success: true };
+  } catch (error) {
+    console.error("Context update failed, rolling back:", error);
+    
+    try {
+      await persistContext(previousContext);
+      return { success: false, rolledBack: true, error: error.message };
+    } catch (rollbackError) {
+      return { 
+        success: false, 
+        rolledBack: false, 
+        error: `Update and rollback both failed: ${rollbackError.message}` 
+      };
+    }
+  }
+};
+```
+
+### Streaming Error Propagation
+
+Streaming responses properly propagate provider errors:
+
+```typescript
+async function* processStreamingResponse(provider: AIProvider, prompt: string) {
+  try {
+    for await (const chunk of provider.generateMessageStream(prompt)) {
+      yield { success: true, chunk };
+    }
+  } catch (error) {
+    // Ensure streaming errors are properly propagated
+    yield { success: false, error: error.message };
+    throw error; // Re-throw to stop the stream
+  }
+}
+```
+
+### Routing Errors
+
+Safe fallback to default behavior when routing fails:
+
+```typescript
+const selectRoute = async (routes: Route[], context: any) => {
+  try {
+    const selectedRoute = await aiRouting.selectBestRoute(routes, context);
+    return { success: true, route: selectedRoute };
+  } catch (routingError) {
+    console.warn("AI routing failed, using default route:", routingError.message);
+    
+    // Fallback to first available route or default
+    const fallbackRoute = routes.find(r => r.isDefault) || routes[0];
+    return { 
+      success: true, 
+      route: fallbackRoute, 
+      fallback: true,
+      error: routingError.message 
+    };
+  }
+};
+```
 
 ## Streaming Response Processing
 
@@ -166,6 +277,150 @@ Built-in monitoring capabilities:
 - **Debug logging** - Detailed processing traces
 - **Performance profiling** - Identify bottlenecks
 
+## Batch Execution Response Fields
+
+When using multi-step execution, the `AgentResponse` includes additional fields for batch execution information.
+
+### New AgentResponse Fields
+
+```typescript
+interface AgentResponse<TData = unknown> {
+  /** The generated message */
+  message: string;
+  /** Updated session state */
+  session?: SessionState<TData>;
+  /** Tool calls made during response */
+  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  /** Whether the route is complete */
+  isRouteComplete?: boolean;
+  
+  // Multi-step execution fields
+  /** Steps executed in this response */
+  executedSteps?: StepRef[];
+  /** Why execution stopped */
+  stoppedReason?: StoppedReason;
+}
+```
+
+### executedSteps Array
+
+Lists all steps that were executed in the batch:
+
+```typescript
+const response = await agent.respond("Book Grand Hotel for 2 on Friday");
+
+console.log(response.executedSteps);
+// [
+//   { id: "ask-hotel", routeId: "booking" },
+//   { id: "ask-guests", routeId: "booking" },
+//   { id: "ask-date", routeId: "booking" }
+// ]
+```
+
+Each `StepRef` contains:
+- `id` - The step identifier
+- `routeId` - The route this step belongs to
+
+### stoppedReason Field
+
+Indicates why batch execution stopped:
+
+```typescript
+type StoppedReason =
+  | 'needs_input'      // Step requires uncollected data
+  | 'end_route'        // Reached END_ROUTE
+  | 'route_complete'   // All Steps processed
+  | 'prepare_error'    // Error in prepare hook
+  | 'llm_error'        // Error during LLM call
+  | 'validation_error' // Error validating collected data
+  | 'finalize_error';  // Error in finalize hook (non-fatal)
+```
+
+### BatchExecutionResult Structure
+
+The internal batch execution result provides detailed information:
+
+```typescript
+interface BatchExecutionResult<TData = unknown> {
+  /** The generated message */
+  message: string;
+  /** Updated session state */
+  session: SessionState<TData>;
+  /** Steps that were executed */
+  executedSteps: StepRef[];
+  /** Why execution stopped */
+  stoppedReason: StoppedReason;
+  /** Collected data from the batch */
+  collectedData?: Partial<TData>;
+  /** Any errors that occurred */
+  error?: BatchExecutionError;
+}
+```
+
+### Error Information
+
+When errors occur, detailed information is available:
+
+```typescript
+interface BatchExecutionError {
+  /** Type of error that occurred */
+  type: 'pre_extraction' | 'skipif_evaluation' | 'prepare_hook' | 
+        'llm_call' | 'data_validation' | 'finalize_hook';
+  /** Error message */
+  message: string;
+  /** Step where error occurred (if applicable) */
+  stepId?: string;
+  /** Additional error details */
+  details?: unknown;
+}
+```
+
+### Using Response Fields
+
+```typescript
+const response = await agent.respond("Complete my booking");
+
+// Check what was executed
+console.log(`Executed ${response.executedSteps?.length || 0} steps`);
+
+// Check why execution stopped
+switch (response.stoppedReason) {
+  case 'needs_input':
+    console.log("Waiting for more information from user");
+    break;
+  case 'route_complete':
+  case 'end_route':
+    console.log("Route finished successfully");
+    break;
+  case 'validation_error':
+    console.log("Data validation issues:", response.error);
+    break;
+  default:
+    console.log("Stopped due to:", response.stoppedReason);
+}
+
+// Check route completion
+if (response.isRouteComplete) {
+  console.log("All required data collected");
+}
+```
+
+### Session State After Batch
+
+The session state reflects the final step position:
+
+```typescript
+const response = await agent.respond("Book for 2 guests");
+
+// Session shows current position
+console.log(response.session?.currentStep);
+// { id: "ask-date", routeId: "booking" }
+
+// Session data includes all collected values
+console.log(response.session?.data);
+// { hotel: "Grand Hotel", guests: 2 }
+```
+
 ## Best Practices
 
 - Design schemas for reliable AI extraction
@@ -174,3 +429,5 @@ Built-in monitoring capabilities:
 - Use streaming for better user experience
 - Leverage tool results for context enrichment
 - Validate data at multiple levels (schema + business rules)
+- Check `executedSteps` to understand batch behavior
+- Handle different `stoppedReason` values appropriately

package/docs/core/conversation-flows/data-collection.md

@@ -13,6 +13,149 @@ The agent-level data collection system provides:
 - **Natural Conversations**: AI handles information gathering conversationally
 - **Validation & Enrichment**: Agent-level lifecycle hooks for data processing
 - **Session Persistence**: Data survives across conversation turns and route transitions
+- **Batch Data Collection**: Multiple steps can collect data in a single LLM call
+
+## Data Collection Across Batched Steps
+
+When multiple steps execute in a single batch, data collection works across all steps simultaneously.
+
+### How Batch Data Collection Works
+
+1. **Gather collect fields** - All `collect` fields from all steps in the batch are combined
+2. **Single LLM call** - The combined prompt instructs the LLM to extract all fields
+3. **Extract from response** - All specified fields are extracted from the LLM response
+4. **Validate against schema** - Collected data is validated against the agent schema
+5. **Update session** - All collected values are merged into session data
+
+```typescript
+// Batch with 3 steps, each collecting different fields
+const batch = [
+  { collect: ["name"] },
+  { collect: ["email", "phone"] },
+  { collect: ["preferences"] }
+];
+
+// Combined collection: ["name", "email", "phone", "preferences"]
+// Single LLM response extracts all fields at once
+```
+
+### Pre-Extraction and Batch Determination
+
+Pre-extraction happens **before** batch determination and directly impacts which steps can be batched:
+
+```typescript
+// User message: "I'm John, email john@example.com, I prefer dark mode"
+
+// Phase 1: Pre-extraction
+const preExtracted = {
+  name: "John",
+  email: "john@example.com",
+  preferences: { theme: "dark" }
+};
+
+// Phase 2: Batch determination (with pre-extracted data merged)
+// Step 1: collect: ["name"] → name exists → doesn't need input
+// Step 2: collect: ["email"] → email exists → doesn't need input
+// Step 3: collect: ["preferences"] → preferences exists → doesn't need input
+// Result: All 3 steps batched together
+```
+
+### Pre-Extraction Configuration
+
+Pre-extraction is automatic when routes define data fields:
+
+```typescript
+// Option 1: Route-level required fields
+agent.createRoute({
+  title: "Booking",
+  requiredFields: ["hotel", "date", "guests"],
+  // Pre-extraction enabled automatically
+});
+
+// Option 2: Route-level optional fields
+agent.createRoute({
+  title: "Booking",
+  optionalFields: ["specialRequests"],
+  // Pre-extraction enabled automatically
+});
+
+// Option 3: Steps with collect arrays
+agent.createRoute({
+  title: "Booking",
+  steps: [
+    { collect: ["hotel"] },  // Pre-extraction enabled automatically
+  ]
+});
+```
+
+### Batch Collection Example
+
+```typescript
+const response = await agent.respond(
+  "I'm Alice, alice@example.com, and I want to book for 2 guests"
+);
+
+// Response includes all collected data
+console.log(response.session.data);
+// {
+//   name: "Alice",
+//   email: "alice@example.com",
+//   guests: 2
+// }
+
+// Shows which steps executed
+console.log(response.executedSteps);
+// [
+//   { id: "ask-name", routeId: "booking" },
+//   { id: "ask-email", routeId: "booking" },
+//   { id: "ask-guests", routeId: "booking" }
+// ]
+```
+
+### Validation Across Batch
+
+Data validation happens after collection for all fields:
+
+```typescript
+// Agent schema defines validation rules
+const agent = new Agent({
+  schema: {
+    type: "object",
+    properties: {
+      email: { type: "string", format: "email" },
+      guests: { type: "number", minimum: 1, maximum: 10 }
+    }
+  }
+});
+
+// If validation fails for any field:
+const response = await agent.respond("Book for 100 guests");
+
+// Response includes validation errors
+if (response.stoppedReason === 'validation_error') {
+  console.log(response.error);
+  // {
+  //   type: 'data_validation',
+  //   message: 'Validation failed for 1 field(s): guests',
+  //   details: [{ field: 'guests', message: 'Value exceeds maximum of 10' }]
+  // }
+}
+```
+
+### Partial Data Preservation
+
+Even when validation fails, valid partial data is preserved:
+
+```typescript
+// User provides valid name but invalid email
+const response = await agent.respond("I'm John, email: not-an-email");
+
+// Valid data is still collected
+console.log(response.session.data.name); // "John"
+
+// Invalid data triggers validation error
+console.log(response.stoppedReason); // "validation_error"
+```
 
 ## Agent-Level Schema Definition
 

package/docs/core/conversation-flows/routes.md

@@ -44,7 +44,7 @@ const agent = new Agent<{}, HotelData>({
 const bookingRoute = agent.createRoute({
   title: "Hotel Booking",
   description: "Help users book hotel accommodations",
-  conditions: ["User wants to book a hotel"],
+  when: ["User wants to book a hotel"],
   requiredFields: ["destination", "checkIn", "checkOut", "guests", "customerName", "email"],
   optionalFields: ["roomType", "phone", "specialRequests"]
 });
@@ -52,7 +52,7 @@ const bookingRoute = agent.createRoute({
 const customerServiceRoute = agent.createRoute({
   title: "Customer Service",
   description: "Help with booking issues",
-  conditions: ["User needs help with existing booking"],
+  when: ["User needs help with existing booking"],
   requiredFields: ["customerName", "email"], // Minimal requirements
   optionalFields: ["phone", "destination"]
 });
@@ -74,6 +74,8 @@ Routes are selected by the AI routing system based on user intent and conversati
 
 Routes complete when all their required fields are present in the agent's collected data, regardless of which route collected the data. This enables flexible cross-route completion scenarios.
 
+### Basic Route Completion
+
 ```typescript
 // Route completion evaluation
 const isComplete = bookingRoute.isComplete(agent.getCollectedData());
@@ -86,6 +88,134 @@ if (missingFields.length > 0) {
 }
 ```
 
+### Route Completion with Error Handling
+
+Proper error handling ensures accurate route completion detection:
+
+```typescript
+const checkRouteCompletion = async (route: Route, agent: Agent) => {
+  try {
+    const collectedData = agent.getCollectedData();
+    
+    // Check data-based completion
+    if (route.isComplete(collectedData)) {
+      return { complete: true, reason: "all_required_data_collected" };
+    }
+    
+    // Check step-based completion (for routes with skipIf conditions)
+    const allStepsProcessed = route.steps.every(step => {
+      if (step.skipIf && step.skipIf(collectedData)) {
+        return true; // Step is skipped, counts as processed
+      }
+      return step.isCompleted;
+    });
+    
+    if (allStepsProcessed) {
+      return { complete: true, reason: "all_steps_processed" };
+    }
+    
+    // Check for explicit route termination
+    if (route.hasExplicitEnd()) {
+      return { complete: true, reason: "explicit_end_route" };
+    }
+    
+    return { 
+      complete: false, 
+      missingFields: route.getMissingRequiredFields(collectedData),
+      progress: route.getCompletionProgress(collectedData)
+    };
+  } catch (error) {
+    console.error("Route completion check failed:", error);
+    return { 
+      complete: false, 
+      error: error.message,
+      fallback: true 
+    };
+  }
+};
+
+// Usage with error handling
+const completionResult = await checkRouteCompletion(bookingRoute, agent);
+
+if (completionResult.error) {
+  console.warn("Completion check failed, assuming incomplete:", completionResult.error);
+} else if (completionResult.complete) {
+  console.log(`Route completed: ${completionResult.reason}`);
+} else {
+  console.log(`Route ${Math.round(completionResult.progress * 100)}% complete`);
+  console.log(`Missing: ${completionResult.missingFields.join(', ')}`);
+}
+```
+
+### Handling Routes with Conditional Steps
+
+Routes with `skipIf` conditions require special completion logic:
+
+```typescript
+const conditionalRoute = agent.createRoute({
+  title: "Conditional Booking",
+  requiredFields: ["destination", "dates", "passengers"]
+});
+
+const askDestination = conditionalRoute.initialStep.nextStep({
+  prompt: "Where would you like to go?",
+  collect: ["destination"],
+  skipIf: (data) => !!data.destination, // Skip if already collected
+});
+
+const askDates = askDestination.nextStep({
+  prompt: "When would you like to travel?",
+  collect: ["dates"],
+  skipIf: (data) => !!data.dates,
+});
+
+const confirmBooking = askDates.nextStep({
+  prompt: "Confirm your booking details",
+  requires: ["destination", "dates", "passengers"],
+  onComplete: () => ({ endRoute: true }) // Explicit route termination
+});
+
+// Completion detection handles skipped steps
+const response = await agent.respond({
+  message: "I want to go to Paris on March 15th for 2 passengers",
+  sessionId: "user-123"
+});
+
+// All steps may be skipped due to complete data extraction
+// Route should still be marked as complete
+console.log("Route complete:", response.isRouteComplete); // Should be true
+```
+
+### Error Recovery in Route Completion
+
+```typescript
+const safeRouteCompletion = async (route: Route, agent: Agent) => {
+  const maxRetries = 3;
+  let attempt = 0;
+  
+  while (attempt < maxRetries) {
+    try {
+      return await checkRouteCompletion(route, agent);
+    } catch (error) {
+      attempt++;
+      console.warn(`Route completion check attempt ${attempt} failed:`, error.message);
+      
+      if (attempt >= maxRetries) {
+        // Final fallback - assume incomplete
+        return {
+          complete: false,
+          error: `Completion check failed after ${maxRetries} attempts: ${error.message}`,
+          fallback: true
+        };
+      }
+      
+      // Brief delay before retry
+      await new Promise(resolve => setTimeout(resolve, 100 * attempt));
+    }
+  }
+};
+```
+
 ## Route Transitions
 
 Routes can automatically transition to other routes upon completion using the `onComplete` configuration. With agent-level data, the target route may already have some of its required data.