@falai/agent 0.9.0-alpha-1 → 0.9.0-alpha-2

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

@@ -31,31 +31,44 @@ const greetingRoute = agent
   });
 ```
 
-### Route with Schema
+### Route with Agent-Level Schema
 
 ```typescript
 interface UserInfo {
   name: string;
   email: string;
   interests: string[];
+  preferences?: object;
+  profileComplete?: boolean;
 }
 
+// Agent defines comprehensive schema
+const agent = new Agent<{}, UserInfo>({
+  name: "Profile Assistant",
+  provider: openaiProvider,
+  schema: {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      email: { type: "string", format: "email" },
+      interests: {
+        type: "array",
+        items: { type: "string" },
+      },
+      preferences: { type: "object" },
+      profileComplete: { type: "boolean" }
+    },
+    required: ["name", "email"],
+  }
+});
+
+// Route specifies required fields instead of schema
 const userProfileRoute = agent
-  .createRoute<UserInfo>({
+  .createRoute({
     title: "User Profile Collection",
     description: "Collect basic user information",
-    schema: {
-      type: "object",
-      properties: {
-        name: { type: "string" },
-        email: { type: "string", format: "email" },
-        interests: {
-          type: "array",
-          items: { type: "string" },
-        },
-      },
-      required: ["name", "email"],
-    },
+    requiredFields: ["name", "email", "interests"], // Required for completion
+    optionalFields: ["preferences"], // Nice to have
     initialStep: {
       prompt: "Let's create your profile. What's your name?",
       collect: ["name"],
@@ -64,12 +77,12 @@ const userProfileRoute = agent
   .nextStep({
     prompt: "Great, {{name}}! What's your email address?",
     collect: ["email"],
-    requires: ["name"],
+    requires: ["name"], // Prerequisites from agent data
   })
   .nextStep({
     prompt: "What are your interests? (comma-separated)",
     collect: ["interests"],
-    requires: ["name", "email"],
+    requires: ["name", "email"], // Prerequisites from agent data
   });
 ```
 
@@ -99,9 +112,9 @@ interface StepOptions<TContext, TData> {
 ```typescript
 const dataCollectionStep = {
   prompt: "What's your preferred contact method?",
-  collect: ["contactMethod"], // Maps to schema field
-  requires: ["name", "email"], // Must have these fields first
-  skipIf: (data) => data.contactMethod !== undefined, // Skip if already collected
+  collect: ["contactMethod"], // Maps to agent schema field
+  requires: ["name", "email"], // Must have these fields from agent data
+  skipIf: (data) => data.contactMethod !== undefined, // Skip if already collected by any route
 };
 ```
 
@@ -296,6 +309,10 @@ const advancedRoute = agent.createRoute({
   title: "Advanced Interaction",
   description: "Complex multi-step conversation",
 
+  // Route completion requirements
+  requiredFields: ["customerName", "email", "issueType"],
+  optionalFields: ["phone", "priority"],
+
   // Route-level identity overrides agent identity
   identity: "You are an expert consultant specializing in {{domain}}",
 
@@ -316,19 +333,25 @@ const advancedRoute = agent.createRoute({
     },
   ],
 
-  // Initial data to pre-populate
+  // Initial data to pre-populate (maps to agent schema)
   initialData: {
     sessionId: generateId(),
     startTime: new Date().toISOString(),
   },
 
-  // Lifecycle hooks
+  // Route-level lifecycle hooks (work with agent data)
   hooks: {
     onDataUpdate: (newData, previousData) => {
-      // Validate or enrich collected data
+      // Validate or enrich agent-level collected data
       if (newData.email && !isValidEmail(newData.email)) {
         throw new Error("Invalid email format");
       }
+      
+      // Auto-set priority based on issue type
+      if (newData.issueType === 'billing' && !newData.priority) {
+        newData.priority = 'high';
+      }
+      
       return newData;
     },
     onContextUpdate: (newContext, previousContext) => {

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

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

package/docs/core/conversation-flows/step-transitions.md

@@ -26,14 +26,14 @@ const smartRoute = agent
     initialStep: {
       prompt: "What's your name?",
       collect: ["name"],
-      skipIf: (data) => data.name !== undefined, // Skip if name already known
+      skipIf: (data) => data.name !== undefined, // Skip if name already collected by any route
     },
   })
   .nextStep({
     prompt: "What's your email, {{name}}?",
     collect: ["email"],
-    requires: ["name"], // Must have name to proceed
-    skipIf: (data) => data.email !== undefined, // Skip if email already known
+    requires: ["name"], // Must have name from agent data to proceed
+    skipIf: (data) => data.email !== undefined, // Skip if email already collected by any route
   });
 ```
 

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

@@ -1,24 +1,25 @@
 # Steps
 
-Steps are the building blocks of conversational routes in @falai/agent. This document covers step configuration, data collection, and transition logic.
+Steps are the building blocks of conversational routes in @falai/agent with agent-level data collection. This document covers step configuration, data collection into the agent schema, and transition logic based on agent data.
 
 ## Overview
 
 Steps represent individual moments in a conversation where the agent can:
 
 - Prompt the user for information
-- Collect structured data from responses
-- Execute tools or perform actions
-- Make decisions about conversation flow
+- Collect structured data into the agent-level schema
+- Execute tools that work with complete agent data
+- Make decisions about conversation flow based on agent data
+- Skip execution if required data is already available from other routes
 
 ## Step Configuration
 
 ```typescript
 const nameStep = bookingRoute.initialStep.nextStep({
   prompt: "What's your name?",
-  collect: ["firstName", "lastName"],
+  collect: ["customerName"], // Collects into agent-level schema
   requires: [], // No prerequisites
-  skipIf: (data) => data.firstName && data.lastName, // Skip if already collected
+  skipIf: (data) => data.customerName, // Skip if already collected by any route
 });
 ```
 
@@ -42,34 +43,57 @@ Steps that end the route using `END_ROUTE`.
 
 ## Data Collection
 
-Steps collect data through the `collect` array, which maps to the route's JSON schema.
+Steps collect data through the `collect` array, which maps to the agent's JSON schema and is validated against it.
 
 ```typescript
 const contactStep = nameStep.nextStep({
   prompt: "What's your email and phone number?",
-  collect: ["email", "phone"],
-  requires: ["firstName"], // Must have name first
+  collect: ["email", "phone"], // Maps to agent schema fields
+  requires: ["customerName"], // Must have name first (from agent data)
 });
 ```
 
 ## Conditional Logic
 
-Steps support various conditional behaviors:
+Steps support various conditional behaviors based on agent-level data:
 
-- `skipIf`: Skip the step if a condition is met
-- `requires`: Prerequisites that must be satisfied
+- `skipIf`: Skip the step if a condition is met (evaluates against complete agent data)
+- `requires`: Prerequisites that must be satisfied (checks agent data from any route)
 - `when`: AI-evaluated conditions for branching
 
 ## Tool Integration
 
-Steps can execute tools before generating AI responses:
+Steps can execute tools that work with complete agent-level data:
 
 ```typescript
 const weatherStep = planningStep.nextStep({
   prompt: "I'll check the weather for your destination",
-  tool: weatherLookupTool,
-  requires: ["destination", "travelDate"],
+  tool: weatherLookupTool, // Tool receives complete agent data
+  requires: ["destination", "checkIn"], // Prerequisites from agent data
 });
+
+// Tool implementation with agent data access
+const weatherLookupTool: Tool<Context, [], WeatherData, HotelData> = {
+  id: "weather_lookup",
+  description: "Look up weather for destination",
+  parameters: { type: "object", properties: {} },
+  handler: async (toolContext) => {
+    const { data } = toolContext; // Complete agent data
+    
+    if (!data.destination || !data.checkIn) {
+      return { data: undefined };
+    }
+    
+    const weather = await getWeather(data.destination, data.checkIn);
+    
+    return {
+      data: weather,
+      dataUpdate: {
+        weatherInfo: weather.summary // Update agent data
+      }
+    };
+  }
+};
 ```
 
 ## Step Transitions

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

@@ -58,8 +58,9 @@ The system intelligently traverses step chains:
 All routing decisions consider:
 
 - **Conversation History**: Full dialogue context
-- **Collected Data**: What information has been gathered
-- **Session State**: Current route and step position
+- **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
@@ -107,20 +108,27 @@ The `getCandidateSteps()` method implements sophisticated logic:
 const candidates = routingEngine.getCandidateSteps(
   route, // Current route
   currentStep, // Current step (or null for route start)
-  collectedData // Session data collected so far
+  agentData // Agent-level data collected across all routes
 );
 ```
 
 ### SkipIf Processing
 
-Steps are automatically filtered based on conditions:
+Steps are automatically filtered based on agent-level data conditions:
 
 ```typescript
-// Step definition with skipIf
+// 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
+  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
 }
 ```
 
@@ -155,8 +163,9 @@ const routingPrompt = await routingEngine.buildRoutingPrompt({
 Prompts include:
 
 - Agent identity and personality
-- Available routes with descriptions and conditions
-- Session context and collected data
+- 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
 
@@ -169,7 +178,7 @@ const stepPrompt = await routingEngine.buildStepSelectionPrompt({
   route,
   currentStep,
   candidates,
-  data: session.data,
+  data: agent.getCollectedData(), // Agent-level data
   history,
   lastMessage,
   agentOptions,

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

@@ -18,7 +18,7 @@ Tools are created as objects implementing the `Tool` interface:
 ```typescript
 import { Tool } from "@falai/agent";
 
-const weatherTool: Tool<unknown, [], string, WeatherData> = {
+const weatherTool: Tool<unknown, WeatherData, [], string> = {
   id: "get_weather",
   name: "Weather Forecast", // Human-readable name shown to AI models
   description: "Get current weather and forecast for a location",
@@ -48,7 +48,7 @@ const weatherTool: Tool<unknown, [], string, WeatherData> = {
 The optional `name` field provides a human-readable name for the tool that is displayed to AI models. When provided, this name takes precedence over the `id` field in AI provider interactions:
 
 ```typescript
-const calculatorTool: Tool<unknown, [], string, CalcData> = {
+const calculatorTool: Tool<unknown, CalcData, [], string> = {
   id: "math_calculator", // Internal identifier
   name: "Math Calculator", // Display name for AI models
   description: "Perform mathematical calculations",
@@ -68,7 +68,7 @@ const calculatorTool: Tool<unknown, [], string, CalcData> = {
 Tool parameters are defined using JSON Schema:
 
 ```typescript
-const searchTool: Tool<unknown, [], string, SearchData> = {
+const searchTool: Tool<unknown, SearchData, [], string> = {
   id: "web_search",
   name: "Web Search Engine",
   description: "Search the web for information",
@@ -110,7 +110,7 @@ Tools receive execution context including:
 - **Route information** - Current route and step details
 
 ```typescript
-const userProfileTool: Tool<unknown, [], string, UserData> = {
+const userProfileTool: Tool<unknown, UserData, [], string> = {
   id: "get_user_profile",
   description: "Retrieve user profile information",
   parameters: {
@@ -159,7 +159,7 @@ interface ToolResult {
 Tools can modify conversation context:
 
 ```typescript
-const locationTool: Tool<unknown, [], string, LocationData> = {
+const locationTool: Tool<unknown, LocationData, [], string> = {
   id: "set_location",
   description: "Update the user's location in context",
   parameters: {
@@ -187,7 +187,7 @@ const locationTool: Tool<unknown, [], string, LocationData> = {
 Tools can update session data collected during conversation:
 
 ```typescript
-const validationTool: Tool<unknown, [], string, BookingData> = {
+const validationTool: Tool<unknown, BookingData, [], string> = {
   id: "validate_booking",
   description: "Validate booking information and update session data",
   parameters: {
@@ -223,7 +223,7 @@ const validationTool: Tool<unknown, [], string, BookingData> = {
 Tools should handle errors gracefully:
 
 ```typescript
-const apiTool: Tool<unknown, [], string, ApiData> = {
+const apiTool: Tool<unknown, ApiData, [], string> = {
   id: "call_external_api",
   description: "Call an external API endpoint",
   parameters: {
@@ -303,7 +303,7 @@ When multiple tools with the same name exist, priority is:
 Tools support async operations and Promises:
 
 ```typescript
-const asyncTool: Tool<unknown, [], string, ProcessingData> = {
+const asyncTool: Tool<unknown, ProcessingData, [], string> = {
   id: "process_data",
   description: "Process data asynchronously with heavy computation",
   parameters: {