@falai/agent 1.2.7 → 2.0.0

package/docs/api/README.md

@@ -1,3299 +0,0 @@
-# API Reference
-
-Complete API documentation for `@falai/agent`. This framework provides a strongly-typed, modular agent architecture with AI-powered routing and schema-driven data collection.
-
-## 📋 Documentation Structure
-
-- **[Complete API Overview](./overview.md)** - Comprehensive reference for all classes, interfaces, and utilities
-- **[Agent Architecture](../core/agent/README.md)** - Agent class, context management, and lifecycle
-- **[AI Routing System](../core/routing/intelligent-routing.md)** - Intelligent route and step selection
-- **[Route DSL](../core/conversation-flows/route-dsl.md)** - Declarative conversation flow design
-- **[Data Collection](../core/conversation-flows/data-collection.md)** - Schema-driven data extraction
-- **[Tool Definition](../core/tools/tool-definition.md)** - Tool creation and configuration
-- **[Session Storage](../core/persistence/session-storage.md)** - Persistence and session management
-- **[AI Providers](../core/ai-integration/providers.md)** - Provider integrations and configuration
-
----
-
-## ConditionTemplate System
-
-### `ConditionTemplate<TContext, TData>`
-
-**NEW:** Enhanced condition type that supports flexible routing logic with both AI context and programmatic evaluation.
-
-```typescript
-type ConditionTemplate<TContext = unknown, TData = unknown> =
-  | string  // AI context only - provides context to AI for routing decisions
-  | ((params: TemplateContext<TContext, TData>) => boolean | Promise<boolean>) // Programmatic evaluation
-  | ConditionTemplate<TContext, TData>[]; // Array of either type
-```
-
-**Key Features:**
-
-- **String conditions**: Provide AI context for routing decisions (e.g., `"user wants to book a flight"`)
-- **Function conditions**: Execute programmatic logic returning boolean (e.g., `(ctx) => ctx.data?.isLoggedIn === true`)
-- **Array conditions**: Combine multiple conditions with logical operators
-- **Hybrid approach**: Mix strings and functions for optimal flexibility
-
-#### Evaluation Logic
-
-**For `when` conditions (AND logic):**
-- **Functions**: All must return `true` for condition to pass
-- **Strings**: Ignored in programmatic evaluation, used for AI context
-- **Arrays**: All functions must return `true`
-
-**For `skipIf` conditions (OR logic):**
-- **Functions**: Any returning `true` causes skip
-- **Strings**: Ignored in programmatic evaluation, used for AI context  
-- **Arrays**: Any function returning `true` causes skip
-
-#### Usage Examples
-
-```typescript
-// String-only condition (AI context)
-when: "User wants to make a reservation"
-
-// Function-only condition (programmatic)
-when: (ctx) => ctx.data?.userType === 'premium'
-
-// Mixed array condition (hybrid approach)
-when: [
-  "User is asking for help", // AI context
-  (ctx) => ctx.data?.isLoggedIn === true // Programmatic check
-]
-
-// Route skipIf with OR logic
-skipIf: [
-  "System is under maintenance", // AI context
-  (ctx) => ctx.data?.maintenanceMode === true // Programmatic check
-]
-```
-
-### `ConditionEvaluator<TContext, TData>`
-
-**NEW:** Utility class for evaluating ConditionTemplate instances with consistent logic across the framework.
-
-#### Constructor
-
-```typescript
-new ConditionEvaluator<TContext, TData>(templateContext: TemplateContext<TContext, TData>)
-```
-
-#### Methods
-
-##### `evaluateCondition(condition, logic?): Promise<ConditionEvaluationResult>`
-
-Evaluates a ConditionTemplate and returns detailed results.
-
-**Parameters:**
-- `condition`: ConditionTemplate to evaluate
-- `logic`: 'AND' | 'OR' - logical operator for arrays (default: 'AND')
-
-**Returns:**
-```typescript
-interface ConditionEvaluationResult {
-  programmaticResult: boolean; // Result of function evaluations only
-  aiContextStrings: string[]; // String values for AI context
-  hasProgrammaticConditions: boolean; // Whether any functions were evaluated
-}
-```
-
-**Example:**
-
-```typescript
-const evaluator = new ConditionEvaluator(templateContext);
-
-const result = await evaluator.evaluateCondition([
-  "User needs premium support", // AI context
-  (ctx) => ctx.data?.userType === 'premium' // Programmatic
-]);
-
-console.log(result.programmaticResult); // true/false from function
-console.log(result.aiContextStrings); // ["User needs premium support"]
-console.log(result.hasProgrammaticConditions); // true
-```
-
----
-
-## Core Classes
-
-### `Agent<TContext, TData>`
-
-Main agent class for managing conversational AI with agent-level data collection.
-
-#### Constructor
-
-```typescript
-new Agent<TContext, TData>(options: AgentOptions<TContext, TData>)
-```
-
-See `AgentOptions` type definition for full details.
-
-#### Methods
-
-##### `createRoute(options: RouteOptions): Route`
-
-Creates a new conversation route with required fields specification.
-
-##### `getCollectedData(): Partial<TData>`
-
-Gets the current agent-level collected data.
-
-```typescript
-const data = agent.getCollectedData();
-console.log(data); // { customerName: "John", email: "john@example.com" }
-```
-
-##### `updateCollectedData(updates: Partial<TData>): Promise<void>`
-
-Updates agent-level collected data and triggers validation.
-
-```typescript
-await agent.updateCollectedData({
-  customerId: "CUST-12345",
-  priority: "high"
-});
-```
-
-##### `validateData(data: Partial<TData>): ValidationResult`
-
-Validates data against the agent-level schema.
-
-```typescript
-const validation = agent.validateData({ email: "invalid-email" });
-if (!validation.valid) {
-  console.log(validation.errors); // Detailed validation errors
-}
-```
-
-##### `createTerm(term: Term): this`
-
-Adds a domain glossary term. Returns `this` for chaining.
-
-##### `createGuideline(guideline: Guideline): this`
-
-Adds a behavioral guideline. Returns `this` for chaining.
-
-##### `addTool(definition: Tool<TContext, TData, TResult>): this`
-
-Creates and adds a tool to agent scope using the unified Tool interface. Returns `this` for chaining.
-
-```typescript
-// Simple return value approach
-agent.addTool({
-  id: "weather_check",
-  description: "Get current weather",
-  parameters: {
-    type: "object",
-    properties: {
-      location: { type: "string", description: "City name" }
-    },
-    required: ["location"]
-  },
-  handler: async ({ context, data }, args) => {
-    const weather = await weatherAPI.get(args.location);
-    return `Weather in ${args.location}: ${weather.condition}`;
-  }
-});
-
-// Advanced ToolResult pattern
-agent.addTool({
-  id: "user_lookup",
-  description: "Look up user information",
-  handler: async ({ context, data }, args) => {
-    const user = await userAPI.find(args.userId);
-    return {
-      data: `Found user: ${user.name}`,
-      success: true,
-      contextUpdate: { currentUser: user },
-      dataUpdate: { userName: user.name }
-    };
-  }
-});
-```
-
-##### `tool: ToolManager<TContext, TData>`
-
-Access to the ToolManager instance for advanced tool operations.
-
-```typescript
-// Register tools for ID-based reference
-agent.tool.register({
-  id: "reusable_search",
-  description: "Search across data sources",
-  handler: async ({ context, data }, args) => "Search results"
-});
-
-// Create tools without adding to scope
-const customTool = agent.tool.create({
-  id: "standalone_tool",
-  handler: async () => "Custom result"
-});
-
-// Use pattern helpers
-const enrichmentTool = agent.tool.createDataEnrichment({
-  id: "enrich_profile",
-  fields: ['name', 'email'],
-  enricher: async (context, data) => ({
-    displayName: `${data.name} <${data.email}>`
-  })
-});
-```
-
-##### `respond(input: RespondInput<TContext>): Promise<RespondOutput>`
-
-Generates an AI response with session step management, tool execution, data extraction, and intelligent routing.
-
-**Note:** This method now delegates to the internal `ResponseModal` class for improved architecture and maintainability.
-
-**Enhanced Response Pipeline:**
-
-1. **Tool Execution** - Execute tools if current step has `tool` (enriches context before AI response)
-2. **Always-On Routing** - Score all routes, respect user intent to change direction
-3. **Step Traversal** - Use `skipIf` and `requires` to determine next step
-4. **Response Generation** - Build schema with `collect` fields, extract data
-5. **Session Update** - Merge collected data into session step
-
-**Tool Execution (Pre-Response):**
-Tools execute before AI response generation, allowing them to:
-
-- Enrich context with external data
-- Update collected session data
-- Perform business logic
-- Access APIs and databases
-
-This design enables more intelligent, context-aware responses.
-
-##### `getKnowledgeBase(): Record<string, unknown>`
-
-Gets the agent's knowledge base containing any JSON structure the AI should know.
-
-```typescript
-const knowledge = agent.getKnowledgeBase();
-// Returns the agent's knowledge base
-```
-
-##### `getRoutes(): Route<TContext, unknown>[]`
-
-Gets all routes configured in the agent.
-
-```typescript
-const routes = agent.getRoutes();
-// Returns array of all configured routes
-```
-
-##### `getTerms(): Term<TContext>[]`
-
-Gets all terms configured in the agent.
-
-```typescript
-const terms = agent.getTerms();
-// Returns array of all configured terms
-```
-
-##### `getGuidelines(): Guideline<TContext>[]`
-
-Gets all guidelines configured in the agent.
-
-```typescript
-const guidelines = agent.getGuidelines();
-// Returns array of all configured guidelines
-```
-
-##### `getRules(): Template<TContext, TData>[]`
-
-Gets agent-level rules. These are merged with route-level rules in every prompt.
-
-```typescript
-const rules = agent.getRules();
-```
-
-##### `getProhibitions(): Template<TContext, TData>[]`
-
-Gets agent-level prohibitions. These are merged with route-level prohibitions in every prompt.
-
-```typescript
-const prohibitions = agent.getProhibitions();
-```
-
-````typescript
-
-##### `getPersistenceManager(): PersistenceManager | undefined`
-
-Gets the persistence manager if configured.
-
-```typescript
-const persistence = agent.getPersistenceManager();
-// Returns PersistenceManager instance or undefined if not configured
-````
-
-##### `hasPersistence(): boolean`
-
-Checks if persistence is enabled.
-
-```typescript
-if (agent.hasPersistence()) {
-  // Persistence is configured
-}
-```
-
-##### `nextStepRoute(routeIdOrTitle, session?, condition?, history?): Promise<SessionState>`
-
-Manually transition to a different route by setting a pending transition that will be executed on the next `respond()` call.
-
-```typescript
-// Transition to feedback route after completion
-const updatedSession = await agent.nextStepRoute(
-  "feedback-collection",
-  session
-);
-
-// Next respond() call will automatically transition
-const response = await agent.respond({ history, session: updatedSession });
-```
-
-**Parameters:**
-
-- `routeIdOrTitle`: Route ID or title to transition to
-- `session`: Session step to update (uses current session if not provided)
-- `condition`: Optional AI-evaluated condition for the transition
-- `history`: Optional history for template context
-
-**Returns:** Updated session with pending transition
-
-##### `getData<TData>(routeId?): Partial<TData>`
-
-Gets the collected data from current session, optionally for a specific route.
-
-```typescript
-// Option 1: Using current session (set with setCurrentSession)
-agent.setCurrentSession(session);
-const data = agent.getData(); // Uses current session
-
-// Option 2: Get data for specific route
-const routeData = agent.getData("onboarding"); // Route-specific data
-
-// Option 3: From response (with current session set)
-const response = await agent.respond({ history });
-const data = agent.getData(); // Uses current session
-```
-
-**Parameters:**
-
-- `routeId` (optional): Route ID to get data for. If not provided, returns current route data.
-
-**Returns:** The collected data from the current session
-
-**Note:** Returns empty object if no current session is set.
-
-##### `setCurrentSession(session): void`
-
-Sets the current session for convenience methods. Once set, methods like `getData()` don't need the session parameter.
-
-```typescript
-// Set current session
-agent.setCurrentSession(session);
-
-// Now methods use the current session automatically
-const data = agent.getData();
-// Get collected data for route
-const routeData = agent.getData("onboarding");
-```
-
-**Parameters:**
-
-- `session`: Session step to use as current session
-
-##### `getCurrentSession(): SessionState | undefined`
-
-Gets the currently set session.
-
-```typescript
-const current = agent.getCurrentSession();
-if (current) {
-  console.log("Current session:", current.id);
-}
-```
-
-**Returns:** Current session or undefined if none set
-
-##### `clearCurrentSession(): void`
-
-Clears the current session.
-
-```typescript
-agent.clearCurrentSession();
-```
-
-##### `respond(input: RespondInput<TContext>): Promise<RespondOutput>`
-
-Generates an AI response with session step management, data extraction, and intelligent routing.
-
-```typescript
-interface RespondInput<TContext> {
-  history: Event[];
-  session?: SessionState; // NEW: Session step for conversation tracking
-  contextOverride?: Partial<TContext>;
-  signal?: AbortSignal;
-}
-
-interface RespondOutput {
-  /** The message to send to the user */
-  message: string;
-  /** Updated session step (includes collected data, current route/step) */
-  session?: SessionState;
-  /** Tool calls executed during response (for debugging) */
-  toolCalls?: Array<{
-    toolName: string;
-    arguments: Record<string, unknown>;
-  }>;
-  /**
-   * NEW: Indicates if the current route has reached END_ROUTE
-   * When true, the step flow has reached its end and the route is complete.
-   * Your application should handle this appropriately (e.g., process collected data,
-   * show completion UI, start a new route, etc.)
-   */
-  isRouteComplete?: boolean;
-}
-```
-
-**Enhanced Response Pipeline:**
-
-1. **Tool Execution** - Execute tools if current step has `tool`
-2. **Always-On Routing** - Score all routes, respect user intent to change direction
-3. **Step Traversal** - Use `skipIf` and `requires` to determine next step
-4. **Response Generation** - Build schema with `collect` fields, extract data
-5. **Session Update** - Merge collected data into session step
-
-**Session Step Management:**
-
-- Tracks current route, step, and collected data across turns
-- Enables "I changed my mind" scenarios with context-aware routing
-- Automatically merges new collected data with existing session data
-- **Per-route data preservation** - Collected data is organized by route ID, allowing users to switch routes without losing progress
-
-**Example with Automatic Session Management:**
-
-```typescript
-// Server endpoint with automatic session management
-app.post('/chat', async (req, res) => {
-  const { sessionId, message } = req.body;
-  
-  const agent = new Agent({
-    name: "Travel Agent",
-    provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
-    persistence: { adapter: new PrismaAdapter({ prisma }) },
-    sessionId // Automatically loads or creates this session
-  });
-  
-  const response = await agent.respond(message);
-  
-  res.json({
-    message: response.message,
-    sessionId: agent.session.id,
-    isComplete: response.isRouteComplete
-  });
-});
-```
-
-**SessionManager API:**
-
-```typescript
-// Access session manager
-const sessionManager = agent.session;
-
-// Get or create session (works for existing, new, or auto-generated IDs)
-await sessionManager.getOrCreate("user-123");
-await sessionManager.getOrCreate(); // Auto-generates ID
-
-// Data access
-const data = sessionManager.getData<FlightData>();
-await sessionManager.setData({ destination: "Paris" });
-
-// History management
-await sessionManager.addMessage("user", "Hello");
-const history = sessionManager.getHistory();
-sessionManager.clearHistory();
-
-// Session operations
-await sessionManager.save(); // Manual save (auto-saves on addMessage)
-await sessionManager.delete();
-const newSession = await sessionManager.reset(true); // Preserve history
-  currentRoute: response.session?.currentRoute?.id,
-  currentStep: response.session?.currentStep?.id,
-  collectedData: {
-    data: response.session?.data,
-    routeHistory: response.session?.routeHistory,
-    currentRouteTitle: response.session?.currentRoute?.title,
-    currentStepDescription: response.session?.currentStep?.description,
-    metadata: response.session?.metadata,
-  },
-  lastMessageAt: new Date(),
-});
-
-// Save message
-await yourDb.messages.create({
-  sessionId: dbSession.id,
-  role: "assistant",
-  content: response.message,
-  route: response.session?.currentRoute?.id,
-  step: response.session?.currentStep?.id,
-});
-```
-
-**Handling Route Completion:**
-
-When a route reaches its END_ROUTE transition (all required data collected), the response includes `isRouteComplete: true`:
-
-```typescript
-const response = await agent.respond({
-  history,
-  session,
-});
-
-if (response.isRouteComplete) {
-  // Route is complete! All data has been collected
-  console.log("✅ Route completed!");
-
-  // Get all the collected data
-  const collectedData = agent.getData(response.session!);
-  console.log("Collected data:", collectedData);
-
-  // Handle completion in your application:
-  // - Save the collected data to your database
-  // - Trigger business logic (e.g., create booking, send email)
-  // - Show completion UI to user
-  // - Start a new route or conversation
-
-  await processCompletedData(collectedData);
-
-  // Optional: Show a custom completion message
-  return "Thank you! Your information has been saved.";
-} else {
-  // Normal flow - route still in progress
-  return response.message;
-}
-```
-
-**Example: Onboarding Flow**
-
-```typescript
-// Onboarding route with skipIf logic for pre-filled data
-const onboardingRoute = agent.createRoute<OnboardingData>({
-  id: "onboarding",
-  title: "User Onboarding",
-  schema: ONBOARDING_SCHEMA,
-  initialData: existingUserData, // Pre-fill with existing data
-});
-
-// Build steps with skipIf conditions
-const welcome = onboardingRoute.initialStep.nextStep({
-  id: "ask_name",
-  prompt: "What's your name?",
-  collect: ["name"],
-  skipIf: (data) => !!data.name, // Skip if name already collected
-});
-
-const askEmail = welcome.nextStep({
-  id: "ask_email",
-  prompt: "What's your email?",
-  collect: ["email"],
-  skipIf: (data) => !!data.email, // Skip if email already collected
-});
-
-const complete = askEmail.nextStep({
-  id: "complete",
-  prompt: "All done! Thank you.",
-});
-
-complete.nextStep({ step: END_ROUTE });
-
-// Option 1: Set current session for convenience
-agent.setCurrentSession(session);
-
-const response = await agent.respond({ history });
-
-if (response.isRouteComplete) {
-  // If all data was pre-filled, the route completes immediately!
-  // The routing engine recursively skips all steps and reaches END_ROUTE
-  const data = agent.getData(); // No need to pass session!
-  await saveUserProfile(data);
-  return "Profile updated successfully!";
-}
-
-return response.message;
-```
-
-**Important Notes:**
-
-- `isRouteComplete` is `true` when the route reaches an `END_ROUTE` transition
-- The `message` contains the completion message generated by the AI when `isRouteComplete` is `true`
-- You should check `isRouteComplete` and handle completion appropriately
-- If all steps are skipped (due to `skipIf` conditions), the route can complete immediately on entry
-- Use `agent.getData(session)` to retrieve all collected data
-
-See also: [Database Integration Example](../../examples/integrations/database-integration.ts)
-
-##### `respondStream(input: RespondInput<TContext>): AsyncGenerator<StreamChunk>`
-
-Generates an AI response as a real-time stream for better user experience. Provides the same structured output as `respond()` but delivers it incrementally.
-
-**Note:** This method now delegates to the internal `ResponseModal` class for improved architecture and maintainability.
-
-```typescript
-interface StreamChunk {
-  /** The incremental text delta */
-  delta: string;
-  /** Full accumulated text so far */
-  accumulated: string;
-  /** Whether this is the final chunk */
-  done: boolean;
-  /** Updated session step (includes collected data, current route/step) */
-  session?: SessionState;
-  /** Tool calls requested by the agent (only in final chunk) */
-  toolCalls?: Array<{
-    toolName: string;
-    arguments: Record<string, unknown>;
-  }>;
-  /**
-   * Indicates if the current route has reached END_ROUTE (only in final chunk)
-   * When true, the step flow has reached its end and the route is complete.
-   */
-  isRouteComplete?: boolean;
-}
-```
-
-**Key Features:**
-
-- 🌊 Real-time streaming for better perceived performance
-- 📊 Access to route, step, and tool information in final chunk
-- 🛑 Cancellable with AbortSignal
-- ✅ Supported by all providers (Anthropic, OpenAI, Gemini, OpenRouter)
-
-**Example:**
-
-```typescript
-// Basic streaming
-for await (const chunk of agent.respondStream({ history, session })) {
-  if (chunk.delta) {
-    // Display incremental text to user
-    process.stdout.write(chunk.delta);
-  }
-
-  if (chunk.done) {
-    console.log("\n✅ Complete!");
-
-    // Check if route is complete
-    if (chunk.isRouteComplete) {
-      console.log("🎉 Route completed!");
-      const data = agent.getData(chunk.session!);
-      await handleCompletion(data);
-    }
-
-    // Access session step
-    if (chunk.session?.currentRoute) {
-      console.log("Route:", chunk.session.currentRoute.title);
-    }
-    if (chunk.toolCalls) {
-      console.log("Tool calls:", chunk.toolCalls.length);
-    }
-  }
-}
-```
-
-##### `stream(message?: string, options?: StreamOptions<TContext>): AsyncGenerator<AgentResponseStreamChunk<TData>>`
-
-**NEW:** Modern streaming API that provides a simple interface similar to `chat()` but returns a stream. This is the recommended way to implement streaming responses.
-
-```typescript
-interface StreamOptions<TContext = unknown> {
-  contextOverride?: Partial<TContext>;
-  signal?: AbortSignal;
-  history?: History; // Optional: override session history
-}
-```
-
-**Key Features:**
-
-- 🎯 **Simple Interface**: Just `agent.stream("message")` - no complex parameters
-- 🔄 **Automatic Session Management**: Handles conversation history automatically
-- 🌊 **Real-time Streaming**: Same performance as `respondStream()` but easier to use
-- 🛑 **Cancellable**: Supports AbortSignal for cancellation
-
-**Example:**
-
-```typescript
-// Simple streaming - automatically manages session history
-for await (const chunk of agent.stream("Hello, how are you?")) {
-  if (chunk.delta) {
-    process.stdout.write(chunk.delta);
-  }
-  
-  if (chunk.done) {
-    console.log("\n✅ Stream complete!");
-    // Session history is automatically updated
-  }
-}
-
-// With cancellation
-const controller = new AbortController();
-setTimeout(() => controller.abort(), 5000); // Cancel after 5s
-
-for await (const chunk of agent.stream("Tell me a long story", {
-  signal: controller.signal
-})) {
-  process.stdout.write(chunk.delta);
-}
-```
-
-**Migration from `respondStream()`:**
-
-```typescript
-// Old way (still supported)
-for await (const chunk of agent.respondStream({
-  history: agent.session.getHistory(),
-  session: await agent.session.getOrCreate()
-})) {
-  // Handle chunk
-}
-
-// New way (recommended)
-for await (const chunk of agent.stream("Your message")) {
-  // Handle chunk - session management is automatic
-}
-```
-
-**With Cancellation:**
-
-```typescript
-const abortController = new AbortController();
-
-// Cancel after 5 seconds
-setTimeout(() => abortController.abort(), 5000);
-
-try {
-  for await (const chunk of agent.respondStream({
-    history,
-    signal: abortController.signal,
-  })) {
-    console.log(chunk.delta);
-  }
-} catch (error) {
-  if (error.name === "AbortError") {
-    console.log("Stream cancelled");
-  }
-}
-```
-
-**Collecting Full Response:**
-
-```typescript
-let fullMessage = "";
-let finalChunk;
-
-for await (const chunk of agent.respondStream({ history })) {
-  fullMessage += chunk.delta;
-  if (chunk.done) {
-    finalChunk = chunk;
-  }
-}
-
-// Save to database
-await db.agentMessages.create({
-  sessionId: session.id,
-  role: "assistant",
-  content: fullMessage,
-  route: finalChunk.route?.title,
-  toolCalls: finalChunk.toolCalls || [],
-});
-```
-
-**See Also:** [streaming-responses.ts](../../examples/advanced-patterns/streaming-responses.ts) for comprehensive examples.
-
-#### Properties
-
-##### `name: string`
-
-Agent's name (readonly).
-
-##### `description?: string`
-
-Agent's description (readonly).
-
-##### `goal?: string`
-
-Agent's goal (readonly).
-
-##### `identity(): Template<TContext> | undefined`
-
-Agent's identity template (readonly).
-
----
-
-### `ResponseModal<TContext, TData>`
-
-**NEW:** Internal class that handles all response generation logic for the Agent. This class centralizes response processing, provides unified streaming and non-streaming APIs, and improves maintainability.
-
-**Note:** This class is primarily used internally by the Agent class. Most users should use the Agent's response methods (`respond`, `respondStream`, `stream`, `chat`) rather than accessing ResponseModal directly.
-
-#### Constructor
-
-```typescript
-new ResponseModal<TContext, TData>(
-  agent: Agent<TContext, TData>,
-  options?: ResponseModalOptions
-)
-
-interface ResponseModalOptions {
-  /** Maximum number of tool loops allowed during response generation */
-  maxToolLoops?: number;
-  /** Enable automatic session saving after response generation */
-  enableAutoSave?: boolean;
-  /** Enable debug mode for detailed logging */
-  debugMode?: boolean;
-}
-```
-
-#### Methods
-
-##### `respond(params: RespondParams<TContext, TData>): Promise<AgentResponse<TData>>`
-
-Generates a non-streaming response using unified logic. This method consolidates all response generation logic including routing, tool execution, and data collection.
-
-##### `respondStream(params: RespondParams<TContext, TData>): AsyncGenerator<AgentResponseStreamChunk<TData>>`
-
-Generates a streaming response using unified logic. Provides the same functionality as `respond()` but delivers results incrementally.
-
-##### `stream(message?: string, options?: StreamOptions<TContext>): AsyncGenerator<AgentResponseStreamChunk<TData>>`
-
-Modern streaming API with automatic session management. This is the recommended way to implement streaming responses.
-
-```typescript
-// Simple usage
-for await (const chunk of responseModal.stream("Hello")) {
-  console.log(chunk.delta);
-}
-
-// With options
-for await (const chunk of responseModal.stream("Hello", {
-  contextOverride: { userId: "123" },
-  signal: abortController.signal
-})) {
-  console.log(chunk.delta);
-}
-```
-
-##### `generate(message?: string, options?: GenerateOptions<TContext>): Promise<AgentResponse<TData>>`
-
-Modern non-streaming API equivalent to `chat()` but more explicit. Provides automatic session management for non-streaming responses.
-
-```typescript
-// Simple usage
-const response = await responseModal.generate("Hello");
-console.log(response.message);
-
-// With options
-const response = await responseModal.generate("Hello", {
-  contextOverride: { userId: "123" }
-});
-```
-
-#### Error Handling
-
-ResponseModal includes comprehensive error handling with the `ResponseGenerationError` class:
-
-```typescript
-try {
-  const response = await responseModal.respond(params);
-} catch (error) {
-  if (ResponseGenerationError.isResponseGenerationError(error)) {
-    console.log("Response generation failed:", error.message);
-    console.log("Phase:", error.details?.phase);
-    console.log("Original error:", error.details?.originalError);
-  }
-}
-```
-
-#### Architecture Benefits
-
-- **Separation of Concerns**: Agent focuses on configuration and orchestration, ResponseModal handles response generation
-- **Unified Logic**: Both streaming and non-streaming responses use the same underlying logic
-- **Modern APIs**: Provides simple `stream()` and `generate()` methods alongside legacy compatibility
-- **Error Handling**: Comprehensive error handling with detailed context
-- **Performance**: Optimized response pipeline with minimal duplication
-
----
-
-### `Route`
-
-Represents a conversation flow with steps and transitions.
-
-#### Constructor
-
-```typescript
-new Route(options: RouteOptions)
-
-interface RouteOptions<TData = unknown> {
-  id?: string;              // Optional custom ID (deterministic ID generated from title if not provided)
-  title: string;            // Route title
-  description?: string;     // Route description
-  identity?: string;        // Optional identity prompt defining the agent's role and persona for this route
-  personality?: Template;   // Optional personality prompt defining the agent's communication style for this route
-  when?: ConditionTemplate; // NEW: Conditions that activate this route (replaces conditions)
-  skipIf?: ConditionTemplate; // NEW: Conditions that exclude this route from consideration
-  guidelines?: Guideline[]; // Initial guidelines for this route
-  terms?: Term[];          // Initial terms for the route's domain glossary
-  rules?: string[];         // Absolute rules the agent MUST follow in this route
-  prohibitions?: string[];  // Absolute prohibitions the agent MUST NEVER do in this route
-
-  // NEW: Schema-first data extraction
-  schema?: {
-    type: "object";
-    properties: Record<string, any>;
-    required?: string[];
-    additionalProperties?: boolean;
-  };
-
-  // NEW: Pre-populate collected data when entering route
-  initialData?: Partial<TData>;
-
-  // NEW: Configure the initial step
-  initialStep?: {
-    id?: string;              // Custom ID for the initial step
-    prompt?: string;       // Description for the initial step
-    collect?: string[];        // Fields to collect in the initial step
-    skipIf?: (data: Partial<TData>) => boolean;  // Skip condition
-    requires?: string[];  // Required data prerequisites
-  };
-
-  // NEW: Sequential steps for simple linear flows
-  steps?: StepOptions<unknown, TData>[];
-  /** Knowledge base specific to this route containing any JSON structure the AI should know */
-  knowledgeBase?: Record<string, unknown>;
-  /**
-   * Route lifecycle hooks
-   */
-  hooks?: RouteLifecycleHooks<TContext, TData>;
-}
-```
-
-**Note on IDs:** Route IDs are deterministic by default, generated from the title using a hash function. This ensures consistency across server restarts. You can provide a custom ID if you need specific control over the identifier.
-
-**Initial Step Configuration:** You can configure the initial step in two ways:
-
-1. Using `initialStep` option when creating the route
-2. Using `route.initialStep.configure()` method after route creation
-
-#### Methods
-
-##### `createGuideline(guideline: Guideline): this`
-
-Adds a guideline specific to this route. Returns `this` for chaining.
-
-##### `getGuidelines(): Guideline[]`
-
-Returns all guidelines for this route.
-
-##### `createTerm(term: Term): this`
-
-Adds a term to the route's domain glossary. Returns `this` for chaining.
-
-##### `getTerms(): Term[]`
-
-Returns all terms in the route's domain glossary.
-
-##### `getRules(): string[]`
-
-Returns the rules that must be followed in this route.
-
-##### `getProhibitions(): string[]`
-
-Returns the prohibitions that must never be done in this route.
-
-##### `getKnowledgeBase(): Record<string, unknown>`
-
-Gets the route's knowledge base containing any JSON structure the AI should know.
-
-```typescript
-const knowledge = route.getKnowledgeBase();
-// Returns the route-specific knowledge base
-```
-
-##### `getRef(): RouteRef`
-
-Returns a reference to this route.
-
-##### `getAllSteps(): Step<TContext, TData>[]`
-
-Gets all steps in this route via traversal from the initial step.
-
-```typescript
-const steps = route.getAllSteps();
-// Returns array of all steps in the route
-```
-
-##### `getStep(stepId: string): Step<TContext, TData> | undefined`
-
-Gets a specific step by ID.
-
-```typescript
-const step = route.getStep("ask_destination");
-// Returns the step with the specified ID or undefined
-```
-
-##### `describe(): string`
-
-Generates a description of this route's structure for debugging.
-
-```typescript
-const description = route.describe();
-console.log(description);
-// Output:
-// Route: Book Flight
-// ID: route_book_flight
-// Description: N/A
-// When: None
-//
-// Steps:
-//   - step_ask_destination: Ask where to fly
-//     -> step_ask_dates: Ask about travel dates
-//     -> step_ask_passengers: How many passengers?
-```
-
-##### `handleDataUpdate(data, previousCollected): Promise<Partial<TData>>`
-
-Handles data updates for this route, calling the onDataUpdate hook if configured. Returns modified data after hook processing, or original data if no hook.
-
-```typescript
-const updatedData = await route.handleDataUpdate(newData, previousData);
-```
-
-**Parameters:**
-
-- `data`: New collected data
-- `previousCollected`: Previously collected data
-
-**Returns:** Modified data after hook processing
-
-##### `handleContextUpdate(newContext, previousContext): Promise<void>`
-
-Handles context updates for this route, calling the onContextUpdate hook if configured.
-
-```typescript
-await route.handleContextUpdate(newContext, previousContext);
-```
-
-**Parameters:**
-
-- `newContext`: New context
-- `previousContext`: Previous context
-
-##### `evaluateOnComplete(session, context?): Promise<RouteTransitionConfig<TContext, TData> | undefined>`
-
-Evaluates the onComplete handler and returns transition config.
-
-```typescript
-const transition = await route.evaluateOnComplete(
-  { data: session.data },
-  context
-);
-
-if (transition) {
-  // Transition to next route
-  console.log(`Next route: ${transition.nextStep}`);
-}
-```
-
-**Note:** Routes no longer have a `getData()` method. Use `agent.getData()` or `agent.getData(routeId)` instead.
-
-#### Properties
-
-##### `id: string`
-
-Unique route identifier (readonly).
-
-##### `title: string`
-
-Route title (readonly).
-
-##### `description?: string`
-
-Route description (readonly).
-
-##### `when?: ConditionTemplate`
-
-**NEW:** Conditions that trigger this route (readonly). Can be a string, function, or array of either.
-
-##### `skipIf?: ConditionTemplate`
-
-**NEW:** Conditions that exclude this route from consideration (readonly). Can be a string, function, or array of either.
-
-##### `initialStep: Step`
-
-Starting step of the route (readonly).
-
-##### `hooks?: RouteLifecycleHooks<TContext, TData>`
-
-Route lifecycle hooks for managing route-specific data and behavior (readonly).
-
----
-
-### `Step`
-
-Represents a step within a conversation route.
-
-#### Methods
-
-##### `nextStep(spec: StepOptions): Step`
-
-Creates a transition from this step and returns a chainable result.
-
-```typescript
-interface StepOptions<TData = unknown> {
-  id?: string; // step id
-  description?: string; // Step description
-  prompt?: string; // Transition to a chat interaction
-  tool?: ToolRef; // Transition to execute a tool
-  step?: StepRef | symbol; // Transition to specific step or END_ROUTE
-
-  // NEW: Data extraction fields for this step
-  collect?: string[];
-
-  // ENHANCED: Flexible condition to determine when this step should be active
-  when?: ConditionTemplate<TContext, TData>;
-
-  // ENHANCED: Flexible condition to skip this step
-  skipIf?: ConditionTemplate<TContext, TData>;
-
-  // NEW: Prerequisites that must be met to enter this step
-  requires?: string[];
-}
-
-interface Step<TContext = unknown, TData = unknown> {
-  id: string; // Step identifier
-  routeId: string; // Route identifier
-  nextStep: (spec: StepOptions<TContext, TData>) => Step<TContext, TData>;
-  description?: string; // Step description
-  collect?: (keyof TData)[]; // Fields to collect in this step
-  when?: ConditionTemplate<TContext, TData>; // ENHANCED: Flexible condition for step activation
-  skipIf?: ConditionTemplate<TContext, TData>; // ENHANCED: Flexible condition to skip step
-  requires?: (keyof TData)[]; // Required data prerequisites
-}
-```
-
-**Parameters:**
-
-- `spec`: The transition specification (see `StepOptions` above). Can include an optional `condition` property for AI-evaluated step selection guidance.
-
-**Returns:** A `Step` that includes the target step's reference (`id`, `routeId`) and a `nextStep` method for chaining additional transitions.
-
-**Example:**
-
-```typescript
-// Define your data extraction type
-interface FlightData {
-  destination: string;
-  departureDate: string;
-  passengers: number;
-}
-
-// Create a data-driven route
-const flightRoute = agent.createRoute<FlightData>({
-  title: "Book Flight",
-  schema: {
-    type: "object",
-    properties: {
-      destination: { type: "string" },
-      departureDate: { type: "string" },
-      passengers: { type: "number", minimum: 1, maximum: 9 },
-    },
-    required: ["destination", "departureDate", "passengers"],
-  },
-});
-
-// Approach 1: Step-by-step with data extraction and text conditions
-const askDestination = flightRoute.initialStep.nextStep({
-  prompt: "Ask where they want to fly",
-  collect: ["destination"],
-  skipIf: (data) => !!data.destination, // Skip if already have destination
-  condition: "Customer hasn't specified destination yet", // AI-evaluated condition
-});
-
-const askDates = askDestination.nextStep({
-  prompt: "Ask about travel dates",
-  collect: ["departureDate"],
-  skipIf: (data) => !!data.departureDate,
-  requires: ["destination"], // Must have destination first
-  condition: "Destination confirmed, need travel dates",
-});
-
-const askPassengers = askDates.nextStep({
-  prompt: "How many passengers?",
-  collect: ["passengers"],
-  skipIf: (data) => !!data.passengers,
-});
-
-// Access step properties
-console.log(askDestination.id); // Step ID
-console.log(askDestination.routeId); // Route ID
-
-// Approach 2: Fluent chaining for linear flows
-flightRoute.initialStep
-  .nextStep({
-    prompt: "Extract travel details",
-    collect: ["destination", "departureDate", "passengers"],
-  })
-  .nextStep({
-    prompt: "Present available flights",
-  })
-  .nextStep({ step: END_ROUTE });
-
-// Automatic session management
-const agent = new Agent({
-  name: "Travel Agent",
-  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
-  persistence: { adapter: new PrismaAdapter({ prisma }) },
-  sessionId: "user-123" // Automatically loads or creates session
-});
-
-const response = await agent.respond("I want to book a flight to Paris");
-console.log(agent.session.getData<FlightData>()); // { destination: "Paris", ... }
-```
-
-##### `addGuideline(guideline: Guideline): void`
-
-Adds a guideline specific to this step.
-
-##### `getGuidelines(): Guideline<TContext>[]`
-
-Gets all guidelines for this step.
-
-```typescript
-const guidelines = step.getGuidelines();
-// Returns array of guidelines specific to this step
-```
-
-##### `getTransitions(): Step<TContext, TData>[]`
-
-Gets all transitions from this step.
-
-```typescript
-const nextSteps = step.getTransitions();
-// Returns array of possible next steps
-```
-
-##### `shouldSkip(data: Partial<TData>): boolean`
-
-Checks if this step should be skipped based on collected data.
-
-```typescript
-if (step.shouldSkip(session.data)) {
-  // Skip this step
-}
-```
-
-##### `hasRequires(data: Partial<TData>): boolean`
-
-Checks if this step has all required data to proceed.
-
-```typescript
-if (step.hasRequires(session.data)) {
-  // Step can proceed
-}
-```
-
-
-
-##### `configure(config): this`
-
-Configure the step properties after creation. Useful for overriding initial step configuration. Returns `this` for chaining.
-
-```typescript
-// Configure initial step after route creation
-route.initialStep.configure({
-  description: "Welcome! Let's get started",
-  collect: ["name", "email"],
-  skipIf: (data) => !!data.name && !!data.email,
-  requires: [],
-  prompt: "Hello! Let's get started with your information.",
-});
-
-// Or configure any step
-const askName = route.initialStep.nextStep({ prompt: "Ask for name" });
-askName.configure({
-  collect: ["firstName", "lastName"],
-});
-```
-
-**Parameters:**
-
-- `config`: Configuration object with optional properties:
-  - `description?: string` - Step description
-  - `collect?: string[]` - Fields to collect in this step
-  - `skipIf?: (data: Partial<TData>) => boolean` - Skip condition function
-  - `requires?: string[]` - Required data prerequisites
-  - `prompt?: Template<TContext, TData>` - Step prompt template
-
-**Returns:** `this` for method chaining
-
-#### Properties
-
-##### `id: string`
-
-Unique step identifier (readonly).
-
-##### `routeId: string`
-
-ID of the route this step belongs to (readonly).
-
-##### `description: string`
-
-Step description (readonly).
-
----
-
-### `StepResult`
-
-Result interface returned by step transition methods that enables fluent chaining of conversation flows. Combines step reference with the ability to chain transitions and create branches.
-
-#### Interface
-
-```typescript
-interface StepResult<TContext = unknown, TData = unknown> extends StepRef {
-  /** Allow chaining transitions */
-  nextStep: (spec: StepOptions<TContext, TData>) => StepResult<TContext, TData>;
-  /** Create multiple branches from this step */
-  branch: (
-    branches: BranchSpec<TContext, TData>[]
-  ) => BranchResult<TContext, TData>;
-  /** Shortcut to end the current route */
-  endRoute: (options?: Omit<StepOptions<TContext, TData>, "step">) => StepResult<TContext, TData>;
-}
-```
-
-#### Methods
-
-##### `nextStep(spec: StepOptions<TContext, TData>): StepResult<TContext, TData>`
-
-Creates a transition from this step and returns a chainable result for building linear flows.
-
-**Example:**
-
-```typescript
-// Linear flow chaining
-const flow = route.initialStep
-  .nextStep({
-    prompt: "Ask for destination",
-    collect: ["destination"]
-  })
-  .nextStep({
-    prompt: "Ask for dates", 
-    collect: ["departureDate", "returnDate"]
-  })
-  .nextStep({
-    prompt: "Confirm booking details"
-  });
-```
-
-##### `branch(branches: BranchSpec<TContext, TData>[]): BranchResult<TContext, TData>`
-
-Creates multiple conditional branches from this step for complex conversation flows.
-
-**Example:**
-
-```typescript
-// Branching flow
-const branches = askIssueType.branch([
-  {
-    name: "technical",
-    step: {
-      prompt: "Let me help with your technical issue",
-      when: "issue type is technical"
-    }
-  },
-  {
-    name: "billing", 
-    step: {
-      prompt: "I'll connect you with billing support",
-      when: "issue type is billing"
-    }
-  }
-]);
-
-// Continue each branch independently
-branches.technical.nextStep({ prompt: "What device are you using?" });
-branches.billing.nextStep({ prompt: "What's your account number?" });
-```
-
-##### `endRoute(options?: Omit<StepOptions<TContext, TData>, "step">): StepResult<TContext, TData>`
-
-Shortcut method to end the current route with optional completion configuration.
-
-**Example:**
-
-```typescript
-// Simple route completion
-askConfirmation.endRoute();
-
-// Route completion with final message
-askConfirmation.endRoute({
-  prompt: "Thank you! Your booking is confirmed."
-});
-```
-
-#### Properties
-
-Inherits all properties from `StepRef`:
-
-##### `id: string`
-
-Step identifier (readonly).
-
-##### `routeId: string`
-
-Route this step belongs to (readonly).
-
----
-
----
-
-## Tool Execution
-
-Tools provide a powerful way to execute custom logic, access external APIs, and enrich conversation context before AI response generation.
-
-**See Also:** [Tool Definition](../core/tools/tool-definition.md) - Complete guide to tool creation and configuration
-
----
-
-### `AnthropicProvider`
-
-AI provider implementation for Anthropic (Claude models).
-
-#### Constructor
-
-```typescript
-new AnthropicProvider(options: AnthropicProviderOptions)
-
-interface AnthropicProviderOptions {
-  apiKey: string;
-  model: string;               // Required: e.g., "claude-sonnet-4-5"
-  backupModels?: string[];     // Fallback models
-  config?: Partial<Omit<MessageCreateParamsNonStreaming, "model" | "messages" | "max_tokens">>;
-  retryConfig?: {
-    timeout?: number;          // Default: 60000ms
-    retries?: number;          // Default: 3
-  };
-}
-```
-
-**Note:** `model` is required for AnthropicProvider. Available models include:
-
-- `claude-sonnet-4-5` - Latest Claude Sonnet 4.5 (most capable)
-- `claude-opus-4-1` - Claude Opus 4.1 (powerful for complex tasks)
-- `claude-sonnet-4-0` - Claude Sonnet 4.0 (stable, production-ready)
-
-#### Methods
-
-##### `generateMessage<TContext>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>`
-
-Generates a message with retry logic and backup models using Anthropic's API.
-
-**Example:**
-
-```typescript
-import { AnthropicProvider } from "@falai/agent";
-
-const provider = new AnthropicProvider({
-  apiKey: process.env.ANTHROPIC_API_KEY!,
-  model: "claude-sonnet-4-5",
-  backupModels: ["claude-opus-4-1", "claude-sonnet-4-0"],
-  config: {
-    temperature: 0.7,
-    top_p: 0.9,
-  },
-  retryConfig: {
-    timeout: 60000,
-    retries: 3,
-  },
-});
-```
-
----
-
-### `GeminiProvider`
-
-AI provider implementation for Google Gemini.
-
-#### Constructor
-
-```typescript
-new GeminiProvider(options: GeminiProviderOptions)
-
-interface GeminiProviderOptions {
-  apiKey: string;
-  model?: string;              // Default: "models/gemini-2.5-flash"
-  backupModels?: string[];     // Fallback models
-  retryConfig?: {
-    timeout?: number;          // Default: 60000ms
-    retries?: number;          // Default: 3
-  };
-}
-```
-
-#### Methods
-
-##### `generateMessage<TContext>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>`
-
-Generates a message with retry logic and backup models.
-
----
-
-### `OpenAIProvider`
-
-AI provider implementation for OpenAI (GPT models).
-
-#### Constructor
-
-```typescript
-new OpenAIProvider(options: OpenAIProviderOptions)
-
-interface OpenAIProviderOptions {
-  apiKey: string;
-  model: string;               // Required: e.g., "gpt-4o", "gpt-5"
-  backupModels?: string[];     // Fallback models
-  retryConfig?: {
-    timeout?: number;          // Default: 60000ms
-    retries?: number;          // Default: 3
-  };
-}
-```
-
-**Note:** Unlike GeminiProvider, `model` is required for OpenAIProvider. Choose from available OpenAI models like "gpt-4o", "gpt-5", "gpt-4-turbo", etc.
-
-#### Methods
-
-##### `generateMessage<TContext>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>`
-
-Generates a message with retry logic and backup models using OpenAI's API.
-
-**Example:**
-
-```typescript
-import { OpenAIProvider } from "@falai/agent";
-
-const provider = new OpenAIProvider({
-  apiKey: process.env.OPENAI_API_KEY!,
-  model: "gpt-5",
-  backupModels: ["gpt-4o", "gpt-4-turbo"],
-  retryConfig: {
-    timeout: 60000,
-    retries: 3,
-  },
-});
-```
-
----
-
-### `OpenRouterProvider`
-
-AI provider implementation for OpenRouter (access to 200+ models).
-
-#### Constructor
-
-```typescript
-new OpenRouterProvider(options: OpenRouterProviderOptions)
-
-interface OpenRouterProviderOptions {
-  apiKey: string;
-  model: string;               // Required: e.g., "openai/gpt-5", "anthropic/claude-sonnet-4-5"
-  backupModels?: string[];     // Fallback models
-  siteUrl?: string;            // Optional: your app URL for OpenRouter rankings
-  siteName?: string;           // Optional: your app name for OpenRouter rankings
-  retryConfig?: {
-    timeout?: number;          // Default: 60000ms
-    retries?: number;          // Default: 3
-  };
-}
-```
-
-**Note:** OpenRouter provides access to models from multiple providers. Model names follow the format `provider/model-name` (e.g., "openai/gpt-5", "anthropic/claude-sonnet-4-5", "google/gemini-pro").
-
-#### Methods
-
-##### `generateMessage<TContext>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>`
-
-Generates a message with retry logic and backup models using OpenRouter's API.
-
-**Example:**
-
-```typescript
-import { OpenRouterProvider } from "@falai/agent";
-
-const provider = new OpenRouterProvider({
-  apiKey: process.env.OPENROUTER_API_KEY!,
-  model: "openai/gpt-5",
-  backupModels: ["anthropic/claude-sonnet-4-5", "google/gemini-pro"],
-  siteUrl: "https://yourapp.com",
-  siteName: "Your App Name",
-  retryConfig: {
-    timeout: 60000,
-    retries: 3,
-  },
-});
-```
-
-**See Also:** [AI Providers](../core/ai-integration/providers.md) for detailed provider comparison and configuration examples.
-
----
-
-## Persistence Adapters
-
-Optional persistence for auto-saving sessions and messages. All adapters implement the `PersistenceAdapter` interface.
-
-### `PersistenceManager`
-
-Manages persistence operations for sessions and messages.
-
-#### Constructor
-
-```typescript
-new PersistenceManager(config: PersistenceConfig)
-
-interface PersistenceConfig {
-  adapter: PersistenceAdapter;
-  autoSave?: boolean;    // Default: true
-  userId?: string;       // Optional: associate with user
-}
-```
-
-#### Methods
-
-##### `createSession(data: Partial<SessionData>): Promise<SessionData>`
-
-Creates a new conversation session.
-
-```typescript
-const session = await persistence.createSession({
-  userId: "user_123",
-  agentName: "Support Bot",
-  initialData: { channel: "web" },
-});
-```
-
-##### `getSession(sessionId: string): Promise<SessionData | null>`
-
-Retrieves a session by ID.
-
-##### `findActiveSession(userId: string): Promise<SessionData | null>`
-
-Finds the active session for a user.
-
-##### `getUserSessions(userId: string, limit?: number): Promise<SessionData[]>`
-
-Gets all sessions for a user.
-
-##### `updateSessionStatus(sessionId: string, status: SessionStatus): Promise<SessionData | null>`
-
-Updates session status ("active" | "completed" | "abandoned").
-
-##### `saveMessage(data: Partial<MessageData>): Promise<MessageData>`
-
-Saves a message to the database.
-
-```typescript
-await persistence.saveMessage({
-  sessionId: session.id,
-  role: "user",
-  content: "Hello!",
-});
-```
-
-##### `getSessionMessages(sessionId: string, limit?: number): Promise<MessageData[]>`
-
-Gets all messages for a session.
-
-##### `loadSessionHistory(sessionId: string, limit?: number): Promise<Event[]>`
-
-Loads session history in Event format for agent.respond().
-
-```typescript
-const history = await persistence.loadSessionHistory(sessionId);
-const response = await agent.respond({ history });
-```
-
-##### `completeSession(sessionId: string): Promise<SessionData | null>`
-
-Marks a session as completed.
-
-##### `abandonSession(sessionId: string): Promise<SessionData | null>`
-
-Marks a session as abandoned.
-
-##### `updateCollectedData(sessionId: string, collectedData: Record<string, unknown>): Promise<SessionData | null>`
-
-Updates collected data in session.
-
-##### `updateRouteStep(sessionId: string, route?: string, step?: string): Promise<SessionData | null>`
-
-Updates current route and step in session.
-
-##### `getUserMessages(userId?: string, limit?: number): Promise<MessageData[]>`
-
-Gets messages for a user.
-
-##### `deleteSession(sessionId: string): Promise<boolean>`
-
-Deletes a session and all its messages.
-
-##### `messageToEvent(message: MessageData): Event | undefined`
-
-Helper: Convert message data to Event format.
-
-##### `saveSessionState(sessionId: string, sessionStep: SessionState): Promise<SessionData | null>`
-
-Saves SessionState to database by converting to SessionData.
-
-```typescript
-const saved = await persistence.saveSessionState(sessionId, sessionState);
-```
-
-##### `loadSessionState(sessionId: string): Promise<SessionState | null>`
-
-Loads SessionState from database by converting from SessionData.
-
-```typescript
-const sessionState = await persistence.loadSessionState(sessionId);
-```
-
-##### `createSessionWithStep(options: CreateSessionOptions): Promise<{ sessionData: SessionData; sessionStep: SessionState }>`
-
-Creates a new session with both SessionData and initialized SessionState.
-
-```typescript
-const { sessionData, sessionStep } = await persistence.createSessionWithStep({
-  userId: "user_123",
-  agentName: "Travel Agent",
-  initialData: { channel: "web" },
-});
-```
-
----
-
-### `RoutingEngine<TContext, TData>`
-
-Handles route and step selection logic for conversation orchestration.
-
-#### Constructor
-
-```typescript
-new RoutingEngine<TContext, TData>(options?: RoutingEngineOptions)
-
-interface RoutingEngineOptions {
-  routeSwitchMargin?: number;  // Default: 15 (0-100)
-}
-```
-
-#### Methods
-
-##### `decideRouteAndStep(params): Promise<RoutingDecision>`
-
-Combines route selection and step selection into a single orchestrated decision.
-
-**Parameters:**
-
-- `routes`: Array of available routes
-- `session`: Current session state
-- `history`: Conversation history
-- `agentOptions`: Agent metadata
-- `provider`: AI provider for scoring
-- `context`: Agent context
-- `signal`: Optional abort signal
-
-**Returns:** Routing decision with selected route, step, directives, and updated session
-
----
-
-### `ResponseEngine<TContext>`
-
-Builds prompts and response schemas for AI message generation.
-
-#### Constructor
-
-```typescript
-new ResponseEngine<TContext>();
-```
-
-#### Methods
-
-##### `responseSchemaForRoute(route, currentStep?): StructuredSchema`
-
-Builds JSON schema for AI responses based on route and current step.
-
-##### `buildResponsePrompt(params): Promise<string>`
-
-Builds a comprehensive prompt for AI response generation including context, guidelines, and route information.
-
-**Parameters:**
-
-- `route`: Current route
-- `currentStep`: Current step in route
-- `rules`: Route-specific rules
-- `prohibitions`: Route-specific prohibitions
-- `directives`: Response directives
-- `history`: Conversation history
-- `lastMessage`: Last user message
-- `agentOptions`: Agent metadata
-- `context`: Agent context
-- `session`: Current session state
-
-##### `buildFallbackPrompt(params): Promise<string>`
-
-Builds a fallback prompt when no routes are configured.
-
----
-
-### `Events`
-
-Utility functions for creating and adapting conversation events.
-
-#### Functions
-
-##### `adaptEvent(event): string`
-
-Adapts an event for inclusion in AI prompts by transforming it into serializable format.
-
-```typescript
-const promptText = adaptEvent(messageEvent);
-```
-
-##### History Format
-
-For conversation history, use the simplified `History` type instead of manually creating events. See the [History Format](#history-format) section below for details.
-
-##### `createToolEvent(source, toolCalls, timestamp?): Event`
-
-Creates a tool execution event.
-
-```typescript
-const toolEvent = createToolEvent(MessageRole.AGENT, [
-  { tool_id: "search_flights", arguments: { from: "NYC", to: "LAX" }, result: { flights: [...] } }
-]);
-```
-
----
-
-### `PrismaAdapter`
-
-Type-safe ORM adapter with migrations support.
-
-#### Constructor
-
-```typescript
-new PrismaAdapter(options: PrismaAdapterOptions)
-
-interface PrismaAdapterOptions {
-  prisma: PrismaClient;
-  autoMigrate?: boolean;      // Default: false
-  tables?: {
-    sessions?: string;        // Default: "AgentSession"
-    messages?: string;        // Default: "AgentMessage"
-  };
-  fieldMappings?: FieldMappings;  // Custom field names
-}
-```
-
-#### Example
-
-```typescript
-import { PrismaAdapter } from "@falai/agent";
-import { PrismaClient } from "@prisma/client";
-
-const prisma = new PrismaClient();
-
-const agent = new Agent({
-  persistence: {
-    adapter: new PrismaAdapter({
-      prisma,
-      autoMigrate: true, // Auto-run migrations
-      tables: {
-        sessions: "CustomSessions",
-        messages: "CustomMessages",
-      },
-    }),
-    userId: "user_123",
-  },
-});
-```
-
-**Schema Example:** See [examples/prisma-schema.example.prisma](../../examples/persistence/prisma-schema.example.prisma)
-
-**Full Example:** See [examples/database-persistence.ts](../../examples/persistence/database-persistence.ts)
-
----
-
-### `RedisAdapter`
-
-Fast, in-memory persistence for high-throughput applications.
-
-#### Constructor
-
-```typescript
-new RedisAdapter(options: RedisAdapterOptions)
-
-interface RedisAdapterOptions {
-  redis: RedisClient;         // ioredis or redis client
-  keyPrefix?: string;         // Default: "agent:"
-  sessionTTL?: number;        // Default: 7 days (in seconds)
-  messageTTL?: number;        // Default: 30 days (in seconds)
-}
-```
-
-#### Example
-
-```typescript
-import { RedisAdapter } from "@falai/agent";
-import Redis from "ioredis";
-
-const redis = new Redis();
-
-const agent = new Agent({
-  persistence: {
-    adapter: new RedisAdapter({
-      redis,
-      keyPrefix: "chat:",
-      sessionTTL: 24 * 60 * 60, // 24 hours
-      messageTTL: 7 * 24 * 60 * 60, // 7 days
-    }),
-  },
-});
-```
-
-**Install:** `npm install ioredis` or `npm install redis`
-
-**Full Example:** See [examples/redis-persistence.ts](../../examples/persistence/redis-persistence.ts)
-
----
-
-### `MongoAdapter`
-
-Document-based storage with flexible schema.
-
-#### Constructor
-
-```typescript
-new MongoAdapter(options: MongoAdapterOptions)
-
-interface MongoAdapterOptions {
-  client: MongoClient;
-  databaseName: string;
-  collections?: {
-    sessions?: string;        // Default: "agent_sessions"
-    messages?: string;        // Default: "agent_messages"
-  };
-}
-```
-
-#### Example
-
-```typescript
-import { MongoAdapter } from "@falai/agent";
-import { MongoClient } from "mongodb";
-
-const client = new MongoClient("mongodb://localhost:27017");
-await client.connect();
-
-const agent = new Agent({
-  persistence: {
-    adapter: new MongoAdapter({
-      client,
-      databaseName: "myapp",
-      collections: {
-        sessions: "chat_sessions",
-        messages: "chat_messages",
-      },
-    }),
-  },
-});
-```
-
-**Install:** `npm install mongodb`
-
----
-
-### `PostgreSQLAdapter`
-
-Raw SQL adapter with auto table/index creation.
-
-#### Constructor
-
-```typescript
-new PostgreSQLAdapter(options: PostgreSQLAdapterOptions)
-
-interface PostgreSQLAdapterOptions {
-  client: PgClient;           // pg client
-  tables?: {
-    sessions?: string;        // Default: "agent_sessions"
-    messages?: string;        // Default: "agent_messages"
-  };
-}
-```
-
-#### Methods
-
-##### `initialize(): Promise<void>`
-
-Creates tables and indexes if they don't exist.
-
-#### Example
-
-```typescript
-import { PostgreSQLAdapter } from "@falai/agent";
-import { Client } from "pg";
-
-const client = new Client({
-  host: "localhost",
-  database: "myapp",
-  user: "postgres",
-  password: "password",
-});
-await client.connect();
-
-const adapter = new PostgreSQLAdapter({ client });
-
-// Auto-create tables
-await adapter.initialize();
-
-const agent = new Agent({
-  persistence: { adapter },
-});
-```
-
-**Install:** `npm install pg`
-
----
-
-### `SQLiteAdapter`
-
-Lightweight, file-based database for local development.
-
-#### Constructor
-
-```typescript
-new SQLiteAdapter(options: SQLiteAdapterOptions)
-
-interface SQLiteAdapterOptions {
-  db: SqliteDatabase;           // better-sqlite3 database
-  tables?: {
-    sessions?: string;          // Default: "agent_sessions"
-    messages?: string;          // Default: "agent_messages"
-  };
-}
-```
-
-#### Methods
-
-##### `initialize(): Promise<void>`
-
-Creates tables and indexes if they don't exist.
-
-#### Example
-
-```typescript
-import { SQLiteAdapter } from "@falai/agent";
-import Database from "better-sqlite3";
-
-const db = new Database("agent.db");
-const adapter = new SQLiteAdapter({ db });
-
-// Auto-create tables
-await adapter.initialize();
-
-const agent = new Agent({
-  persistence: { adapter },
-});
-```
-
-**Install:** `npm install better-sqlite3`
-
-**Perfect for:** Local development, testing, desktop apps, single-user applications
-
----
-
-### `OpenSearchAdapter`
-
-Full-text search and analytics-powered persistence. Compatible with OpenSearch and Elasticsearch 7.x.
-
-#### Constructor
-
-```typescript
-new OpenSearchAdapter(client: OpenSearchClient, options?: OpenSearchAdapterOptions)
-
-interface OpenSearchAdapterOptions {
-  indices?: {
-    sessions?: string;        // Default: "agent_sessions"
-    messages?: string;        // Default: "agent_messages"
-  };
-  autoCreateIndices?: boolean; // Default: true
-  refresh?: boolean | "wait_for"; // Default: false
-}
-```
-
-#### Methods
-
-##### `initialize(): Promise<void>`
-
-Creates indices with proper mappings if they don't exist.
-
-##### `disconnect(): Promise<void>`
-
-Gracefully disconnect (no-op for OpenSearch - connection pooling is automatic).
-
-#### Example
-
-```typescript
-import { OpenSearchAdapter } from "@falai/agent";
-import { Client } from "@opensearch-project/opensearch";
-
-const client = new Client({
-  node: "https://localhost:9200",
-  auth: {
-    username: "admin",
-    password: "admin",
-  },
-});
-
-const adapter = new OpenSearchAdapter(client, {
-  indices: {
-    sessions: "agent_sessions",
-    messages: "agent_messages",
-  },
-  autoCreateIndices: true,
-  refresh: "wait_for", // Wait for documents to be searchable
-});
-
-// Auto-create indices with mappings
-await adapter.initialize();
-
-const agent = new Agent({
-  persistence: { adapter },
-});
-```
-
-**Install:** `npm install @opensearch-project/opensearch`
-
-**Perfect for:** Full-text search, analytics, time-series analysis, AWS OpenSearch Service, Elasticsearch 7.x users
-
----
-
-### `MemoryAdapter`
-
-Zero-dependency in-memory storage for testing and development.
-
-#### Constructor
-
-```typescript
-new MemoryAdapter();
-```
-
-No options needed - it's ready to go! ✨
-
-#### Methods
-
-##### `clear(): void`
-
-Clears all stored data (useful for testing).
-
-##### `getSnapshot(): { sessions: SessionData[]; messages: MessageData[] }`
-
-Returns a snapshot of all data (useful for debugging/testing).
-
-#### Example
-
-```typescript
-import { MemoryAdapter } from "@falai/agent";
-
-const adapter = new MemoryAdapter();
-
-const agent = new Agent({
-  persistence: { adapter },
-});
-
-// Perfect for unit tests!
-```
-
-**Testing Example:**
-
-```typescript
-describe("Agent", () => {
-  const adapter = new MemoryAdapter();
-
-  afterEach(() => {
-    adapter.clear(); // Reset between tests
-  });
-
-  it("should persist messages", async () => {
-    const agent = new Agent({
-      persistence: { adapter },
-    });
-
-    // ... test logic ...
-
-    const { sessions, messages } = adapter.getSnapshot();
-    expect(sessions).toHaveLength(1);
-    expect(messages).toHaveLength(2);
-  });
-});
-```
-
-**No installation required** - built into the framework!
-
----
-
-### Persistence Types
-
-#### `SessionData`
-
-```typescript
-interface SessionData {
-  id: string;
-  userId?: string;
-  agentName?: string;
-  status: SessionStatus; // "active" | "completed" | "abandoned"
-  currentRoute?: string;
-  currentStep?: string;
-  collectedData?: Record<string, unknown>;
-  messageCount: number;
-  lastMessageAt?: Date;
-  completedAt?: Date;
-  createdAt: Date;
-  updatedAt: Date;
-}
-```
-
-#### `MessageData`
-
-```typescript
-interface MessageData {
-  id: string;
-  sessionId: string;
-  userId?: string;
-  role: MessageRole; // "user" | "assistant" | "agent" | "system"
-  content: string;
-  route?: string;
-  step?: string;
-  toolCalls?: Array<{
-    toolName: string;
-    arguments: Record<string, unknown>;
-    result?: unknown;
-  }>;
-  event?: Event;
-  createdAt: Date;
-}
-```
-
-#### `PersistenceAdapter`
-
-Interface for creating custom adapters:
-
-```typescript
-interface PersistenceAdapter {
-  sessionRepository: SessionRepository;
-  messageRepository: MessageRepository;
-  initialize?(): Promise<void>; // Optional: setup tables/indexes
-  disconnect?(): Promise<void>; // Optional: cleanup
-}
-```
-
-**See Also:**
-
-- [Session Storage](../core/persistence/session-storage.md) - Session persistence patterns
-- [Database Adapters](../core/persistence/adapters.md) - Adapter comparison and details
-
----
-
-### `PromptBuilder`
-
-Constructs prompts for AI generation.
-
-#### Methods
-
-##### `addIdentity(name: string, description?: string, goal?: string): this`
-
-Adds agent identity section.
-
-##### `addContext(variables: ContextVariable[]): this`
-
-Adds context variables.
-
-##### `addGlossary(terms: Term[]): this`
-
-Adds domain glossary terms.
-
-##### `addGuidelinesForMessageGeneration(guidelines: GuidelineMatch[]): this`
-
-Adds guidelines section.
-
-##### `addActiveRoutes(routes): this`
-
-Adds active routes to the prompt.
-
-##### `build(): string`
-
-Builds the final prompt string.
-
----
-
-### `PromptComposer`
-
-Constructs prompts for AI generation.
-
-**Note:** As of the latest version, many methods in `PromptComposer` are `async` to support function-based templates.
-
-#### Methods
-
-##### `addIdentity(name: string, description?: string, goal?: string): this`
-
-Adds agent identity section.
-
-##### `addContext(variables: ContextVariable[]): this`
-
-Adds context variables.
-
-##### `addGlossary(terms: Term[]): this`
-
-Adds domain glossary terms.
-
-##### `addGuidelinesForMessageGeneration(guidelines: GuidelineMatch[]): this`
-
-Adds guidelines section.
-
-##### `addActiveRoutes(routes): this`
-
-Adds active routes to the prompt.
-
-##### `build(): Promise<string>`
-
-Builds the final prompt string.
-
----
-
-## Utility Functions
-
-### `Tool<TContext, TArgs, TResult, TData>`
-
-Defines a type-safe tool using the Tool interface.
-
-```typescript
-interface Tool<
-  TContext = unknown,
-  TArgs extends unknown[] = unknown[],
-  TResult = unknown,
-  TData = unknown
-> {
-  id: string; // Unique tool identifier
-  description?: string; // Description for AI discovery
-  parameters?: unknown; // JSON Schema for tool parameters
-  handler: ToolHandler<TContext, TArgs, TResult, TData>; // Tool execution handler
-}
-```
-
-**Example:**
-
-```typescript
-const getTool: Tool<MyContext, [id: string], Data> = {
-  id: "get_data",
-  description: "Fetches data by ID",
-  parameters: {
-    type: "object",
-    properties: {
-      id: { type: "string", description: "The data ID to fetch" },
-    },
-    required: ["id"],
-  },
-  handler: async (toolContext, args) => {
-    return { data: await fetchData(args.id) };
-  },
-};
-```
-
----
-
-### `formatKnowledgeBase(data, title?, maxDepth?)`
-
-Formats a JSON structure into readable markdown format for AI prompts. Handles nested objects, arrays, and primitive values.
-
-```typescript
-formatKnowledgeBase(
-  data: Record<string, unknown> | unknown,
-  title?: string,
-  maxDepth?: number
-): string
-```
-
-**Parameters:**
-
-- `data` - The JSON data to format
-- `title` - Optional title for the knowledge base section
-- `maxDepth` - Maximum nesting depth (default: 3)
-
-**Returns:** Formatted markdown string
-
-**Example:**
-
-```typescript
-import { formatKnowledgeBase } from "@falai/agent";
-
-const knowledge = {
-  company: {
-    name: "Acme Corp",
-    products: ["Widget A", "Widget B"],
-    locations: {
-      headquarters: "NYC",
-      branches: ["LA", "Chicago"],
-    },
-  },
-};
-
-const markdown = formatKnowledgeBase(knowledge, "Company Information");
-// Output:
-// ## Company Information
-//
-// - **name**: Acme Corp
-// - **products**:
-//   - Widget A
-//   - Widget B
-// - **locations**:
-//   - **headquarters**: NYC
-//   - **branches**:
-//     - LA
-//     - Chicago
-```
-
----
-
-### History Format
-
-The agent accepts a simplified history format for conversation context. This format is easier to use than the internal Event structure.
-
-#### Types
-
-```typescript
-type Role = "user" | "assistant" | "tool" | "system";
-
-type HistoryItem =
-  | {
-      role: "user";
-      content: string;
-      name?: string; // Optional participant name
-    }
-  | {
-      role: "assistant";
-      content: string | null;
-      tool_calls?: Array<{
-        id: string;
-        name: string;
-        arguments: Record<string, unknown>;
-      }>;
-    }
-  | {
-      role: "tool";
-      tool_call_id: string;
-      name: string;
-      content: any;
-    }
-  | {
-      role: "system";
-      content: string;
-    };
-
-type History = HistoryItem[];
-```
-
-**Example:**
-
-```typescript
-// Simple conversation history
-const history: History = [
-  {
-    role: "user",
-    content: "Hello! Can you help me book a flight?",
-    name: "Alice"
-  },
-  {
-    role: "assistant",
-    content: "I'd be happy to help you book a flight. Where would you like to go?"
-  },
-  {
-    role: "user",
-    content: "I want to go to Paris next Friday for 2 people.",
-    name: "Alice"
-  }
-];
-
-// Assistant with tool calls
-const historyWithTools: History = [
-  {
-    role: "assistant",
-    content: "I'll search for flights to Paris.",
-    tool_calls: [
-      {
-        id: "search_flights_1",
-        name: "search_flights",
-        arguments: {
-          destination: "Paris",
-          date: "2025-10-18",
-          passengers: 2
-        }
-      }
-    ]
-  },
-  {
-    role: "tool",
-    tool_call_id: "search_flights_1",
-    name: "search_flights",
-    content: { flights: [...] }  // Tool execution result
-  }
-];
-```
-
----
-
-### `createToolEvent()`
-
-Creates a tool execution event.
-
-```typescript
-createToolEvent(
-  source: MessageRole,
-  toolCalls: ToolCall[],
-  timestamp?: string  // Optional: provide custom timestamp (ISO 8601 format)
-): Event
-```
-
-**Example:**
-
-```typescript
-// With auto-generated timestamp
-createToolEvent(MessageRole.AGENT, [
-  { tool_id: "get_data", arguments: { id: "123" }, result: { data: {...} } }
-]);
-
-// With custom timestamp
-createToolEvent(
-  MessageRole.AGENT,
-  [{ tool_id: "get_data", arguments: { id: "123" }, result: { data: {...} } }],
-  "2025-10-13T10:30:00Z"
-);
-```
-
----
-
-### `adaptEvent()`
-
-Adapts an event to the internal format.
-
-```typescript
-adaptEvent(event: EmittedEvent): Event
-```
-
----
-
-## Type Definitions
-
-### `Term`
-
-```typescript
-interface Term<TContext = unknown> {
-  name: Template<TContext>;
-  description: Template<TContext>;
-  synonyms?: Template<TContext>[];
-}
-```
-
----
-
-### `Guideline`
-
-```typescript
-interface Guideline<TContext = unknown, TData = unknown> {
-  id?: string;
-  condition?: ConditionTemplate<TContext, TData>; // ENHANCED: Flexible condition for guideline activation
-  action: Template<TContext>;
-  enabled?: boolean; // Default: true
-  tags?: string[];
-  tools?: ToolRef[];
-  metadata?: Record<string, unknown>;
-}
-```
-
----
-
-### `RouteLifecycleHooks<TContext, TData>`
-
-Route lifecycle hooks for managing route-specific data and behavior.
-
-```typescript
-interface RouteLifecycleHooks<TContext = unknown, TData = unknown> {
-  /**
-   * Called after collected data is updated for this route (from AI response or tool execution)
-   * Useful for validation, enrichment, or persistence of route-specific collected data
-   * Return modified collected data or the same data to keep it unchanged
-   *
-   * Unlike Agent-level onDataUpdate, this only triggers for data changes in this specific route.
-   */
-  onDataUpdate?: (
-    data: Partial<TData>,
-    previousCollected: Partial<TData>
-  ) => Partial<TData> | Promise<Partial<TData>>;
-
-  /**
-   * Called after context is updated via updateContext() when this route is active
-   * Useful for route-specific context reactions, validation, or side effects
-   *
-   * Unlike Agent-level onContextUpdate, this only triggers when this specific route is active.
-   */
-  onContextUpdate?: (
-    newContext: TContext,
-    previousContext: TContext
-  ) => void | Promise<void>;
-}
-```
-
----
-
----
-
-### `Event`
-
-```typescript
-interface Event {
-  kind: EventKind;
-  source: MessageRole;
-  data: MessageEventData | ToolEventData | StatusEventData;
-  creation_utc: string;
-}
-
-enum EventKind {
-  MESSAGE = "message",
-  TOOL = "tool",
-  STATUS = "status",
-}
-
-enum MessageRole {
-  USER = "user",
-  ASSISTANT = "assistant",
-  AGENT = "agent",
-  SYSTEM = "system",
-}
-```
-
----
-
-### `ToolContext<TContext>`
-
-```typescript
-interface ToolContext<TContext> {
-  context: TContext;
-  // Additional runtime context
-}
-```
-
----
-
-### `ToolResult<TReturn>`
-
-```typescript
-interface ToolResult<TReturn> {
-  data: TReturn;
-  error?: string;
-}
-```
-
----
-
-### `RoutingDecision`
-
-Result of route and step selection process.
-
-```typescript
-interface RoutingDecision {
-  context: string;
-  routes: Record<string, number>; // Route scores
-  responseDirectives?: string[];
-  extractions?: unknown;
-  contextUpdate?: Record<string, unknown>;
-}
-```
-
----
-
-### `ToolExecutionResult`
-
-Result of tool execution.
-
-```typescript
-interface ToolExecutionResult {
-  toolName: string;
-  success: boolean;
-  data?: unknown;
-  contextUpdate?: Record<string, unknown>;
-  dataUpdate?: Record<string, unknown>;
-  error?: string;
-}
-```
-
----
-
-## Types
-
-### `SessionState<TData>`
-
-Tracks the current position in the conversation flow and data collected during route progression.
-
-```typescript
-interface SessionState<TData = Record<string, unknown>> {
-  /** Unique session identifier (useful for persistence) */
-  id?: string;
-
-  /** Current route the conversation is in */
-  currentRoute?: {
-    id: string;
-    title: string;
-    enteredAt: Date;
-  };
-
-  /** Current step within the route */
-  currentStep?: {
-    id: string;
-    description?: string;
-    enteredAt: Date;
-  };
-
-  /**
-   * Data collected during the current route
-   * Convenience reference to dataByRoute[currentRoute.id]
-   */
-  data?: Partial<TData>;
-
-  /**
-   * Data collected organized by route ID
-   * Persists data when switching between routes
-   * Allows resuming incomplete routes where they left off
-   */
-  dataByRoute?: Record<string, Partial<unknown>>;
-
-  /** History of routes visited in this session */
-  routeHistory: Array<{
-    routeId: string;
-    enteredAt: Date;
-    exitedAt?: Date;
-    completed: boolean;
-  }>;
-
-  /**
-   * Pending route transition after completion
-   * Set when a route completes with onComplete handler
-   */
-  pendingTransition?: {
-    targetRouteId: string;
-    condition?: string;
-    reason: "route_complete" | "manual";
-  };
-
-  /** Session metadata */
-  metadata?: {
-    createdAt?: Date;
-    lastUpdatedAt?: Date;
-    [key: string]: unknown;
-  };
-}
-```
-
-**Key Features:**
-
-- **`id`** - Optional session identifier that persists across database operations
-- **`data`** - Type-safe data collected via `schema` for the **current route**
-- **`dataByRoute`** - **Per-route data map that preserves collected data when switching routes**
-- **`currentRoute`** / **`currentStep`** - Track conversation position
-- **`routeHistory`** - Full audit trail of route transitions
-- **`pendingTransition`** - Handles route completion transitions
-- **`metadata`** - Custom data (timestamps, user info, etc.)
-
-**Per-Route Data Preservation:**
-
-When users switch routes (e.g., "Actually, I want to book a hotel instead"), the framework automatically:
-
-- Saves current route's `data` data to `dataByRoute[routeId]`
-- Loads the new route's data from `dataByRoute[newRouteId]` (if resuming)
-- Keeps `data` as a convenient reference to the current route's data
-
-This allows users to:
-
-- Switch routes without losing progress
-- Resume incomplete routes where they left off
-- Access historical data from previous routes via `session.dataByRoute["route_id"]`
-
-**Usage:**
-
-```typescript
-interface FlightData {
-  destination: string;
-  departureDate: string;
-}
-
-// Create session with database ID
-const session = createSession<FlightData>("session_abc123");
-
-// Use in conversation
-const response = await agent.respond({ history, session });
-
-// Access collected data
-console.log(response.session?.data.destination); // Type-safe!
-```
-
----
-
-### Session Helper Functions
-
-#### `createSession<TData>(sessionId?, metadata?): SessionState<TData>`
-#### `createSession<TData>(state: Partial<SessionState<TData>>): SessionState<TData>`
-
-Creates a new session state object. Supports two overloaded signatures:
-
-**Signature 1 — ID + metadata (original):**
-
-- `sessionId` (optional): Unique session identifier from database
-- `metadata` (optional): Additional metadata to attach
-
-**Signature 2 — Partial state (new):**
-
-- `state`: A `Partial<SessionState<TData>>` object that is merged with sensible defaults (auto-generated `id`, empty `data`, empty `routeHistory`, and timestamped `metadata`)
-
-**Example:**
-
-```typescript
-// Simple usage
-const session = createSession<OnboardingData>();
-
-// With database ID (when loading from persistence)
-const session = createSession<OnboardingData>("session_123");
-
-// With metadata
-const session = createSession<OnboardingData>("session_123", {
-  userId: "user_456",
-  channel: "whatsapp",
-});
-
-// NEW: From partial state — pre-populate any fields
-const session = createSession<OnboardingData>({
-  id: "session_123",
-  data: { fullName: "Alice" },
-  history: previousHistory,
-  currentRoute: { id: "onboarding", title: "Onboarding" },
-});
-
-// NEW: Minimal partial — only override what you need
-const session = createSession<OnboardingData>({
-  history: restoredHistory,
-});
-```
-
-#### `createSessionId(): string`
-
-Generates a unique session ID string in the format `session_{timestamp}_{random}`. Use this when you need to generate an ID without creating a full session object.
-
-**Example:**
-
-```typescript
-const id = createSessionId();
-// e.g. "session_1709388025123_k8f2m9x"
-```
-
-#### `enterRoute<TData>(session, routeId, routeTitle): SessionState<TData>`
-
-Updates session when entering a new route. Automatically:
-
-- Exits previous route (if exists)
-- Resets collected data
-- Adds route to history
-- Updates timestamps
-
-**Example:**
-
-```typescript
-let session = createSession<FlightData>();
-
-// Enter booking route
-session = enterRoute(session, "book_flight", "Book a Flight");
-
-console.log(session.currentRoute?.title); // "Book a Flight"
-console.log(session.data); // {} (reset for new route)
-```
-
-#### `enterStep<TData>(session, stepId, description?): SessionState<TData>`
-
-Updates session when entering a new step within a route.
-
-**Example:**
-
-```typescript
-session = enterStep(session, "ask_destination", "Ask where to fly");
-
-console.log(session.currentStep?.id); // "ask_destination"
-console.log(session.currentStep?.description); // "Ask where to fly"
-```
-
-#### `mergeCollected<TData>(session, data): SessionState<TData>`
-
-Merges new collected data into session. Updates timestamps automatically.
-
-**Example:**
-
-```typescript
-session = mergeCollected(session, {
-  destination: "Paris",
-  departureDate: "2025-06-15",
-});
-
-console.log(session.data); // { destination: "Paris", departureDate: "2025-06-15" }
-```
-
-#### `sessionStepToData<TData>(session): object`
-
-Converts SessionState to persistence-friendly format for database storage.
-
-**Returns:**
-
-```typescript
-{
-  currentRoute?: string;          // Route ID
-  currentStep?: string;          // Step ID
-  collectedData: {                // All session data
-    data: Partial<TData>;
-    routeHistory: Array<...>;
-    currentRouteTitle?: string;
-    currentStepDescription?: string;
-    metadata?: object;
-  };
-}
-```
-
-**Example:**
-
-```typescript
-const session = createSession<FlightData>("session_123");
-// ... conversation happens ...
-
-// Save to database
-const dbData = sessionStepToData(session);
-await db.sessions.update(session.id!, {
-  currentRoute: dbData.currentRoute,
-  currentStep: dbData.currentStep,
-  collectedData: dbData.collectedData,
-});
-```
-
-#### `sessionDataToStep<TData>(sessionId, data): SessionState<TData>`
-
-Converts database data back to SessionState for resuming conversations.
-
-**Parameters:**
-
-- `sessionId`: The database session ID
-- `data`: Database session data (currentRoute, currentStep, collectedData)
-
-**Example:**
-
-```typescript
-// Load from database
-const dbSession = await db.sessions.findById("session_123");
-
-// Restore session step
-const session = sessionDataToStep<FlightData>(dbSession.id, {
-  currentRoute: dbSession.currentRoute,
-  currentStep: dbSession.currentStep,
-  collectedData: dbSession.collectedData,
-});
-
-// Resume conversation
-const response = await agent.respond({ history, session });
-```
-
-**Complete Persistence Example:**
-
-```typescript
-// CREATE: New session
-let session = createSession<FlightData>(dbSession.id);
-
-// CONVERSATION: Extract data
-const response1 = await agent.respond({ history: history1, session });
-session = response1.session!; // { data: { destination: "Paris" } }
-
-// SAVE: To database
-const saveData = sessionStepToData(session);
-await db.sessions.update(session.id!, saveData);
-
-// ---  Later (new request) ---
-
-// LOAD: From database
-const loaded = await db.sessions.findById("session_123");
-const restored = sessionDataToStep<FlightData>(loaded.id, loaded);
-
-// CONTINUE: Conversation
-const response2 = await agent.respond({ history: history2, session: restored });
-```
-
----
-
-### `AgentStructuredResponse`
-
-The structured response format returned by AI providers when JSON mode is enabled.
-
-```typescript
-interface AgentStructuredResponse {
-  /** The actual message to send to the user */
-  message: string;
-  /** Route chosen by the agent (route title or null if no route) */
-  route?: string | null;
-  /** Current step within the route (step description or null) */
-  step?: string | null;
-  /** Tool calls the agent wants to execute */
-  toolCalls?: Array<{
-    toolName: string;
-    arguments: Record<string, unknown>;
-  }>;
-  /** Additional reasoning or internal thoughts (optional) */
-  reasoning?: string;
-}
-```
-
-This type represents the structured JSON output that AI providers return when using the enhanced response format. The `Agent.respond()` method automatically parses this and returns a more convenient format.
-
----
-
-### ID Generation Utilities
-
-Generate deterministic IDs for consistency across server restarts.
-
-#### `generateRouteId(title: string): string`
-
-Generates a deterministic route ID from a title.
-
-```typescript
-import { generateRouteId } from "@falai/agent";
-
-const routeId = generateRouteId("User Onboarding");
-// Returns: "route_user_onboarding_{hash}"
-```
-
-#### `generateStepId(routeId: string, description?: string, index?: number): string`
-
-Generates a deterministic step ID.
-
-```typescript
-import { generateStepId } from "@falai/agent";
-
-const stepId = generateStepId("route_123", "Ask for name");
-// Returns: "step_ask_for_name_{hash}"
-```
-
-#### `generateToolId(name: string): string`
-
-Generates a deterministic tool ID from a name.
-
-```typescript
-import { generateToolId } from "@falai/agent";
-
-const toolId = generateToolId("get_user_data");
-// Returns: "tool_get_user_data_{hash}"
-```
-
-**Why Deterministic IDs?**
-
-All IDs are generated deterministically using a hash function of their content (title, name, description). This ensures:
-
-- **Consistency** - Same input always produces the same ID
-- **Server Restart Safe** - IDs remain stable across application restarts
-- **Persistence Friendly** - Safe to store in databases and reference later
-- **Custom Control** - You can always provide your own IDs when needed
-
----
-
-## Constants
-
-### `END_ROUTE`
-
-Symbol marking the end of a conversation route. Use this when building routes to mark where they should end.
-
-```typescript
-import { END_ROUTE } from "@falai/agent";
-
-const thankYou = askEmail.nextStep({
-  prompt: "Thank you for your information!",
-});
-
-// Mark the end of the route
-thankYou.nextStep({ step: END_ROUTE });
-```
-
-### `END_ROUTE_ID`
-
-String constant representing END_ROUTE for runtime comparisons. When a route completes, `currentStep.id` is set to this value.
-
-```typescript
-import { END_ROUTE_ID } from "@falai/agent";
-
-const response = await agent.respond({ history, session });
-
-// Method 1: Using isRouteComplete (recommended)
-if (response.isRouteComplete) {
-  console.log("Route completed!");
-}
-
-// Method 2: Using END_ROUTE_ID constant
-if (response.session?.currentStep?.id === END_ROUTE_ID) {
-  console.log("Route completed!");
-}
-```
-
-**Note:** Both methods are equivalent. Use `isRouteComplete` for simplicity, or `END_ROUTE_ID` for consistency with how you build routes.
-
----
-
-## Enums
-
-### `CompositionMode`
-
-```typescript
-enum CompositionMode {
-  FLUID = "fluid",
-  CANNED_FLUID = "canned_fluid",
-  CANNED_COMPOSITED = "composited_canned",
-  CANNED_STRICT = "strict_canned",
-}
-```
-
----
-
-### `BuiltInSection`
-
-Prompt builder section identifiers.
-
-```typescript
-enum BuiltInSection {
-  IDENTITY = "identity",
-  GLOSSARY = "glossary",
-  CONTEXT = "context",
-  GUIDELINES = "guidelines",
-  TOOLS
-  ACTIVE_ROUTES = "active_routes",
-}
-```
-
----
-
-## Advanced Topics
-
-### Custom AI Providers
-
-Implement the `AiProvider` interface:
-
-```typescript
-interface AiProvider {
-  generateMessage<TContext = unknown>(
-    input: GenerateMessageInput<TContext>
-  ): Promise<GenerateMessageOutput>;
-}
-```
-
----
-
-## Template Utilities
-
-### Dynamic Content with Templates
-
-The framework supports dynamic content generation through a versatile `Template` system. A `Template` can be either a simple string with `{{variable}}` placeholders or a function that returns a string, allowing for more complex, context-aware logic.
-
-Templates are evaluated at runtime with a `TemplateContext` object that provides access to the agent's state:
-
-```typescript
-interface TemplateContext<TContext = unknown, TData = unknown> {
-  context?: TContext;
-  session?: SessionState<TData>;
-  history?: Event[];
-  data?: Partial<TData>; // Convenience alias for session.data
-}
-```
-
-#### `Template<TContext, TData>` Type
-
-This is the core type for all dynamic content:
-
-```typescript
-type Template<TContext = unknown, TData = unknown> =
-  | string
-  | ((params: TemplateContext<TContext, TData>) => string | Promise<string>);
-```
-
-**String Templates:**
-
-Simple strings with `{{variable}}` placeholders are rendered using values from the `context` object.
-
-```typescript
-const agent = new Agent({
-  identity: "I am {{name}}",
-  context: { name: "HelperBot" },
-});
-```
-
-**Function Templates:**
-
-For more complex logic, you can provide a function that receives the `TemplateContext` and returns a string (or a `Promise<string>` for async operations).
-
-```typescript
-const agent = new Agent({
-  identity: ({ context }) => `I am here to help, ${context.user.name}`,
-  context: { user: { name: "Alice" } },
-});
-```
-
-#### `render(template, params)`
-
-An internal async utility that resolves a `Template` to a string. You won't typically call this directly, but it powers the dynamic content generation throughout the framework.
-
-**Supported in (Dynamic/Personalized):**
-
-- **Agent**: `identity`
-- **Terms**: `name`, `description`, `synonyms`
-- **Guidelines**: `condition`, `action`
-- **Routes**: `conditions`, `rules`, `prohibitions`
-- **Steps/Transitions**: `prompt`, `condition`
-
-**Not supported in (Static/Predictable):**
-
-- Agent `name`, `goal`, `description`
-- Route `title`, `description`
-- Step `description`
-
-**Example:**
-
-```typescript
-const agent = new Agent({
-  name: "Assistant", // Static
-  identity: ({ context }) =>
-    `I am here to help you, ${context.user.firstName}.`, // Dynamic
-  context: {
-    user: { firstName: "Alice", age: 30 },
-  },
-});
-
-agent.createGuideline({
-  condition: ({ context }) => context.user.age > 18, // Dynamic condition
-  action:
-    "Be helpful to {{user.firstName}} and consider their age in responses", // Dynamic action
-});
-```
-
----
-
-**Made with ❤️ for the community**