@falai/agent 0.9.0-alpha-1 → 0.9.0

package/docs/core/conversation-flows/data-collection.md

@@ -1,20 +1,22 @@
-# Schema-Driven Data Collection
+# Agent-Level Schema-Driven Data Collection
 
-@falai/agent implements a powerful schema-first approach to data collection, enabling type-safe, structured information extraction from natural conversations. Unlike traditional form-filling, this system uses AI to naturally gather information while maintaining data integrity.
+@falai/agent implements a powerful agent-level schema-first approach to data collection, enabling type-safe, structured information extraction from natural conversations across all routes. Unlike traditional route-specific data collection, this system centralizes data schemas at the agent level while allowing routes to specify completion requirements.
 
 ## Overview
 
-The data collection system provides:
+The agent-level data collection system provides:
 
-- **JSON Schema Contracts**: Define data structures upfront with validation
+- **Centralized JSON Schema**: Define comprehensive data structures at the agent level
+- **Cross-Route Data Sharing**: Data collected by any route is available to all routes
+- **Route Completion Logic**: Routes complete when their required fields are satisfied
 - **Type-Safe Extraction**: Automatic mapping from AI responses to typed data
 - **Natural Conversations**: AI handles information gathering conversationally
-- **Validation & Enrichment**: Lifecycle hooks for data processing
-- **Session Persistence**: Data survives across conversation turns
+- **Validation & Enrichment**: Agent-level lifecycle hooks for data processing
+- **Session Persistence**: Data survives across conversation turns and route transitions
 
-## Schema Definition
+## Agent-Level Schema Definition
 
-### Basic Schema
+### Centralized Schema
 
 ```typescript
 interface UserProfile {
@@ -26,10 +28,19 @@ interface UserProfile {
     notifications: boolean;
     theme: "light" | "dark";
   };
+  // Additional fields for other routes
+  supportTicketId?: string;
+  issueType?: string;
+  feedbackRating?: number;
+  subscriptionTier?: "free" | "premium" | "enterprise";
 }
 
-const userProfileRoute = agent.createRoute<UserProfile>({
-  title: "User Profile Collection",
+// Define schema at agent level
+const agent = new Agent<{}, UserProfile>({
+  name: "User Management Agent",
+  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  
+  // Comprehensive agent-level schema
   schema: {
     type: "object",
     properties: {
@@ -63,9 +74,32 @@ const userProfileRoute = agent.createRoute<UserProfile>({
           },
         },
       },
+      supportTicketId: { type: "string" },
+      issueType: { type: "string" },
+      feedbackRating: { type: "number", minimum: 1, maximum: 5 },
+      subscriptionTier: { type: "string", enum: ["free", "premium", "enterprise"] }
     },
     required: ["name", "email"],
-  },
+  }
+});
+
+// Routes specify required fields instead of schemas
+const profileRoute = agent.createRoute({
+  title: "User Profile Collection",
+  requiredFields: ["name", "email", "age"],
+  optionalFields: ["interests", "preferences"]
+});
+
+const supportRoute = agent.createRoute({
+  title: "Support Ticket",
+  requiredFields: ["name", "email", "issueType"],
+  optionalFields: ["supportTicketId"]
+});
+
+const feedbackRoute = agent.createRoute({
+  title: "Feedback Collection",
+  requiredFields: ["name", "email", "feedbackRating"],
+  optionalFields: ["subscriptionTier"]
 });
 ```
 
@@ -128,24 +162,33 @@ const complexSchema = {
 
 ## Step-Level Data Collection
 
-### Basic Collection
+### Basic Collection with Agent-Level Data
 
 ```typescript
 const profileRoute = agent
   .createRoute({
     title: "Profile Collection",
-    schema: userProfileSchema,
+    requiredFields: ["name", "email", "age"], // Required for route completion
+    optionalFields: ["interests"], // Optional but helpful
     initialStep: {
       prompt:
         "Hi! I'm collecting some information to personalize your experience. What's your name?",
-      collect: ["name"], // Maps to schema field
+      collect: ["name"], // Maps to agent schema field
     },
   })
   .nextStep({
     prompt: "Thanks {{name}}! What's your email address?",
     collect: ["email"],
     requires: ["name"], // Must have name before collecting email
+  })
+  .nextStep({
+    prompt: "What's your age?",
+    collect: ["age"],
+    requires: ["name", "email"],
   });
+
+// Route completes when all required fields are collected
+// Data is available to all other routes
 ```
 
 ### Multi-Field Collection
@@ -160,12 +203,12 @@ const comprehensiveStep = {
     - Your preferred theme (light/dark)
   `,
   collect: [
-    "age", // Single field
-    "interests", // Array field
+    "age", // Single field from agent schema
+    "interests", // Array field from agent schema
     "preferences.notifications", // Nested field (dot notation)
     "preferences.theme", // Another nested field
   ],
-  requires: ["name", "email"],
+  requires: ["name", "email"], // Prerequisites from agent data
 };
 ```
 
@@ -175,34 +218,69 @@ const comprehensiveStep = {
 const conditionalCollection = {
   prompt: "Would you like to set up notifications? (yes/no)",
   collect: ["preferences.notifications"],
-  skipIf: (data) => data.preferences?.notifications !== undefined,
-  requires: ["name", "email"],
+  skipIf: (data) => data.preferences?.notifications !== undefined, // Skip if already collected
+  requires: ["name", "email"], // Prerequisites from agent data
 };
 ```
 
+### Cross-Route Data Sharing
+
+With agent-level data collection, routes can share data seamlessly:
+
+```typescript
+// User starts with profile collection
+const response1 = await agent.respond("Hi, I'm John Doe, email john@example.com");
+// Agent data: { name: "John Doe", email: "john@example.com" }
+
+// User switches to support - data is already available
+const response2 = await agent.respond("Actually, I need help with a technical issue");
+// Support route can access name and email, only needs to collect issue details
+// Support route: 2/3 required fields already satisfied
+
+// User provides issue details
+const response3 = await agent.respond("My account won't sync properly");
+// Support route completes: { name: "John Doe", email: "john@example.com", issueType: "technical" }
+
+// Later, user wants to give feedback
+const response4 = await agent.respond("I want to rate my support experience - 5 stars");
+// Feedback route completes immediately: already has name, email, and now rating
+```
+
 ## Data Validation & Processing
 
-### Lifecycle Hooks
+### Agent-Level Lifecycle Hooks
 
 ```typescript
-const validatedRoute = agent.createRoute({
-  title: "Validated Collection",
+const agent = new Agent<{}, UserProfile>({
+  name: "User Management Agent",
+  schema: { /* agent schema */ },
 
-  // Agent-level data validation
+  // Agent-level data validation (applies to all routes)
   hooks: {
     onDataUpdate: (newData, previousData) => {
-      // Cross-field validation
+      // Cross-field validation using complete agent data
       if (newData.email && newData.confirmEmail) {
         if (newData.email !== newData.confirmEmail) {
           throw new Error("Email addresses don't match");
         }
       }
 
-      // Data enrichment
+      // Data enrichment based on agent-level data
       if (newData.name && !newData.displayName) {
         newData.displayName = newData.name.split(" ")[0]; // First name only
       }
 
+      // Auto-set subscription tier based on email domain
+      if (newData.email && !newData.subscriptionTier) {
+        newData.subscriptionTier = newData.email.includes('@enterprise.com') ? 'enterprise' : 'free';
+      }
+
+      // Validate against agent schema
+      const validation = agent.validateData(newData);
+      if (!validation.valid) {
+        throw new Error(`Data validation failed: ${validation.errors.map(e => e.message).join(', ')}`);
+      }
+
       return newData;
     },
   },

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,