@falai/agent 1.2.7 → 2.0.0

package/docs/architecture/data-extraction-flow.md

@@ -1,360 +0,0 @@
-# Data Extraction Flow Architecture
-
-## Overview
-
-@falai/agent uses an **intelligent pre-extraction system** that captures data from user messages BEFORE entering conversation steps. This eliminates repetitive questions and creates efficient, natural conversations.
-
-## The Problem with Traditional Approaches
-
-Traditional conversational AI follows a rigid step-by-step approach:
-
-```
-User: "I want to book the Grand Hotel for 2 people next Friday"
-
-Traditional Flow:
-Step 1: "Which hotel?" → User already said this!
-Step 2: "How many guests?" → User already said this!
-Step 3: "What date?" → User already said this!
-```
-
-This wastes user time and creates frustration.
-
-## Our Solution: Pre-Extraction + Smart Step Selection
-
-### Phase 1: Route Selection & Pre-Extraction
-
-When a user message arrives:
-
-1. **Route Evaluation** - AI scores all routes based on user intent
-2. **Route Selection** - Best matching route is selected
-3. **Pre-Extraction** - If entering a NEW route that collects data:
-   - AI extracts ALL relevant data from the message
-   - Data is validated against the agent schema
-   - Collected data is merged into session
-
-```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: Step Skipping
-
-After pre-extraction, the system evaluates the route's steps:
-
-```typescript
-// Route defines required fields
-agent.createRoute({
-  title: "Book Hotel",
-  requiredFields: ["hotelName", "guests", "date"],
-  // ...
-});
-
-// After pre-extraction, all required fields are present.
-// The data is now in the session, which allows steps to be evaluated.
-```
-
-**Key Insight:** Routes complete by naturally reaching the `END_ROUTE` step. If all required data is pre-extracted, the system will rapidly skip through the data-collection steps and naturally reach the end of the route.
-
-### Phase 3: Smart Step Selection
-
-If route is NOT complete, determine which step to start at:
-
-```typescript
-// Steps with skipIf conditions
-steps: [
-  {
-    id: "ask_hotel",
-    collect: ["hotelName"],
-    skipIf: (data) => !!data.hotelName  // ✅ SKIP - already have it
-  },
-  {
-    id: "ask_guests",
-    collect: ["guests"],
-    skipIf: (data) => data.guests !== undefined  // ✅ SKIP - already have it
-  },
-  {
-    id: "ask_date",
-    collect: ["date"],
-    skipIf: (data) => !!data.date  // ✅ SKIP - already have it
-  }
-]
-
-// Result: All steps skipped → Route complete
-```
-
-### Phase 4: Response Generation
-
-**If route is complete:**
-- Generate completion message
-- Mark step as END_ROUTE
-- Exclude route from future selection
-
-**If route is NOT complete:**
-- Enter the first non-skipped step
-- Generate response asking for missing data
-- Continue conversation
-
-## Complete Flow Example
-
-### Scenario: User provides all data at once
-
-```typescript
-// Turn 1
-User: "I want to book the Grand Hotel for 2 people next Friday"
-
-System:
-1. Routes to "Book Hotel" (AI scoring)
-2. Pre-extracts: { hotelName: "Grand Hotel", guests: 2, date: "next Friday" }
-3. Evaluates steps: All collection steps are skipped (data already present)
-4. Reaches END_ROUTE and generates completion message
-5. Marks route as complete
-
-AI: "Perfect! Booking confirmed for 2 guests at Grand Hotel on Friday!"
-
-// Turn 2
-User: "I'm feeling anxious about my visit"
-
-System:
-1. Evaluates routes
-2. Excludes "Book Hotel" (already complete)
-3. Routes to "General Healthcare Questions"
-4. Generates response
-
-AI: "I understand you're feeling anxious. How can I help?"
-```
-
-### Scenario: User provides partial data
-
-```typescript
-// Turn 1
-User: "I want to book the Grand Hotel"
-
-System:
-1. Routes to "Book Hotel"
-2. Pre-extracts: { hotelName: "Grand Hotel" }
-3. Checks completion: Missing guests and date ✗
-4. Evaluates steps:
-   - ask_hotel: SKIP (have hotelName)
-   - ask_guests: ENTER (need guests)
-5. Enters ask_guests step
-
-AI: "How many guests will be staying?"
-
-// Turn 2
-User: "2 people next Friday"
-
-System:
-1. Already in "Book Hotel" route
-2. Pre-extracts: { guests: 2, date: "next Friday" }
-3. Evaluates steps: All collection steps are skipped (data already present)
-4. Reaches END_ROUTE and generates completion message
-
-AI: "Booking confirmed for 2 guests at Grand Hotel on Friday!"
-```
-
-## Key Design Decisions
-
-### 1. Pre-Extraction Triggers
-
-Pre-extraction only happens when:
-- Entering a NEW route (not already in it)
-- Route has `requiredFields`, `optionalFields`, OR steps with `collect` arrays
-
-This minimizes unnecessary AI calls for purely conversational routes.
-
-### 2. Route Completion Logic
-
-A route is complete when:
-- **It reaches the END_ROUTE marker in its step flow**
-
-`requiredFields` act as a validation gate. While they must be collected, simply collecting them doesn't instantly end the route; the conversation naturally progresses through any remaining steps (or skips them) until it finishes.
-
-### 3. Completed Route Exclusion
-
-Once a route is 100% complete:
-- It's excluded from future route selection
-- Users won't be forced back into finished tasks
-- System falls back to other routes or general conversation
-
-### 4. Step Skipping Logic
-
-Steps are skipped when:
-- `skipIf` condition evaluates to true
-- `requires` fields are not yet collected
-- Data for `collect` fields is already present
-
-## Configuration
-
-### Enable Pre-Extraction
-
-Pre-extraction is automatic when you define:
-
-```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: [
-    {
-      id: "ask_hotel",
-      collect: ["hotel"],  // Pre-extraction enabled automatically
-    }
-  ]
-});
-```
-
-### Disable Pre-Extraction
-
-For purely conversational routes (no data collection):
-
-```typescript
-agent.createRoute({
-  title: "General Chat",
-  // No requiredFields, optionalFields, or collect arrays
-  // Pre-extraction skipped automatically
-  steps: [
-    {
-      id: "chat",
-      prompt: "Have a friendly conversation"
-      // No collect array
-    }
-  ]
-});
-```
-
-## Performance Considerations
-
-### AI Call Optimization
-
-Pre-extraction adds ONE additional AI call when entering a new data-collecting route:
-
-```
-Traditional: N calls (one per step)
-With Pre-Extraction: 1 + M calls (pre-extract + remaining steps)
-
-Where M ≤ N (often M = 0 if all data extracted)
-```
-
-**Net Result:** Usually FEWER total AI calls due to step skipping.
-
-### When to Use Pre-Extraction
-
-✅ **Use for:** Data collection flows (booking, forms, surveys)
-✅ **Use for:** Multi-field information gathering
-❌ **Skip for:** Pure Q&A or conversational routes
-❌ **Skip for:** Single-field collection
-
-## Advanced Patterns
-
-### Optional Fields
-
-```typescript
-agent.createRoute({
-  title: "Booking",
-  requiredFields: ["hotel", "date"],
-  optionalFields: ["specialRequests", "dietaryRestrictions"],
-  // Route completes when it naturally reaches END_ROUTE
-  // Optional fields can be collected if user provides them,
-  // but they won't block steps from progressing.
-});
-```
-
-### Conditional Completion
-
-```typescript
-agent.createRoute({
-  title: "Order",
-  requiredFields: ["items", "address"],
-  
-  steps: [
-    // ... collection steps ...
-    {
-      id: "payment",
-      when: "Ready to process payment",
-      skipIf: (data) => data.paymentComplete,
-      // This step runs AFTER required fields are collected
-      // Allows post-completion actions
-    }
-  ]
-});
-```
-
-### Progressive Disclosure
-
-```typescript
-agent.createRoute({
-  title: "Support",
-  requiredFields: ["issueType"],
-  optionalFields: ["accountNumber", "orderNumber"],
-  
-  steps: [
-    {
-      id: "ask_issue",
-      collect: ["issueType"],
-    },
-    {
-      id: "ask_account",
-      collect: ["accountNumber"],
-      when: (data) => data.issueType === "account",
-      // Only ask for account if issue is account-related
-    }
-  ]
-});
-```
-
-## Debugging
-
-Enable debug logging to see the extraction flow:
-
-```typescript
-const agent = new Agent({
-  name: "Assistant",
-  provider: new GeminiProvider({ apiKey: "..." }),
-  debug: true  // Enable detailed logging
-});
-```
-
-Look for these log messages:
-
-```
-[ResponseModal] Pre-extracting data for route: Book Hotel
-[ResponseModal] Pre-extracted data: { hotelName: "Grand Hotel", ... }
-[RoutingEngine] Route Book Hotel completed - END_ROUTE reached
-[RoutingEngine] Excluding completed route: Book Hotel
-```
-
-## Summary
-
-The pre-extraction system creates efficient conversations by:
-
-1. **Extracting data early** - Before entering steps
-2. **Skipping unnecessary steps** - When data is already present
-3. **Reaching completion naturally** - By skipping to the end when data is gathered
-4. **Protecting completed routes** - Preventing re-entry
-
-This results in natural, efficient conversations that respect user time.
-
----
-
-**Next Steps:**
-- [Route Configuration](../core/conversation-flows/routes.md)
-- [Step Configuration](../core/conversation-flows/steps.md)

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

@@ -1,277 +0,0 @@
-# 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.
-
-> **Note:** Multi-step batching is **opt-in**. By default, `maxStepsPerBatch` is `1`, meaning steps execute one at a time (classic behavior). Set `maxStepsPerBatch` to a higher value or `Infinity` to enable batching.
-
-## Configuration
-
-Control batching behavior with the `maxStepsPerBatch` option on the agent:
-
-```typescript
-const agent = new Agent({
-  name: "Assistant",
-  provider: provider,
-  // Default: 1 (single-step execution)
-  // Set higher to enable batching
-  maxStepsPerBatch: Infinity, // No limit — batch all eligible steps
-});
-```
-
-| Value | Behavior |
-|-------|----------|
-| `1` (default) | Steps execute one at a time |
-| `N` (e.g. `3`) | Up to N steps per batch |
-| `Infinity` | No limit — all eligible steps batch together |
-
-## 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 --> G2{maxStepsPerBatch reached?}
-    G2 -->|No| D
-    G2 -->|Yes| H[Stop Batch]
-    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
-  g. If needsInput is true → stop with 'needs_input'
-  h. Check if batch size reached maxStepsPerBatch → stop with 'max_steps_reached'
-  i. Continue to next Step
-```
-
-### 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
-// Enable batching to process multiple steps at once
-const agent = new Agent({
-  name: "Booking Agent",
-  provider: provider,
-  maxStepsPerBatch: Infinity, // Enable full batching
-});
-
-// 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
-  maxStepsPerBatch: 5,     // Allow up to 5 steps per batch
-});
-```
-
-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