@falai/agent 0.1.0-alpha2 → 0.1.0-alpha3

package/docs/architecture/multi-step-execution.md

@@ -0,0 +1,243 @@
+# Multi-Step Execution Architecture
+
+## Overview
+
+@falai/agent supports **multi-step execution**, enabling multiple consecutive Steps to execute in a single LLM call. This reduces unnecessary multi-turn conversations, minimizes LLM costs, and improves user experience when steps don't require new user input.
+
+The core insight is simple: **if a Step's data requirements are already satisfied, there's no reason to pause and wait for user input**. By detecting which Steps can execute together and combining them into a single batch, we reduce LLM calls while improving conversation UX.
+
+## Design Priorities
+
+1. **Conversation UX** - Reduce unnecessary back-and-forth
+2. **LLM Cost Optimization** - Fewer calls for the same outcome
+3. **Predictability** - Clear, simple rules for when execution pauses
+4. **Framework Understandability** - Keep the Step/Route mental model intact
+
+## Batch Execution Flow
+
+```mermaid
+flowchart TD
+    A[User Message] --> B[Pre-Extraction]
+    B --> C[Batch Determination]
+    C --> D{More Steps?}
+    D -->|Yes| E[Evaluate Step]
+    E --> F{Needs Input?}
+    F -->|No| G[Add to Batch]
+    G --> D
+    F -->|Yes| H[Stop Batch]
+    D -->|No| H
+    H --> I[Execute Prepare Hooks]
+    I --> J[Build Combined Prompt]
+    J --> K[Single LLM Call]
+    K --> L[Extract Response Data]
+    L --> M[Execute Finalize Hooks]
+    M --> N[Update Session]
+    N --> O[Return Response]
+```
+
+## Execution Phases
+
+### Phase 1: Pre-Extraction
+
+When processing a user message, the engine performs **pre-extraction** before determining the batch. This phase:
+
+1. Attempts to extract data for all fields defined in the Route's `requiredFields` and `optionalFields`
+2. Merges pre-extracted data into session data
+3. Maximizes batching by satisfying Step requirements upfront
+
+```typescript
+// User: "I want to book the Grand Hotel for 2 people next Friday"
+
+// Pre-extraction automatically captures:
+{
+  hotelName: "Grand Hotel",
+  guests: 2,
+  date: "next Friday"
+}
+```
+
+### Phase 2: Batch Determination
+
+The `BatchExecutor` walks through Steps using this algorithm:
+
+```
+For each Step starting from current position:
+  a. Check if it's END_ROUTE → stop with 'end_route'
+  b. Evaluate skipIf condition
+  c. If skipIf is true → skip Step, continue to next
+  d. If skipIf throws error → treat as non-skippable
+  e. Evaluate needsInput(step, sessionDataAfterPreExtraction)
+  f. If needsInput is false → include Step in batch, continue to next
+  g. If needsInput is true → stop with 'needs_input'
+```
+
+### Phase 3: Hook Execution (Prepare)
+
+Before the LLM call, all `prepare` hooks for batched Steps execute in Step order. If any prepare hook fails, batch execution stops immediately.
+
+### Phase 4: LLM Call
+
+A single LLM call is made with a combined prompt that includes all Step prompts and collect fields.
+
+### Phase 5: Data Collection
+
+All `collect` fields from all Steps in the batch are extracted from the LLM response and validated against the agent schema.
+
+### Phase 6: Hook Execution (Finalize)
+
+After the LLM response, all `finalize` hooks execute in Step order. Finalize hook failures are logged but don't stop execution.
+
+## Needs-Input Detection Algorithm
+
+The `needsInput` function implements the core execution rule:
+
+```typescript
+function needsInput<TData>(
+  step: Step<unknown, TData>,
+  sessionDataAfterPreExtraction: Partial<TData>
+): boolean {
+  // Check requires - all must be present (after pre-extraction)
+  if (step.requires && step.requires.length > 0) {
+    const missingRequired = step.requires.some(
+      field => sessionDataAfterPreExtraction[field] === undefined
+    );
+    if (missingRequired) return true;
+  }
+
+  // Check collect - needs input if collecting and no data exists (after pre-extraction)
+  if (step.collect && step.collect.length > 0) {
+    const hasAnyCollectData = step.collect.some(
+      field => sessionDataAfterPreExtraction[field] !== undefined
+    );
+    if (!hasAnyCollectData) return true;
+  }
+
+  return false;
+}
+```
+
+A Step **needs input** when:
+
+1. It has `requires` fields and at least one is missing from session data (after pre-extraction)
+2. It has non-empty `collect` fields and none of those fields have data (after pre-extraction)
+
+## Pre-Extraction's Role in Batching
+
+Pre-extraction is critical for maximizing batch size. Consider this scenario:
+
+```typescript
+// Route with 3 steps
+const route = agent.createRoute({
+  title: "Booking",
+  requiredFields: ["hotel", "date", "guests"],
+  steps: [
+    { prompt: "Which hotel?", collect: ["hotel"] },
+    { prompt: "What date?", collect: ["date"] },
+    { prompt: "How many guests?", collect: ["guests"] }
+  ]
+});
+
+// User message: "Book Grand Hotel for 2 people on Friday"
+```
+
+**Without pre-extraction:**
+- Step 1 needs input (no hotel data) → batch stops
+- 3 separate LLM calls needed
+
+**With pre-extraction:**
+- Pre-extraction captures: `{ hotel: "Grand Hotel", date: "Friday", guests: 2 }`
+- All steps have their data satisfied
+- All 3 steps execute in a single batch
+- 1 LLM call needed
+
+## Key Components
+
+### BatchExecutor
+
+The core component responsible for:
+- Determining which Steps can execute together (`determineBatch`)
+- Executing prepare/finalize hooks (`executePrepareHooks`, `executeFinalizeHooks`)
+- Collecting data from LLM responses (`collectBatchData`)
+- Orchestrating complete batch execution (`executeBatch`)
+
+### BatchPromptBuilder
+
+Combines multiple Step prompts into a single coherent prompt:
+- Preserves each Step's individual prompt intent
+- Includes data collection instructions for all `collect` fields
+- Produces a single LLM call regardless of Step count
+
+## Example: Multi-Step Batch
+
+```typescript
+// User provides all booking info at once
+const response = await agent.respond(
+  "I want to book the Grand Hotel for 2 people next Friday"
+);
+
+// Response includes:
+{
+  message: "Perfect! I've booked the Grand Hotel for 2 guests on Friday.",
+  executedSteps: [
+    { id: "ask-hotel", routeId: "booking" },
+    { id: "ask-date", routeId: "booking" },
+    { id: "ask-guests", routeId: "booking" }
+  ],
+  stoppedReason: "route_complete",
+  session: {
+    data: {
+      hotel: "Grand Hotel",
+      date: "Friday",
+      guests: 2
+    }
+  }
+}
+```
+
+## Debugging
+
+Enable debug mode to see batch execution decisions:
+
+```typescript
+const agent = new Agent({
+  name: "Assistant",
+  provider: provider,
+  debug: true  // Enable detailed logging
+});
+```
+
+Look for these log messages:
+
+```
+[BatchExecutor] Starting batch determination from step index 0
+[BatchExecutor] Including step ask-hotel in batch (all requirements satisfied)
+[BatchExecutor] Including step ask-date in batch (all requirements satisfied)
+[BatchExecutor] Step ask-guests needs input, stopping batch
+[BatchExecutor] Batch determination complete. Steps: 2, Stopped reason: needs_input
+```
+
+## Event Emission
+
+The BatchExecutor emits events for observability:
+
+- `batch_start` - When batch determination begins
+- `step_included` - When a step is included in the batch
+- `step_skipped` - When a step is skipped (due to skipIf)
+- `batch_stop` - When batch determination stops
+- `batch_complete` - When batch execution completes
+
+```typescript
+const executor = new BatchExecutor();
+
+executor.addEventListener((event) => {
+  console.log(`[${event.type}]`, event.details);
+});
+```
+
+---
+
+**Related Documentation:**
+- [Steps](../core/conversation-flows/steps.md) - Step configuration and batching
+- [Step Transitions](../core/conversation-flows/step-transitions.md) - Stopping conditions
+- [Data Collection](../core/conversation-flows/data-collection.md) - Pre-extraction details
+- [Prompt Composition](../core/ai-integration/prompt-composition.md) - Combined prompts

package/docs/core/ai-integration/prompt-composition.md

@@ -218,3 +218,138 @@ Prompts are optimized for token efficiency:
 - Leverage route-specific overrides for specialized behavior
 - Monitor token usage and optimize prompt length
 - Test prompts with different AI providers for consistency
+
+## BatchPromptBuilder for Multi-Step Execution
+
+When multiple steps execute in a single batch, the `BatchPromptBuilder` combines their prompts into a single coherent prompt.
+
+### Combined Prompt Structure
+
+```
+[Agent Identity & Personality]
+[Route Context]
+
+## Current Conversation Flow
+
+You are handling multiple aspects of this conversation in a single response.
+
+### Step 1: [Step Description]
+[Step Prompt]
+
+### Step 2: [Step Description]  
+[Step Prompt]
+
+[... additional steps ...]
+
+## Data Collection
+
+Extract the following information from your response:
+- field1 (type): description
+- field2 (type): description
+
+## Response Format
+
+Return JSON with:
+- message: Your response to the user
+- [collected fields as top-level properties]
+```
+
+### How Prompts Are Merged
+
+The `BatchPromptBuilder` preserves each step's intent while creating a unified prompt:
+
+```typescript
+// Individual step prompts
+const step1 = { prompt: "What's your name?", collect: ["name"] };
+const step2 = { prompt: "What's your email?", collect: ["email"] };
+const step3 = { prompt: "How can I help?", collect: ["request"] };
+
+// Combined prompt includes all three
+const result = await batchPromptBuilder.buildBatchPrompt({
+  steps: [step1, step2, step3],
+  route,
+  history,
+  context,
+  session,
+  agentOptions,
+});
+
+// result.prompt contains unified prompt
+// result.collectFields = ["name", "email", "request"]
+// result.stepCount = 3
+```
+
+### Collect Fields Aggregation
+
+All `collect` fields from all steps are combined and deduplicated:
+
+```typescript
+// Steps with overlapping collect fields
+const steps = [
+  { collect: ["name", "email"] },
+  { collect: ["email", "phone"] },  // email appears twice
+  { collect: ["preferences"] }
+];
+
+// Combined collect fields (deduplicated)
+// ["name", "email", "phone", "preferences"]
+```
+
+### Schema-Aware Field Descriptions
+
+When the agent has a schema, field descriptions are included in the prompt:
+
+```typescript
+// Agent schema
+const schema = {
+  properties: {
+    email: { type: "string", format: "email", description: "User's email address" },
+    guests: { type: "number", minimum: 1, description: "Number of guests" }
+  }
+};
+
+// Generated data collection section:
+// ## Data Collection
+// Extract the following information from your response:
+// - email (string): User's email address
+// - guests (number): Number of guests
+```
+
+### Single vs Multi-Step Prompts
+
+The prompt structure adapts based on batch size:
+
+```typescript
+// Single step batch
+// ## Current Step
+// [Step prompt]
+
+// Multi-step batch
+// ## Current Conversation Flow
+// You are handling multiple aspects of this conversation in a single response.
+// ### Step 1: ...
+// ### Step 2: ...
+```
+
+### Using BatchPromptBuilder
+
+```typescript
+import { BatchPromptBuilder } from "@falai/agent";
+
+const builder = new BatchPromptBuilder<MyContext, MyData>();
+
+const result = await builder.buildBatchPrompt({
+  steps: batchResult.steps,
+  route: currentRoute,
+  history: conversationHistory,
+  context: agentContext,
+  session: currentSession,
+  agentOptions: agent.getAgentOptions(),
+});
+
+// Use result.prompt for LLM call
+const llmResponse = await provider.generateMessage({
+  prompt: result.prompt,
+  // ...
+});
+```

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

@@ -277,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
@@ -285,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