@falai/agent 0.8.0 → 0.9.0-alpha-1

package/docs/STEPS.md

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