@falai/agent 0.6.8 → 0.7.0

package/docs/STATES.md

@@ -1,888 +0,0 @@
-# States Guide
-
-A complete guide to creating and managing states in conversational flows.
-
----
-
-## Table of Contents
-
-- [What is a State?](#what-is-a-state)
-- [Creating States](#creating-states)
-- [State Configuration](#state-configuration)
-- [Transitions](#transitions)
-- [Data Gathering](#data-gathering)
-- [State Logic](#state-logic)
-- [State Types](#state-types)
-- [Advanced Patterns](#advanced-patterns)
-
----
-
-## What is a State?
-
-A **State** represents a specific step or moment in a conversation. Each state can:
-
-- Display a message to the user (chat state)
-- Execute a tool (tool state)
-- Gather data from the conversation
-- Make decisions about what to do next
-
-```typescript
-// Example: A state that asks for user's name
-const askName = route.initialState.transitionTo({
-  chatState: "What's your name?",
-  gather: ["firstName", "lastName"],
-});
-```
-
-**Key Concepts:**
-
-- States form a **state machine** within a route
-- Each state has a unique **ID** (auto-generated or custom)
-- States can **gather data** from user responses
-- States can be **skipped** based on conditions
-- States can have **prerequisites** (required data)
-
----
-
-## Creating States
-
-### Chat States
-
-Chat states present a message and optionally gather data:
-
-```typescript
-// Simple chat state
-const welcome = route.initialState.transitionTo({
-  chatState: "Welcome! How can I help you today?",
-});
-
-// Chat state with data gathering
-const askDestination = welcome.transitionTo({
-  chatState: "Where would you like to fly?",
-  gather: ["destination"],
-});
-
-// Chat state with custom ID
-const askDates = askDestination.transitionTo({
-  id: "ask_travel_dates",
-  chatState: "When would you like to depart?",
-  gather: ["departureDate"],
-});
-```
-
-### Tool States
-
-Tool states execute functions and can update context or extracted data:
-
-```typescript
-import { defineTool } from "@falai/agent";
-
-const searchFlights = defineTool<Context, [], Results>(
-  "search_flights",
-  async ({ context, extracted }) => {
-    const results = await api.search(extracted.destination);
-    return {
-      data: results,
-      contextUpdate: { availableFlights: results },
-    };
-  }
-);
-
-// Tool state
-const searchState = askDates.transitionTo({
-  toolState: searchFlights,
-  requiredData: ["destination", "departureDate"],
-});
-```
-
-### Direct State References
-
-Jump to specific states or end the route:
-
-```typescript
-import { END_STATE } from "@falai/agent";
-
-// Jump to another state
-const confirm = processPayment.transitionTo({
-  state: previousState.getRef(), // Jump back
-});
-
-// End the route
-const complete = confirm.transitionTo({
-  state: END_STATE,
-});
-```
-
----
-
-## State Configuration
-
-### Configuring Initial State
-
-Every route has an initial state that can be configured:
-
-```typescript
-// Option 1: Configure at route creation
-const route = agent.createRoute({
-  title: "Booking",
-  initialState: {
-    id: "welcome",
-    chatState: "Welcome to our booking system!",
-    gather: ["intention"],
-  },
-});
-
-// Option 2: Configure after creation
-route.initialState.configure({
-  description: "Welcome! Let's start booking",
-  gatherFields: ["destination"],
-  skipIf: (extracted) => !!extracted.destination,
-  requiredData: [],
-});
-```
-
-### Configuring Any State
-
-You can configure any state after creation:
-
-```typescript
-const askName = route.initialState.transitionTo({
-  chatState: "What's your name?",
-});
-
-// Later, reconfigure it
-askName.configure({
-  description: "Ask for user's full name",
-  gatherFields: ["firstName", "lastName"],
-  skipIf: (extracted) => !!extracted.firstName && !!extracted.lastName,
-});
-
-// Chaining is supported
-askName
-  .configure({ description: "Updated description" })
-  .configure({ gatherFields: ["fullName"] });
-```
-
-### Configuration Options
-
-```typescript
-state.configure({
-  // State description
-  description?: string;
-
-  // Fields to gather from conversation
-  gatherFields?: string[];
-
-  // Skip this state if condition is met
-  skipIf?: (extracted: Partial<TExtracted>) => boolean;
-
-  // Prerequisites that must be met before entering
-  requiredData?: string[];
-});
-```
-
----
-
-## Transitions
-
-### Transition Specification
-
-Every transition from one state to another uses a `TransitionSpec`:
-
-```typescript
-interface TransitionSpec<TExtracted = unknown> {
-  // Custom state ID (optional)
-  id?: string;
-
-  // Chat state description
-  chatState?: string;
-
-  // Tool to execute
-  toolState?: ToolRef;
-
-  // Direct state reference or END_STATE
-  state?: StateRef | symbol;
-
-  // Fields to gather in this state
-  gather?: string[];
-
-  // Skip condition (code-based)
-  skipIf?: (extracted: Partial<TExtracted>) => boolean;
-
-  // Prerequisites
-  requiredData?: string[];
-
-  // AI-evaluated condition (for state selection)
-  condition?: string;
-}
-```
-
-### Transition Chaining
-
-```typescript
-// Linear flow
-route.initialState
-  .transitionTo({
-    chatState: "Step 1",
-    gather: ["field1"],
-  })
-  .transitionTo({
-    chatState: "Step 2",
-    gather: ["field2"],
-  })
-  .transitionTo({
-    chatState: "Step 3",
-    gather: ["field3"],
-  })
-  .transitionTo({ state: END_STATE });
-```
-
-### Branching Transitions
-
-```typescript
-const askType = route.initialState.transitionTo({
-  chatState: "Are you booking a flight or hotel?",
-  gather: ["bookingType"],
-});
-
-// Branch 1: Flight booking
-const flightFlow = askType.transitionTo({
-  chatState: "Let's book your flight",
-  condition: "User selected flight",
-});
-
-// Branch 2: Hotel booking
-const hotelFlow = askType.transitionTo({
-  chatState: "Let's book your hotel",
-  condition: "User selected hotel",
-});
-
-// Both branches can converge later
-const payment = flightFlow.transitionTo({
-  chatState: "Let's process payment",
-});
-
-hotelFlow.transitionTo({ state: payment }); // Converge to payment
-```
-
----
-
-## Data Gathering
-
-### Basic Gathering
-
-Specify which fields to extract in each state:
-
-```typescript
-interface UserData {
-  firstName: string;
-  lastName: string;
-  email: string;
-  phone: string;
-}
-
-const route = agent.createRoute<UserData>({ ... });
-
-// Gather single field
-const askName = route.initialState.transitionTo({
-  chatState: "What's your first name?",
-  gather: ["firstName"],
-});
-
-// Gather multiple fields at once
-const askContact = askName.transitionTo({
-  chatState: "Please provide your email and phone number",
-  gather: ["email", "phone"],
-});
-```
-
-### Gathering with Schema Validation
-
-The extraction schema validates gathered data:
-
-```typescript
-const route = agent.createRoute<UserData>({
-  title: "User Registration",
-
-  extractionSchema: {
-    type: "object",
-    properties: {
-      firstName: {
-        type: "string",
-        minLength: 1,
-      },
-      email: {
-        type: "string",
-        format: "email", // Validates email format
-      },
-      age: {
-        type: "number",
-        minimum: 18,
-        maximum: 120,
-      },
-    },
-    required: ["firstName", "email"],
-  },
-});
-
-// AI will extract and validate according to schema
-const askInfo = route.initialState.transitionTo({
-  chatState: "Please provide your name, email, and age",
-  gather: ["firstName", "email", "age"],
-});
-```
-
-### Conditional Gathering
-
-Use `skipIf` to avoid re-asking for data:
-
-```typescript
-const askDestination = route.initialState.transitionTo({
-  chatState: "Where would you like to go?",
-  gather: ["destination"],
-  // Skip if we already have the destination
-  skipIf: (extracted) => !!extracted.destination,
-});
-
-const askDates = askDestination.transitionTo({
-  chatState: "When would you like to travel?",
-  gather: ["departureDate", "returnDate"],
-  // Skip if we have both dates
-  skipIf: (extracted) => !!extracted.departureDate && !!extracted.returnDate,
-});
-```
-
----
-
-## State Logic
-
-### Skip Conditions
-
-Control when states should be bypassed:
-
-```typescript
-// Skip if data already exists
-const askEmail = route.initialState.transitionTo({
-  chatState: "What's your email?",
-  gather: ["email"],
-  skipIf: (extracted) => !!extracted.email,
-});
-
-// Skip based on business logic
-const askShipping = askEmail.transitionTo({
-  chatState: "What's your shipping address?",
-  gather: ["shippingAddress"],
-  // Skip if user selected digital product
-  skipIf: (extracted) => extracted.productType === "digital",
-});
-
-// Skip based on multiple conditions
-const askBilling = askShipping.transitionTo({
-  chatState: "What's your billing address?",
-  gather: ["billingAddress"],
-  // Skip if billing same as shipping, or already provided
-  skipIf: (extracted) =>
-    extracted.billingSameAsShipping === true || !!extracted.billingAddress,
-});
-```
-
-### Required Data
-
-Ensure prerequisites are met before entering a state:
-
-```typescript
-// Can't search without destination and dates
-const searchFlights = askDates.transitionTo({
-  toolState: searchFlightsTool,
-  requiredData: ["destination", "departureDate"],
-});
-
-// Can't checkout without all required fields
-const processPayment = selectFlight.transitionTo({
-  toolState: processPaymentTool,
-  requiredData: [
-    "destination",
-    "departureDate",
-    "selectedFlight",
-    "paymentMethod",
-  ],
-});
-
-// Multiple prerequisites
-const generateInvoice = processPayment.transitionTo({
-  chatState: "Here's your invoice",
-  requiredData: ["paymentConfirmation", "customerEmail", "bookingReference"],
-});
-```
-
-### State Conditions
-
-AI-evaluated conditions for state selection:
-
-```typescript
-const askIssue = route.initialState.transitionTo({
-  chatState: "What seems to be the problem?",
-  gather: ["issueDescription"],
-});
-
-// Technical support path
-const technicalHelp = askIssue.transitionTo({
-  chatState: "Let me help with your technical issue",
-  condition: "Issue is technical in nature",
-});
-
-// Billing support path
-const billingHelp = askIssue.transitionTo({
-  chatState: "Let me help with your billing issue",
-  condition: "Issue is related to billing or payments",
-});
-
-// General inquiry path
-const generalHelp = askIssue.transitionTo({
-  chatState: "Let me help with your question",
-  condition: "Issue is a general inquiry",
-});
-```
-
----
-
-## State Types
-
-### 1. Chat States
-
-Present information and gather data:
-
-```typescript
-const chat = route.initialState.transitionTo({
-  chatState: "What would you like to know?",
-  gather: ["question"],
-});
-```
-
-**When to use:**
-
-- Ask questions
-- Present information
-- Gather user input
-- Confirm actions
-
-### 2. Tool States
-
-Execute functions:
-
-```typescript
-const tool = route.initialState.transitionTo({
-  toolState: myTool,
-  requiredData: ["param1", "param2"],
-});
-```
-
-**When to use:**
-
-- Call APIs
-- Database operations
-- Complex computations
-- External integrations
-- Data validation/enrichment
-
-### 3. Initial State
-
-Every route's starting point:
-
-```typescript
-route.initialState.configure({
-  description: "Welcome message",
-  gatherFields: ["initialInput"],
-});
-```
-
-**When to configure:**
-
-- Set up welcome messages
-- Gather initial context
-- Set expectations
-- Pre-populate data
-
-### 4. End State (Terminal State)
-
-Every route ends when it reaches `END_STATE`. You can configure what happens at completion:
-
-#### Option A: Route-Level Configuration (Recommended)
-
-```typescript
-import { END_STATE } from "@falai/agent";
-
-const bookingRoute = agent.createRoute({
-  title: "Book Flight",
-
-  // Configure end state behavior
-  endState: {
-    chatState: "Confirm booking and thank the user!",
-    toolState: sendConfirmationEmail,  // Execute final actions
-    gather: ["finalConfirmation"],     // Gather last data
-  },
-});
-
-// Later, just transition to END_STATE
-finalStep.transitionTo({
-  state: END_STATE,
-});
-```
-
-#### Option B: Per-Transition Override
-
-```typescript
-// Override endState for this specific path
-finalStep.transitionTo({
-  chatState: "Special completion message for VIP users!",
-  state: END_STATE,
-});
-```
-
-#### Option C: Default Behavior
-
-If you don't configure `endState`, a smart default completion message is generated:
-
-```typescript
-finalStep.transitionTo({
-  state: END_STATE,
-});
-// Uses default: "Summarize what was accomplished and confirm completion..."
-```
-
-**End State Capabilities:**
-
-```typescript
-endState: {
-  // Completion message instruction
-  chatState?: string;
-
-  // Execute final actions (emails, database updates, etc.)
-  toolState?: ToolRef;
-
-  // Gather final data before completion
-  gather?: string[];
-
-  // Require certain data to be present
-  requiredData?: string[];
-
-  // Custom state ID for debugging
-  id?: string;
-}
-```
-
-**When to use END_STATE:**
-
-- ✅ Route completion - all required data collected
-- ✅ Success outcomes - action completed successfully
-- ✅ Failure outcomes - error handling completed
-- ✅ Before transition - handoff to another route via `onComplete`
-
-**End State with Tools:**
-
-Execute final actions when route completes:
-
-```typescript
-import { defineTool, END_STATE } from "@falai/agent";
-
-const notifyTeam = defineTool("notify_team", async ({ extracted }) => {
-  await slack.send({
-    channel: "#bookings",
-    message: `New booking: ${extracted.hotelName} for ${extracted.guests} guests`,
-  });
-  return { data: "Team notified" };
-});
-
-const bookingRoute = agent.createRoute({
-  endState: {
-    toolState: notifyTeam,  // Runs when route completes
-    chatState: "Booking complete! Our team has been notified.",
-  },
-});
-```
-
-**Key Points:**
-
-- ✅ Configure once at route level (DRY principle)
-- ✅ Can be overridden per-transition if needed
-- ✅ Supports full state capabilities: `chatState`, `toolState`, `gather`, `requiredData`
-- ✅ Automatically generates message if not configured
-- ✅ Executes before `onComplete` route transitions
-
----
-
-## Advanced Patterns
-
-### Pattern 1: State Loops
-
-```typescript
-const askItems = route.initialState.transitionTo({
-  chatState: "What items would you like to add to your cart?",
-  gather: ["newItem"],
-});
-
-const confirmMore = askItems.transitionTo({
-  chatState: "Would you like to add more items?",
-  gather: ["addMore"],
-});
-
-// Loop back to askItems if user wants more
-confirmMore.transitionTo({
-  state: askItems,
-  condition: "User wants to add more items",
-});
-
-// Or continue to checkout
-const checkout = confirmMore.transitionTo({
-  chatState: "Let's proceed to checkout",
-  condition: "User is done adding items",
-});
-```
-
-### Pattern 2: Error Handling States
-
-```typescript
-const processPayment = route.initialState.transitionTo({
-  toolState: paymentTool,
-  requiredData: ["amount", "paymentMethod"],
-});
-
-// Success path
-const paymentSuccess = processPayment.transitionTo({
-  chatState: "Payment successful! Here's your receipt",
-  condition: "Payment was successful",
-});
-
-// Failure path
-const paymentFailed = processPayment.transitionTo({
-  chatState:
-    "Payment failed. Would you like to try a different payment method?",
-  gather: ["retryPayment"],
-  condition: "Payment failed",
-});
-
-// Retry logic
-paymentFailed.transitionTo({
-  state: processPayment,
-  condition: "User wants to retry",
-});
-```
-
-### Pattern 3: Progressive Disclosure
-
-```typescript
-// Start with basic info
-const askBasic = route.initialState.transitionTo({
-  chatState: "Let's start with the basics. What's your name?",
-  gather: ["name"],
-});
-
-// Reveal more options
-const askPreferences = askBasic.transitionTo({
-  chatState: "Great! Now, would you like to customize your experience?",
-  gather: ["wantsCustomization"],
-});
-
-// Only ask detailed questions if user wants customization
-const askDetailed = askPreferences.transitionTo({
-  chatState: "Tell me about your preferences...",
-  gather: ["theme", "notifications", "language"],
-  skipIf: (extracted) => extracted.wantsCustomization === false,
-});
-
-const finish = askDetailed.transitionTo({
-  chatState: "All set! Your account is ready",
-});
-
-// Direct path if no customization
-askPreferences.transitionTo({
-  state: finish,
-  condition: "User doesn't want customization",
-});
-```
-
-### Pattern 4: State Validation
-
-```typescript
-const askAge = route.initialState.transitionTo({
-  chatState: "How old are you?",
-  gather: ["age"],
-});
-
-const validateAge = askAge.transitionTo({
-  toolState: validateAgeTool,
-  requiredData: ["age"],
-});
-
-// Valid age
-const proceed = validateAge.transitionTo({
-  chatState: "Great! Let's continue",
-  condition: "Age is valid",
-});
-
-// Invalid age - loop back
-validateAge.transitionTo({
-  state: askAge,
-  condition: "Age is invalid",
-});
-```
-
-### Pattern 5: Context-Aware States
-
-```typescript
-const askQuestion = route.initialState.transitionTo({
-  chatState: "What would you like to know?",
-  gather: ["question"],
-});
-
-// Different responses based on user type
-const premiumResponse = askQuestion.transitionTo({
-  chatState: "As a premium member, here's detailed information...",
-  condition: "User has premium account",
-});
-
-const basicResponse = askQuestion.transitionTo({
-  chatState: "Here's the basic information. Upgrade for more details!",
-  condition: "User has basic account",
-});
-```
-
----
-
-## State Properties
-
-### Accessing State Properties
-
-```typescript
-const state = route.getState("ask_name");
-
-// State identification
-console.log(state.id); // "state_ask_name_abc123"
-console.log(state.routeId); // "route_onboarding_xyz789"
-console.log(state.description); // "Ask for user's name"
-
-// State configuration
-console.log(state.gatherFields); // ["firstName", "lastName"]
-console.log(state.requiredData); // ["userId"]
-
-// State logic
-if (state.skipIf) {
-  const shouldSkip = state.skipIf(extractedData);
-  console.log("Should skip:", shouldSkip);
-}
-
-// State guidelines
-state.addGuideline({
-  condition: "User provides invalid name",
-  action: "Ask for valid name format",
-});
-console.log(state.getGuidelines());
-
-// Transitions
-console.log(state.getTransitions()); // [Transition, Transition, ...]
-```
-
-### State Reference
-
-```typescript
-const stateRef = state.getRef();
-console.log(stateRef);
-// { id: "state_ask_name_abc123", routeId: "route_onboarding_xyz789" }
-
-// Use reference in transitions
-anotherState.transitionTo({ state: stateRef });
-```
-
----
-
-## Best Practices
-
-### ✅ Do's
-
-- **Use descriptive chatState** - Clear prompts for better UX
-- **Define gather fields** - Explicit data extraction
-- **Use skipIf for efficiency** - Avoid redundant questions
-- **Set requiredData** - Prevent premature execution
-- **Configure initial state** - Proper route entry point
-- **Use tool states for logic** - Separate concerns
-- **Add state-specific guidelines** - Context-aware behavior
-
-### ❌ Don'ts
-
-- **Don't hardcode state IDs** - Let framework generate them
-- **Don't skip validation** - Always validate with requiredData
-- **Don't create circular loops** - Without exit conditions
-- **Don't gather unrelated data** - One concept per state
-- **Don't use vague conditions** - Be specific
-- **Don't forget skipIf** - For pre-populated data
-- **Don't mix chat and tool** - One type per state
-
----
-
-## Troubleshooting
-
-### State Not Being Entered
-
-```typescript
-// ❌ Problem: Required data missing
-const state = prev.transitionTo({
-  chatState: "Do something",
-  requiredData: ["field1", "field2"], // Missing field2
-});
-
-// ✅ Solution: Ensure required data is gathered first
-const gatherData = prev.transitionTo({
-  chatState: "Gather data",
-  gather: ["field1", "field2"],
-});
-
-const state = gatherData.transitionTo({
-  chatState: "Do something",
-  requiredData: ["field1", "field2"], // Now available
-});
-```
-
-### State Always Skipped
-
-```typescript
-// ❌ Problem: skipIf always returns true
-const state = prev.transitionTo({
-  chatState: "Ask something",
-  skipIf: (extracted) => true, // Always skips!
-});
-
-// ✅ Solution: Use proper condition
-const state = prev.transitionTo({
-  chatState: "Ask something",
-  skipIf: (extracted) => !!extracted.field, // Only skip if field exists
-});
-```
-
-### Data Not Being Gathered
-
-```typescript
-// ❌ Problem: Forgot to specify gather
-const state = prev.transitionTo({
-  chatState: "What's your name?",
-  // Missing gather!
-});
-
-// ✅ Solution: Add gather fields
-const state = prev.transitionTo({
-  chatState: "What's your name?",
-  gather: ["firstName", "lastName"],
-});
-```
-
----
-
-## See Also
-
-- [Routes Guide](./ROUTES.md) - Understanding routes
-- [API Reference - State](./API_REFERENCE.md#state) - Complete API docs
-- [Examples](../examples/) - Real-world implementations
-- [Architecture Guide](./ARCHITECTURE.md) - System overview
-
----
-
-**Made with ❤️ for the community**