@falai/agent 0.8.1 → 0.9.0-alpha-2

package/docs/core/routing/intelligent-routing.md

@@ -0,0 +1,348 @@
+# Intelligent Routing System
+
+The AI routing system is the core intelligence layer of @falai/agent that enables dynamic, context-aware conversation flows. Unlike traditional state machines, the routing system uses AI to intelligently select routes and steps based on user intent, conversation history, and collected data.
+
+## Overview
+
+The `RoutingEngine` class powers two key decision-making processes:
+
+1. **Route Selection**: When multiple routes are available, AI analyzes the conversation to score and select the most appropriate route
+2. **Step Selection**: Within an active route, AI determines the best next step from available candidates
+
+## How It Works
+
+### Route Selection Process
+
+When an agent has multiple routes defined, the routing engine:
+
+1. **Analyzes Context**: Evaluates conversation history, user intent, and current session state
+2. **Scores Routes**: Uses AI to score each route (0-100) based on relevance and semantic fit
+3. **Applies Thresholds**: Considers switching costs and maintains conversation continuity
+4. **Selects Winner**: Chooses the highest-scoring route or stays with the current route
+
+### Step Selection Process
+
+Within an active route, the routing engine:
+
+1. **Finds Candidates**: Traverses the step chain to identify valid next steps
+2. **Evaluates Conditions**: Respects `skipIf` conditions and `requires` dependencies
+3. **AI Decision**: When multiple candidates exist, uses AI to select the optimal step
+4. **Handles Completion**: Detects route completion and manages transitions
+
+## Key Features
+
+### Intelligent Route Scoring
+
+Routes are scored based on multiple factors:
+
+```typescript
+// Routes receive scores 0-100 based on:
+- Explicit keyword matches (90-100)
+- Contextual evidence (70-89)
+- Moderate relevance (50-69)
+- Weak connections (30-49)
+- Minimal relevance (0-29)
+```
+
+### Smart Step Traversal
+
+The system intelligently traverses step chains:
+
+- **Skip Logic**: Automatically skips steps where `skipIf` conditions are met
+- **Dependency Checking**: Ensures required data is present before allowing step progression
+- **Loop Prevention**: Uses visited sets to prevent infinite traversal
+- **Branch Resolution**: Handles complex branching logic with AI assistance
+
+### Context-Aware Decisions
+
+All routing decisions consider:
+
+- **Conversation History**: Full dialogue context
+- **Agent-Level Data**: Centralized information gathered across all routes
+- **Session State**: Current route and step position with cross-route data access
+- **Route Completion**: Progress toward required fields for each route
+- **Agent Knowledge**: Guidelines, terms, and domain knowledge
+
+## Route Selection API
+
+### Single Route Optimization
+
+For agents with only one route, the system optimizes by skipping expensive route scoring:
+
+```typescript
+// Single route - direct step selection
+const result = await routingEngine.decideSingleRouteStep({
+  route: userOnboardingRoute,
+  session,
+  history,
+  agentOptions,
+  provider,
+  context,
+});
+```
+
+### Multi-Route Orchestration
+
+For complex agents with multiple routes:
+
+```typescript
+// Multiple routes - full AI-powered selection
+const result = await routingEngine.decideRouteAndStep({
+  routes: [onboardingRoute, supportRoute, salesRoute],
+  session,
+  history,
+  agentOptions,
+  provider,
+  context,
+});
+```
+
+## Step Candidate Logic
+
+### Finding Valid Steps
+
+The `getCandidateSteps()` method implements sophisticated logic:
+
+```typescript
+// Find valid next steps considering:
+const candidates = routingEngine.getCandidateSteps(
+  route, // Current route
+  currentStep, // Current step (or null for route start)
+  agentData // Agent-level data collected across all routes
+);
+```
+
+### SkipIf Processing
+
+Steps are automatically filtered based on agent-level data conditions:
+
+```typescript
+// Step definition with skipIf using agent data
+initialStep: {
+  prompt: "What's your name?",
+  collect: ["name"],
+  skipIf: (data) => data.name !== undefined  // Skip if name already collected by any route
+}
+
+// Cross-route skipping example
+const emailStep = {
+  prompt: "What's your email?",
+  collect: ["email"],
+  skipIf: (data) => data.email !== undefined  // Skip if collected in different route
+}
+```
+
+### Recursive Traversal
+
+The system recursively traverses step chains to find valid paths:
+
+```typescript
+// Handles complex scenarios like:
+// Step A (skipIf: condition) -> Step B -> Step C (requires: data)
+// If Step A is skipped, system continues to Step B, then evaluates Step C
+```
+
+## Prompt Engineering
+
+### Route Selection Prompts
+
+The system builds comprehensive prompts for route selection:
+
+```typescript
+const routingPrompt = await routingEngine.buildRoutingPrompt({
+  history,
+  routes,
+  lastMessage,
+  agentOptions,
+  session,
+  activeRouteSteps,
+  context,
+});
+```
+
+Prompts include:
+
+- Agent identity and personality
+- Available routes with descriptions and required fields
+- Session context and agent-level collected data
+- Route completion progress (e.g., "2/3 required fields collected")
+- Scoring guidelines (90-100 scale)
+- Conversation history and directives
+
+### Step Selection Prompts
+
+For step selection within routes:
+
+```typescript
+const stepPrompt = await routingEngine.buildStepSelectionPrompt({
+  route,
+  currentStep,
+  candidates,
+  data: agent.getCollectedData(), // Agent-level data
+  history,
+  lastMessage,
+  agentOptions,
+  context,
+  session,
+});
+```
+
+## Response Processing
+
+### Structured Scoring
+
+AI responses use JSON schemas for reliable parsing:
+
+```typescript
+// Route scoring schema
+{
+  context: "Brief summary of user intent",
+  routes: {
+    "route-id-1": 85,  // Score 0-100
+    "route-id-2": 72,
+    "route-id-3": 45
+  },
+  responseDirectives: ["Focus on pricing", "Be helpful"]
+}
+```
+
+### Step Selection Schema
+
+```typescript
+// Step selection schema
+{
+  reasoning: "Why this step was selected",
+  selectedStepId: "step-id",
+  responseDirectives: ["Address concerns", "Provide options"]
+}
+```
+
+## Integration with Agent Flow
+
+### Response Pipeline Integration
+
+The routing engine integrates seamlessly with the response pipeline:
+
+```typescript
+// In Agent.respondStream():
+1. Prepare context and session
+2. Call routingEngine.decideRouteAndStep()
+3. Execute prepare() functions on current step
+4. Generate AI response with selected route/step
+5. Process tool calls and data collection
+6. Handle route completion and transitions
+```
+
+### Session State Management
+
+Routing decisions update session state:
+
+```typescript
+// Session updates include:
+- Current route transitions
+- Step progression
+- Initial data merging
+- Route completion handling
+- Pending transition management
+```
+
+## Performance Optimizations
+
+### Single Route Fast Path
+
+For agents with one route, skips route scoring entirely:
+
+```typescript
+if (routes.length === 1) {
+  return this.decideSingleRouteStep(/* optimized path */);
+}
+```
+
+### Candidate Limiting
+
+Applies configurable limits to prevent excessive AI calls:
+
+```typescript
+const limited = maxCandidates ? entries.slice(0, maxCandidates) : entries;
+```
+
+## Error Handling & Resilience
+
+### Backup Model Support
+
+When primary AI models fail, automatically tries backup models:
+
+```typescript
+// Automatic fallback to backup models
+// Error classification (rate limits, overloads, etc.)
+// Timeout and retry logic
+```
+
+### Validation & Fallbacks
+
+Robust validation ensures system stability:
+
+```typescript
+// Invalid responses fallback to first candidate
+// Missing data handled gracefully
+// Circular dependencies prevented
+```
+
+## Configuration Options
+
+### Routing Engine Options
+
+```typescript
+const routingEngine = new RoutingEngine({
+  allowRouteSwitch: true, // Allow switching between routes
+  switchThreshold: 70, // Minimum score to switch routes
+  maxCandidates: 5, // Limit AI evaluation candidates
+});
+```
+
+## Best Practices
+
+### Route Design
+
+1. **Clear Conditions**: Define specific conditions for route activation
+2. **Distinct Purposes**: Ensure routes serve different user intents
+3. **Progressive Disclosure**: Use step dependencies to control information flow
+4. **Completion Handling**: Define clear end states and transitions
+
+### Step Design
+
+1. **Atomic Actions**: Each step should accomplish one clear goal
+2. **Smart Skipping**: Use `skipIf` to avoid redundant questions
+3. **Data Dependencies**: Use `requires` to enforce logical flow
+4. **Branch Wisely**: AI can handle branching but prefer linear flows when possible
+
+### Performance
+
+1. **Limit Routes**: Too many routes increase AI evaluation time
+2. **Optimize Prompts**: Keep route/step descriptions concise
+3. **Cache Context**: Reuse context when possible
+4. **Monitor Scores**: Track route selection accuracy and adjust conditions
+
+## Debugging & Monitoring
+
+### Route Selection Logging
+
+```typescript
+// Debug logging shows:
+- Route scores and reasoning
+- Selected routes and steps
+- Candidate evaluation process
+- Context analysis results
+```
+
+### Performance Metrics
+
+```typescript
+// Track:
+- Route selection accuracy
+- Step transition success rates
+- AI call latency and costs
+- User satisfaction scores
+```
+
+The intelligent routing system transforms traditional conversation design from static flows into dynamic, AI-driven experiences that adapt to user needs and context.

package/docs/core/tools/tool-definition.md

@@ -0,0 +1,346 @@
+# Tool Definition
+
+Tools in @falai/agent enable AI agents to execute custom logic, access external APIs, and perform actions during conversations. This document covers tool creation, configuration, and integration.
+
+## Overview
+
+Tools provide a way for agents to:
+
+- Execute business logic and API calls
+- Access external services and databases
+- Perform calculations and data transformations
+- Update conversation context and session data
+
+## Tool Creation
+
+Tools are created as objects implementing the `Tool` interface:
+
+```typescript
+import { Tool } from "@falai/agent";
+
+const weatherTool: Tool<unknown, WeatherData, [], string> = {
+  id: "get_weather",
+  name: "Weather Forecast", // Human-readable name shown to AI models
+  description: "Get current weather and forecast for a location",
+  parameters: {
+    type: "object",
+    properties: {
+      location: { type: "string", description: "City or location name" },
+      date: { type: "string", description: "Date for forecast (YYYY-MM-DD)" },
+    },
+    required: ["location"],
+  },
+  handler: async ({ location, date }) => {
+    const weather = await weatherAPI.getForecast(location, date);
+    return {
+      data: `The weather in ${location} on ${date} is ${weather.condition}`,
+      contextUpdate: {
+        currentWeather: weather,
+        lastWeatherCheck: new Date().toISOString(),
+      },
+    };
+  },
+};
+```
+
+## Tool Name
+
+The optional `name` field provides a human-readable name for the tool that is displayed to AI models. When provided, this name takes precedence over the `id` field in AI provider interactions:
+
+```typescript
+const calculatorTool: Tool<unknown, CalcData, [], string> = {
+  id: "math_calculator", // Internal identifier
+  name: "Math Calculator", // Display name for AI models
+  description: "Perform mathematical calculations",
+  // ... rest of tool definition
+};
+```
+
+**Benefits:**
+
+- **Better AI Understanding**: Clear, descriptive names help AI models choose appropriate tools
+- **User-Friendly**: More readable than cryptic IDs in AI responses and logs
+- **Backward Compatible**: Falls back to `id` if `name` is not provided
+- **Flexible**: Allows separation of internal IDs from user-facing names
+
+## Tool Parameters
+
+Tool parameters are defined using JSON Schema:
+
+```typescript
+const searchTool: Tool<unknown, SearchData, [], string> = {
+  id: "web_search",
+  name: "Web Search Engine",
+  description: "Search the web for information",
+  parameters: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Search query",
+        minLength: 1,
+        maxLength: 200,
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of results",
+        minimum: 1,
+        maximum: 50,
+        default: 10,
+      },
+    },
+    required: ["query"],
+  },
+  handler: async ({ query, limit = 10 }) => {
+    const results = await searchAPI.query(query, limit);
+    return {
+      data: `Found ${results.length} results for "${query}"`,
+      contextUpdate: { searchResults: results },
+    };
+  },
+};
+```
+
+## Tool Execution Context
+
+Tools receive execution context including:
+
+- **Current context** - Agent and route context
+- **Session data** - Collected conversation data
+- **Route information** - Current route and step details
+
+```typescript
+const userProfileTool: Tool<unknown, UserData, [], string> = {
+  id: "get_user_profile",
+  description: "Retrieve user profile information",
+  parameters: {
+    type: "object",
+    properties: {
+      userId: {
+        type: "string",
+        description: "User ID (optional, uses context if not provided)",
+      },
+    },
+  },
+  handler: async (toolContext, args) => {
+    // Access current context
+    const currentUserId = toolContext.context.userId || args.userId;
+
+    // Access collected data
+    const preferences = toolContext.data.userPreferences;
+
+    const profile = await userAPI.getProfile(currentUserId);
+    return {
+      data: `Retrieved profile for ${profile.name}`,
+      dataUpdate: { userProfile: profile },
+    };
+  },
+};
+```
+
+## Tool Response Format
+
+Tools return structured responses with multiple components:
+
+```typescript
+interface ToolResult {
+  success: boolean;
+  result?: {
+    data: unknown; // User-visible result
+    contextUpdate?: Partial<TContext>; // Context modifications
+    dataUpdate?: Partial<TData>; // Session data updates
+  };
+  error?: string; // Error message if failed
+}
+```
+
+## Context Updates
+
+Tools can modify conversation context:
+
+```typescript
+const locationTool: Tool<unknown, LocationData, [], string> = {
+  id: "set_location",
+  description: "Update the user's location in context",
+  parameters: {
+    type: "object",
+    properties: {
+      location: { type: "string", description: "New location" },
+    },
+    required: ["location"],
+  },
+  handler: async (toolContext, args) => {
+    return {
+      data: `Location set to ${args.location}`,
+      contextUpdate: {
+        currentLocation: args.location,
+        locationSetAt: new Date().toISOString(),
+        locationHistory: (prev: string[]) => [...(prev || []), args.location],
+      },
+    };
+  },
+};
+```
+
+## Data Collection Updates
+
+Tools can update session data collected during conversation:
+
+```typescript
+const validationTool: Tool<unknown, BookingData, [], string> = {
+  id: "validate_booking",
+  description: "Validate booking information and update session data",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: async (toolContext) => {
+    const validation = await bookingAPI.validate(toolContext.data.bookingInfo);
+
+    if (!validation.valid) {
+      return {
+        data: `Booking validation failed: ${validation.errors.join(", ")}`,
+        dataUpdate: {
+          bookingErrors: validation.errors,
+          bookingValid: false,
+        },
+      };
+    }
+
+    return {
+      data: "Booking validated successfully",
+      dataUpdate: {
+        bookingValid: true,
+        validatedAt: new Date().toISOString(),
+      },
+    };
+  },
+};
+```
+
+## Error Handling
+
+Tools should handle errors gracefully:
+
+```typescript
+const apiTool: Tool<unknown, ApiData, [], string> = {
+  id: "call_external_api",
+  description: "Call an external API endpoint",
+  parameters: {
+    type: "object",
+    properties: {
+      endpoint: { type: "string", description: "API endpoint to call" },
+    },
+    required: ["endpoint"],
+  },
+  handler: async (toolContext, args) => {
+    try {
+      const result = await externalAPI.call(args.endpoint);
+      return {
+        data: `API call successful: ${result}`,
+      };
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : "Unknown error";
+      return {
+        data: `API call failed: ${errorMessage}`,
+        contextUpdate: { lastApiError: errorMessage },
+      };
+    }
+  },
+};
+```
+
+## Tool Scoping
+
+Tools can be registered at different levels:
+
+### Agent-Level Tools
+
+Available to all routes and steps:
+
+```typescript
+const agent = new Agent({
+  name: "Assistant",
+  provider: openaiProvider,
+  tools: [globalSearchTool, userManagementTool],
+});
+```
+
+### Route-Level Tools
+
+Available only within specific routes:
+
+```typescript
+const supportRoute = agent.createRoute({
+  title: "Customer Support",
+  tools: [ticketCreationTool, knowledgeBaseTool],
+});
+```
+
+### Step-Level Tools
+
+Available only in specific steps:
+
+```typescript
+const bookingStep = route.initialStep.nextStep({
+  prompt: "Ready to book?",
+  tools: [paymentProcessingTool],
+  requires: ["bookingDetails"],
+});
+```
+
+## Tool Resolution Priority
+
+When multiple tools with the same name exist, priority is:
+
+1. **Step-level tools** (highest priority)
+2. **Route-level tools**
+3. **Agent-level tools** (lowest priority)
+
+## Async Tools
+
+Tools support async operations and Promises:
+
+```typescript
+const asyncTool: Tool<unknown, ProcessingData, [], string> = {
+  id: "process_data",
+  description: "Process data asynchronously with heavy computation",
+  parameters: {
+    type: "object",
+    properties: {
+      data: { type: "object", description: "Data to process" },
+    },
+    required: ["data"],
+  },
+  handler: async (toolContext, args) => {
+    // Simulate async processing
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    const processed = await heavyComputation(args.data);
+
+    return {
+      data: "Data processed successfully",
+      dataUpdate: { processedData: processed },
+    };
+  },
+};
+```
+
+## Tool Validation
+
+Tools are validated at registration time:
+
+- **Schema validation** - Parameter schemas must be valid JSON Schema
+- **Type checking** - TypeScript types must match schemas
+- **Name uniqueness** - Tool names must be unique within scope
+
+## Best Practices
+
+- **Keep tools focused** - Each tool should do one thing well
+- **Use descriptive names** - Tool names should be clear and specific
+- **Handle errors gracefully** - Provide meaningful error messages
+- **Leverage context updates** - Use context to maintain conversation state
+- **Validate parameters** - Use JSON Schema constraints effectively
+- **Consider performance** - Avoid long-running operations when possible
+- **Document thoroughly** - Provide clear descriptions for AI usage