@falai/agent 0.8.1 → 0.9.0-alpha-2

package/docs/core/conversation-flows/route-dsl.md

@@ -0,0 +1,502 @@
+# Route DSL (Domain Specific Language)
+
+The Route DSL provides a fluent, declarative API for designing complex conversation flows. Unlike traditional chatbot frameworks that use rigid state machines, the Route DSL enables natural, branching conversation patterns with intelligent routing.
+
+## Overview
+
+Routes are the building blocks of conversational AI in @falai/agent. Each route represents a journey with:
+
+- **Structured Steps**: Sequential or branching conversation states
+- **Data Collection**: Schema-driven information gathering
+- **Conditional Logic**: Smart skipping and branching based on context
+- **Lifecycle Hooks**: Custom behavior at route and step levels
+
+## Basic Route Creation
+
+### Simple Linear Route
+
+```typescript
+const greetingRoute = agent
+  .createRoute({
+    title: "Greeting Flow",
+    description: "Simple greeting and introduction",
+    initialStep: {
+      prompt: "Hello! What's your name?",
+      collect: ["name"],
+    },
+  })
+  .nextStep({
+    prompt: "Nice to meet you, {{name}}! How can I help you today?",
+    requires: ["name"], // Must have name before proceeding
+  });
+```
+
+### Route with Agent-Level Schema
+
+```typescript
+interface UserInfo {
+  name: string;
+  email: string;
+  interests: string[];
+  preferences?: object;
+  profileComplete?: boolean;
+}
+
+// Agent defines comprehensive schema
+const agent = new Agent<{}, UserInfo>({
+  name: "Profile Assistant",
+  provider: openaiProvider,
+  schema: {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      email: { type: "string", format: "email" },
+      interests: {
+        type: "array",
+        items: { type: "string" },
+      },
+      preferences: { type: "object" },
+      profileComplete: { type: "boolean" }
+    },
+    required: ["name", "email"],
+  }
+});
+
+// Route specifies required fields instead of schema
+const userProfileRoute = agent
+  .createRoute({
+    title: "User Profile Collection",
+    description: "Collect basic user information",
+    requiredFields: ["name", "email", "interests"], // Required for completion
+    optionalFields: ["preferences"], // Nice to have
+    initialStep: {
+      prompt: "Let's create your profile. What's your name?",
+      collect: ["name"],
+    },
+  })
+  .nextStep({
+    prompt: "Great, {{name}}! What's your email address?",
+    collect: ["email"],
+    requires: ["name"], // Prerequisites from agent data
+  })
+  .nextStep({
+    prompt: "What are your interests? (comma-separated)",
+    collect: ["interests"],
+    requires: ["name", "email"], // Prerequisites from agent data
+  });
+```
+
+## Step Configuration
+
+### Step Options
+
+Each step supports comprehensive configuration:
+
+```typescript
+interface StepOptions<TContext, TData> {
+  id?: string; // Optional custom ID
+  description?: string; // Human-readable description
+  prompt?: Template<TContext, TData>; // AI prompt template
+  collect?: string[]; // Fields to extract from AI response
+  skipIf?: (data: Partial<TData>) => boolean; // Skip condition
+  requires?: string[]; // Required data fields
+  when?: Template<TContext, TData>; // Conditional execution
+  prepare?: (context: TContext, data?: Partial<TData>) => void | Promise<void>;
+  finalize?: (context: TContext, data?: Partial<TData>) => void | Promise<void>;
+  tools?: (string | Tool<TContext, unknown[], unknown, TData>)[];
+}
+```
+
+### Data Collection Steps
+
+```typescript
+const dataCollectionStep = {
+  prompt: "What's your preferred contact method?",
+  collect: ["contactMethod"], // Maps to agent schema field
+  requires: ["name", "email"], // Must have these fields from agent data
+  skipIf: (data) => data.contactMethod !== undefined, // Skip if already collected by any route
+};
+```
+
+### Conditional Steps
+
+```typescript
+const conditionalStep = {
+  prompt: "Would you like to receive our newsletter?",
+  collect: ["newsletterOptIn"],
+  when: "if user has provided email address", // AI-evaluated condition
+  skipIf: (data) => data.email === undefined, // Skip if no email
+};
+```
+
+### Lifecycle Hooks
+
+```typescript
+const stepWithHooks = {
+  prompt: "Processing your request...",
+  prepare: async (context, data) => {
+    // Run before AI responds
+    console.log("Preparing step with data:", data);
+    // Could fetch external data, validate state, etc.
+  },
+  finalize: async (context, data) => {
+    // Run after AI responds and data is collected
+    console.log("Step completed with data:", data);
+    // Could save to database, trigger notifications, etc.
+  },
+};
+```
+
+## Branching and Non-Linear Flows
+
+### Basic Branching
+
+```typescript
+const branchingRoute = agent
+  .createRoute({
+    title: "Support Flow",
+    initialStep: {
+      prompt: "How can I help you today?",
+      collect: ["intent"],
+    },
+  })
+  .branch([
+    {
+      name: "technical",
+      step: {
+        prompt:
+          "I understand you're having a technical issue. Can you describe the problem?",
+        collect: ["problem"],
+        requires: ["intent"],
+        when: "if intent indicates technical support",
+      },
+    },
+    {
+      name: "billing",
+      step: {
+        prompt: "For billing questions, I'll need your account information...",
+        collect: ["accountInfo"],
+        requires: ["intent"],
+        when: "if intent indicates billing or payment",
+      },
+    },
+    {
+      name: "general",
+      step: {
+        prompt: "I'd be happy to help with general questions...",
+        collect: ["question"],
+        requires: ["intent"],
+      },
+    },
+  ]);
+```
+
+### Accessing Branch Results
+
+```typescript
+const routeWithBranches = agent
+  .createRoute({
+    title: "Complex Flow",
+  })
+  .branch([
+    {
+      name: "optionA",
+      step: { prompt: "Choose option A", collect: ["choiceA"] },
+    },
+    {
+      name: "optionB",
+      step: { prompt: "Choose option B", collect: ["choiceB"] },
+    },
+  ]);
+
+// Access specific branches for further chaining
+const optionA = routeWithBranches.branches.optionA.nextStep({
+  prompt: "You chose A. What's next?",
+  requires: ["choiceA"],
+});
+
+const optionB = routeWithBranches.branches.optionB.nextStep({
+  prompt: "You chose B. What's next?",
+  requires: ["choiceB"],
+});
+```
+
+## Route Completion and Transitions
+
+### Basic Route Completion
+
+```typescript
+const simpleRoute = agent
+  .createRoute({
+    title: "Simple Task",
+    initialStep: { prompt: "What task should I help with?", collect: ["task"] },
+  })
+  .nextStep({
+    prompt: "I'll help you with: {{task}}",
+    requires: ["task"],
+  })
+  .endRoute({
+    prompt: "Task completed! Is there anything else I can help with?",
+  });
+```
+
+### Automatic Transitions
+
+```typescript
+const onboardingRoute = agent
+  .createRoute({
+    title: "User Onboarding",
+    initialStep: { prompt: "Welcome! What's your name?", collect: ["name"] },
+  })
+  .nextStep({
+    prompt: "Thanks {{name}}! Let's set up your profile.",
+    collect: ["profileComplete"],
+    requires: ["name"],
+  })
+  .endRoute({
+    prompt: "Onboarding complete! Ready to explore?",
+  });
+
+// Automatically transition to another route when complete
+onboardingRoute.onComplete = "main-menu"; // Route ID or title
+```
+
+### Conditional Transitions
+
+```typescript
+const purchaseRoute = agent
+  .createRoute({
+    title: "Purchase Flow",
+    initialStep: {
+      prompt: "What would you like to purchase?",
+      collect: ["item"],
+    },
+  })
+  .nextStep({
+    prompt: "Great choice! Processing {{item}}...",
+    collect: ["purchaseComplete"],
+    requires: ["item"],
+  })
+  .endRoute();
+
+purchaseRoute.onComplete = {
+  nextStep: "feedback-collection", // Transition target
+  condition: "if purchase was successful", // AI-evaluated condition
+};
+```
+
+### Dynamic Transitions
+
+```typescript
+purchaseRoute.onComplete = async (session, context) => {
+  // Custom logic for determining next route
+  if (session.data?.purchaseComplete) {
+    return "feedback-collection";
+  } else if (session.data?.error) {
+    return "error-recovery";
+  } else {
+    return "support";
+  }
+};
+```
+
+## Advanced Route Features
+
+### Route-Level Configuration
+
+```typescript
+const advancedRoute = agent.createRoute({
+  title: "Advanced Interaction",
+  description: "Complex multi-step conversation",
+
+  // Route completion requirements
+  requiredFields: ["customerName", "email", "issueType"],
+  optionalFields: ["phone", "priority"],
+
+  // Route-level identity overrides agent identity
+  identity: "You are an expert consultant specializing in {{domain}}",
+
+  // Behavioral guidelines for this route
+  guidelines: [
+    {
+      condition: "if user is frustrated",
+      action: "Be extra patient and offer specific solutions",
+    },
+  ],
+
+  // Domain-specific terms
+  terms: [
+    {
+      name: "ROI",
+      description: "Return on Investment - the financial benefit gained",
+      synonyms: ["return on investment", "profitability"],
+    },
+  ],
+
+  // Initial data to pre-populate (maps to agent schema)
+  initialData: {
+    sessionId: generateId(),
+    startTime: new Date().toISOString(),
+  },
+
+  // Route-level lifecycle hooks (work with agent data)
+  hooks: {
+    onDataUpdate: (newData, previousData) => {
+      // Validate or enrich agent-level collected data
+      if (newData.email && !isValidEmail(newData.email)) {
+        throw new Error("Invalid email format");
+      }
+      
+      // Auto-set priority based on issue type
+      if (newData.issueType === 'billing' && !newData.priority) {
+        newData.priority = 'high';
+      }
+      
+      return newData;
+    },
+    onContextUpdate: (newContext, previousContext) => {
+      // React to context changes
+      console.log("Context updated:", { previousContext, newContext });
+    },
+  },
+});
+```
+
+### Sequential Step Building
+
+```typescript
+const sequentialRoute = agent.createRoute({
+  title: "Sequential Process",
+  steps: [
+    {
+      description: "Step 1: Initial assessment",
+      prompt: "Let's start with some basic information...",
+      collect: ["basicInfo"],
+    },
+    {
+      description: "Step 2: Detailed requirements",
+      prompt: "Now I need more specific details...",
+      collect: ["detailedInfo"],
+      requires: ["basicInfo"],
+      skipIf: (data) => data.skipDetailed, // Allow skipping if condition met
+    },
+    {
+      description: "Step 3: Confirmation",
+      prompt: "Please confirm the following details...",
+      collect: ["confirmed"],
+      requires: ["basicInfo"], // Note: detailedInfo not required due to skipIf
+    },
+  ],
+});
+```
+
+## Route Management
+
+### Route Registration
+
+```typescript
+const agent = new Agent({
+  name: "Multi-Purpose Assistant",
+  provider: openaiProvider,
+  routes: [greetingRoute, supportRoute, purchaseRoute],
+});
+
+// Or add routes dynamically
+agent.createRoute(salesRoute);
+agent.createRoute(feedbackRoute);
+```
+
+### Route Access and Inspection
+
+```typescript
+// Get all routes
+const allRoutes = agent.getRoutes();
+
+// Find specific route
+const supportRoute = agent.getRoutes().find((r) => r.id === "support");
+
+// Inspect route structure
+console.log(supportRoute.describe());
+```
+
+## Best Practices
+
+### Route Design
+
+1. **Single Responsibility**: Each route should serve one clear user intent
+2. **Progressive Disclosure**: Collect information in logical order
+3. **Fail Fast**: Use `requires` to prevent invalid state transitions
+4. **Smart Skipping**: Use `skipIf` to avoid redundant questions
+
+### Step Design
+
+1. **Clear Prompts**: Make step purposes obvious to both AI and users
+2. **Minimal Collection**: Only collect what's needed for the current step
+3. **Validation**: Use lifecycle hooks for data validation
+4. **Error Handling**: Plan for edge cases and invalid inputs
+
+### Performance
+
+1. **Limit Branching**: Too many branches increase AI evaluation complexity
+2. **Optimize Conditions**: Use efficient `skipIf` and `requires` logic
+3. **Cache Data**: Avoid redundant data fetching in lifecycle hooks
+4. **Monitor Usage**: Track route completion rates and drop-off points
+
+### Maintainability
+
+1. **Descriptive Names**: Use clear route and step IDs
+2. **Documentation**: Add descriptions to routes and complex steps
+3. **Modular Design**: Break complex routes into smaller, focused routes
+4. **Version Control**: Plan for route evolution and backward compatibility
+
+## Debugging and Testing
+
+### Route Inspection
+
+```typescript
+// Get detailed route structure
+console.log(route.describe());
+
+// Inspect all steps
+const steps = route.getAllSteps();
+steps.forEach((step) => {
+  console.log(`Step: ${step.id} - ${step.description}`);
+  console.log(
+    `Transitions:`,
+    step.getTransitions().map((s) => s.id)
+  );
+});
+```
+
+### Step Validation
+
+```typescript
+// Test skipIf conditions
+const shouldSkip = step.shouldSkip(collectedData);
+
+// Test requirements
+const hasRequirements = step.hasRequires(collectedData);
+```
+
+### Route Testing
+
+```typescript
+// Simulate route execution
+const mockSession = createSession();
+const mockHistory = [
+  {
+    role: "user",
+    content: "Hello",
+  },
+];
+
+const response = await agent.respond({
+  history: mockHistory,
+  session: mockSession,
+});
+
+console.log("Route selected:", response.session.currentRoute?.title);
+console.log("Data collected:", response.session.data);
+```
+
+The Route DSL transforms conversation design from rigid, hardcoded flows into flexible, intelligent systems that can adapt to user needs while maintaining structure and reliability.

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

@@ -0,0 +1,117 @@
+# Routes
+
+Routes define conversational journeys in @falai/agent with agent-level data collection. This document covers route definition with required fields, lifecycle management, and completion handling based on data availability.
+
+## Overview
+
+Routes represent complete conversational workflows that guide users through specific tasks or processes. Each route specifies required fields for completion, consists of steps that collect data into the agent-level schema, and can complete when their data requirements are satisfied regardless of which route collected the data.
+
+## Route Definition with Required Fields
+
+```typescript
+// Agent defines comprehensive schema
+interface HotelData {
+  destination: string;
+  checkIn: string;
+  checkOut: string;
+  guests: number;
+  roomType?: string;
+  customerName?: string;
+  email?: string;
+  phone?: string;
+  specialRequests?: string;
+}
+
+const agent = new Agent<{}, HotelData>({
+  name: "Hotel Booking Agent",
+  schema: {
+    type: "object",
+    properties: {
+      destination: { type: "string" },
+      checkIn: { type: "string", format: "date" },
+      checkOut: { type: "string", format: "date" },
+      guests: { type: "number", minimum: 1 },
+      roomType: { type: "string" },
+      customerName: { type: "string" },
+      email: { type: "string", format: "email" },
+      phone: { type: "string" },
+      specialRequests: { type: "string" }
+    }
+  }
+});
+
+// Routes specify required fields instead of schemas
+const bookingRoute = agent.createRoute({
+  title: "Hotel Booking",
+  description: "Help users book hotel accommodations",
+  conditions: ["User wants to book a hotel"],
+  requiredFields: ["destination", "checkIn", "checkOut", "guests", "customerName", "email"],
+  optionalFields: ["roomType", "phone", "specialRequests"]
+});
+
+const customerServiceRoute = agent.createRoute({
+  title: "Customer Service",
+  description: "Help with booking issues",
+  conditions: ["User needs help with existing booking"],
+  requiredFields: ["customerName", "email"], // Minimal requirements
+  optionalFields: ["phone", "destination"]
+});
+```
+
+## Route Lifecycle
+
+Routes have a complete lifecycle from creation through execution to completion based on data availability.
+
+### Route Creation
+
+Routes are created using the agent's `createRoute()` method with required fields specifications that reference the agent-level schema.
+
+### Route Execution
+
+Routes are selected by the AI routing system based on user intent and conversation context, with access to all agent-level data.
+
+### Route Completion
+
+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.
+
+```typescript
+// Route completion evaluation
+const isComplete = bookingRoute.isComplete(agent.getCollectedData());
+const missingFields = bookingRoute.getMissingRequiredFields(agent.getCollectedData());
+const progress = bookingRoute.getCompletionProgress(agent.getCollectedData()); // 0-1
+
+console.log(`Booking route is ${Math.round(progress * 100)}% complete`);
+if (missingFields.length > 0) {
+  console.log(`Still need: ${missingFields.join(', ')}`);
+}
+```
+
+## 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.
+
+```typescript
+const bookingRoute = agent.createRoute({
+  title: "Hotel Booking",
+  requiredFields: ["destination", "checkIn", "checkOut", "guests", "customerName", "email"],
+  onComplete: "Feedback Collection", // Transition to feedback route
+});
+
+const feedbackRoute = agent.createRoute({
+  title: "Feedback Collection",
+  requiredFields: ["customerName", "email", "rating"], // Already has name and email from booking
+  optionalFields: ["comments"]
+});
+
+// When booking completes, feedback route is already 2/3 complete
+```
+
+## Best Practices
+
+- Use descriptive titles and conditions for better AI routing
+- Define comprehensive agent-level schemas for type safety across all routes
+- Specify minimal required fields for faster route completion
+- Use optional fields to enhance user experience without blocking completion
+- Implement appropriate completion handlers that leverage shared data
+- Consider route transitions for multi-step workflows with data continuity
+- Design routes that can benefit from cross-route data sharing