@falai/agent 1.2.8 → 2.0.1

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

@@ -1,470 +0,0 @@
-# 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
-
-## Enhanced Condition System
-
-### ConditionTemplate for Routes and Steps
-
-The routing system now supports the powerful `ConditionTemplate` type for both route activation and step control:
-
-```typescript
-// Route with mixed condition types
-agent.createRoute({
-  title: "Premium Support",
-  when: [
-    "User needs premium or priority support", // AI context
-    (ctx) => ctx.context?.accountTier === 'premium' // Programmatic check
-  ],
-  skipIf: [
-    "Support system is under maintenance", // AI context
-    (ctx) => ctx.context?.maintenanceMode === true // Programmatic check
-  ],
-  steps: [
-    {
-      id: "priority_greeting",
-      when: "User should receive priority treatment", // AI context only
-      prompt: "Welcome to premium support! How can I assist you today?",
-      collect: ["issueType"]
-    },
-    {
-      id: "technical_help",
-      when: [
-        "User needs technical assistance", // AI context
-        (ctx) => ctx.data?.issueType === 'technical' // Programmatic check
-      ],
-      skipIf: (ctx) => ctx.data?.issueResolved === true, // Function-only skipIf
-      prompt: "Let me help you with your technical issue",
-      collect: ["issueDescription"]
-    }
-  ]
-});
-```
-
-### Condition Evaluation Logic
-
-**Route `when` conditions (AND logic):**
-- All function conditions must return `true`
-- String conditions provide AI context for route scoring
-- Arrays require all functions to pass
-
-**Route `skipIf` conditions (OR logic):**
-- Any function returning `true` excludes the route
-- String conditions provide AI context about exclusion reasons
-- Arrays skip if any function returns `true`
-
-**Step `when` conditions (AND logic):**
-- All function conditions must return `true` for step to be eligible
-- String conditions help AI understand step purpose
-- Arrays require all functions to pass
-
-**Step `skipIf` conditions (OR logic):**
-- Any function returning `true` skips the step
-- String conditions provide AI context about why step is skipped
-- Arrays skip if any function returns `true`
-
-### Hybrid Evaluation Process
-
-The routing engine now performs a two-phase evaluation:
-
-1. **Programmatic Phase**: Execute all function conditions for boolean results
-2. **AI Context Phase**: Include string conditions in AI prompts for intelligent decision-making
-
-```typescript
-// Example evaluation flow:
-const routeCondition = [
-  "User wants to upgrade their account", // → AI context
-  (ctx) => ctx.context?.accountTier !== 'enterprise' // → Must be true
-];
-
-// Programmatic: Check if user can upgrade (not already enterprise)
-// AI Context: "User wants to upgrade their account" helps AI understand intent
-// Result: Route eligible if function passes AND AI scores it highly
-```
-
-### Context-Aware Routing
-
-Conditions can access comprehensive context:
-
-```typescript
-interface RoutingContext {
-  userId: string;
-  accountTier: 'free' | 'premium' | 'enterprise';
-  supportHistory: SupportTicket[];
-  currentTime: Date;
-}
-
-interface AgentData {
-  customerName?: string;
-  issueType?: string;
-  priority?: 'low' | 'medium' | 'high';
-  previousAttempts?: number;
-}
-
-// Route with context-aware conditions
-agent.createRoute({
-  title: "Escalation Support",
-  when: [
-    "User needs escalated support or is frustrated", // AI context
-    (ctx) => ctx.data?.previousAttempts > 2, // Data check
-    (ctx) => ctx.context?.supportHistory.length > 5 // Context check
-  ],
-  skipIf: [
-    "Issue has been resolved recently", // AI context
-    (ctx) => {
-      const lastTicket = ctx.context?.supportHistory[0];
-      return lastTicket?.status === 'resolved' && 
-             (Date.now() - lastTicket.resolvedAt.getTime()) < 24 * 60 * 60 * 1000;
-    }
-  ]
-});
-```
-
-## 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 */);
-}
-```
-
-### Sticky Route Switching
-
-When the agent is already on a route, it won't switch unless an alternative route scores higher by a configurable margin. This prevents flip-flopping on marginal score differences:
-
-```typescript
-const agent = new Agent({
-  // ...
-  routeSwitchMargin: 15, // default: 15, range 0-100
-});
-```
-
-A margin of 15 means the best alternative must outscore the current route by at least 15 points before a switch occurs.
-
-## 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 Configuration
-
-```typescript
-const agent = new Agent({
-  // ...
-  routeSwitchMargin: 15, // Score margin before switching routes (0-100, default: 15)
-});
-```
-
-## 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/enhanced-tool.md

@@ -1,186 +0,0 @@
-# EnhancedTool Interface
-
-`EnhancedTool` extends the existing `Tool` interface with optional metadata for concurrency control, permission gating, input validation, and result size management. All additional methods are optional — plain `Tool` objects remain fully compatible.
-
-## Interface
-
-```typescript
-interface EnhancedTool<TContext = any, TData = any, TResult = any>
-  extends Tool<TContext, TData, TResult> {
-
-  // Concurrency & safety
-  isConcurrencySafe?(input?: Record<string, unknown>): boolean;
-  isReadOnly?(input?: Record<string, unknown>): boolean;
-  isDestructive?(input?: Record<string, unknown>): boolean;
-
-  // Execution control
-  interruptBehavior?(): 'cancel' | 'block';
-  maxResultSizeChars?: number;
-
-  // Validation & permissions
-  validateInput?(
-    input: Record<string, unknown>,
-    context: ToolContext<TContext, TData>
-  ): Promise<ToolValidationResult> | ToolValidationResult;
-
-  checkPermissions?(
-    input: Record<string, unknown>,
-    context: ToolContext<TContext, TData>
-  ): Promise<ToolPermissionResult> | ToolPermissionResult;
-}
-```
-
-## Methods & Properties
-
-### isConcurrencySafe
-
-Returns `true` if this tool can safely run in parallel with other concurrency-safe tools. The `StreamingToolExecutor` evaluates this once at queue time and caches the result.
-
-Default (when absent): `false` — the tool runs serially.
-
-```typescript
-const listFiles: EnhancedTool = {
-  id: "list-files",
-  name: "list_files",
-  description: "List files in a directory",
-  handler: async (ctx, args) => { /* ... */ },
-  isConcurrencySafe: () => true,
-};
-```
-
-The method receives the tool's input arguments, so concurrency safety can be input-dependent:
-
-```typescript
-isConcurrencySafe: (input) => {
-  // Safe for read paths, not safe for write paths
-  return input?.mode === "read";
-},
-```
-
-### isReadOnly / isDestructive
-
-Informational metadata. `isReadOnly` indicates the tool has no side effects; `isDestructive` indicates irreversible operations. Both default to `false` when absent.
-
-```typescript
-isReadOnly: () => true,
-isDestructive: () => false,
-```
-
-### interruptBehavior
-
-Controls how the tool responds to abort signals (sibling failure or parent cancellation):
-
-- `'cancel'` — immediately abort the tool
-- `'block'` — allow the tool to finish (default when absent)
-
-```typescript
-interruptBehavior: () => "cancel",
-```
-
-### maxResultSizeChars
-
-Maximum characters for the tool result. Results exceeding this limit are truncated with a notice like `[Truncated: 12000 chars total, showing first 5000]`.
-
-```typescript
-maxResultSizeChars: 50_000,
-```
-
-### validateInput
-
-Called before the tool handler. If it returns `{ valid: false }`, the handler is never invoked and a validation error is returned instead.
-
-```typescript
-validateInput: async (input, ctx) => {
-  if (!input.resourceId || typeof input.resourceId !== "string") {
-    return { valid: false, error: "resourceId must be a non-empty string" };
-  }
-  return { valid: true };
-},
-```
-
-The return type:
-
-```typescript
-interface ToolValidationResult {
-  valid: boolean;
-  error?: string;
-  correctedInput?: Record<string, unknown>;
-}
-```
-
-### checkPermissions
-
-Called before the tool handler (after validation). If it returns `{ allowed: false }`, the handler is never invoked and a permission error is returned.
-
-```typescript
-checkPermissions: async (input, ctx) => {
-  const role = (ctx.context as any)?.userRole;
-  if (role !== "admin") {
-    return { allowed: false, reason: "Only admins can delete resources", canOverride: false };
-  }
-  return { allowed: true };
-},
-```
-
-The return type:
-
-```typescript
-interface ToolPermissionResult {
-  allowed: boolean;
-  reason?: string;
-  canOverride?: boolean;
-}
-```
-
-## Full Example
-
-```typescript
-const deleteTool: EnhancedTool = {
-  id: "delete-resource",
-  name: "delete_resource",
-  description: "Delete a resource permanently",
-  parameters: {
-    type: "object",
-    properties: { resourceId: { type: "string" } },
-    required: ["resourceId"],
-  },
-  handler: async (ctx, args) => {
-    await deleteResource(args?.resourceId as string);
-    return { success: true };
-  },
-
-  isConcurrencySafe: () => false,
-  isReadOnly: () => false,
-  isDestructive: () => true,
-  interruptBehavior: () => "block",
-  maxResultSizeChars: 500,
-
-  validateInput: async (input) => {
-    if (!input.resourceId || typeof input.resourceId !== "string") {
-      return { valid: false, error: "resourceId must be a non-empty string" };
-    }
-    return { valid: true };
-  },
-
-  checkPermissions: async (input, ctx) => {
-    const role = (ctx.context as any)?.userRole;
-    if (role !== "admin") {
-      return { allowed: false, reason: "Only admins can delete resources" };
-    }
-    return { allowed: true };
-  },
-};
-```
-
-## Backward Compatibility
-
-Plain `Tool` objects without any `EnhancedTool` methods work exactly as before. The framework applies these defaults:
-
-| Property | Default |
-|---|---|
-| `isConcurrencySafe` | `false` |
-| `isReadOnly` | `false` |
-| `isDestructive` | `false` |
-| `interruptBehavior` | `'block'` |
-| `validateInput` | skipped |
-| `checkPermissions` | skipped |