@falai/agent 0.9.0-alpha-1 → 0.9.0

package/docs/core/agent/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The `Agent<TContext>` class is the central orchestrator of @falai/agent, providing a strongly-typed, context-aware AI agent framework with intelligent routing and schema-driven data collection.
+The `Agent<TContext, TData>` class is the central orchestrator of @falai/agent, providing a strongly-typed, context-aware AI agent framework with intelligent routing and agent-level schema-driven data collection.
 
 ## Core Responsibilities
 
@@ -11,7 +11,7 @@ The `Agent<TContext>` class is the central orchestrator of @falai/agent, providi
 - **Context Lifecycle**: Dynamic context management with provider functions and lifecycle hooks
 - **Session Management**: Conversation state persistence and multi-turn dialogue support
 - **Tool Orchestration**: Hierarchical tool execution (agent → route → step level)
-- **Data Collection**: Schema-driven information extraction from natural conversations
+- **Agent-Level Data Collection**: Centralized schema-driven information extraction shared across all routes
 
 ## Agent Configuration
 
@@ -43,7 +43,18 @@ interface CustomerContext {
   };
 }
 
-const agent = new Agent<CustomerContext>({
+interface CustomerData {
+  customerName?: string;
+  email?: string;
+  phone?: string;
+  issueType?: 'booking' | 'billing' | 'technical' | 'other';
+  issueDescription?: string;
+  priority?: 'low' | 'medium' | 'high';
+  rating?: number;
+  comments?: string;
+}
+
+const agent = new Agent<CustomerContext, CustomerData>({
   // Identity
   name: "Premium Support Assistant",
   description: "24/7 AI support for premium customers",
@@ -56,6 +67,21 @@ const agent = new Agent<CustomerContext>({
     backupModels: ["gpt-4"],
   }),
 
+  // Agent-level data schema (NEW)
+  schema: {
+    type: "object",
+    properties: {
+      customerName: { type: "string" },
+      email: { type: "string", format: "email" },
+      phone: { type: "string" },
+      issueType: { type: "string", enum: ["booking", "billing", "technical", "other"] },
+      issueDescription: { type: "string" },
+      priority: { type: "string", enum: ["low", "medium", "high"] },
+      rating: { type: "number", minimum: 1, maximum: 5 },
+      comments: { type: "string" }
+    }
+  },
+
   // Static context (can be overridden by contextProvider)
   context: {
     userId: "anonymous",
@@ -102,16 +128,21 @@ const agent = new Agent<CustomerContext>({
       }
     },
 
-    // Validate and enrich collected data
+    // Validate and enrich collected data (NEW: Agent-level data hooks)
     onDataUpdate: async (data, previousData) => {
-      // Data validation
+      // Data validation against agent schema
       if (data.email && !isValidEmail(data.email)) {
         throw new Error("Invalid email format");
       }
 
-      // Data enrichment
-      if (data.userId && !data.userProfile) {
-        data.userProfile = await db.getUserProfile(data.userId);
+      // Data enrichment using agent-level data
+      if (data.customerName && !data.customerId) {
+        data.customerId = await lookupCustomerId(data.customerName);
+      }
+
+      // Auto-set priority based on issue type
+      if (data.issueType === 'billing' && !data.priority) {
+        data.priority = 'high';
       }
 
       return data;
@@ -327,26 +358,33 @@ agent.session.clearHistory();
 ### Declarative Route Creation
 
 ```typescript
-const agent = new Agent({
+const agent = new Agent<CustomerContext, CustomerData>({
+  // Agent-level schema defines all possible data fields
+  schema: { /* comprehensive schema */ },
+  
   routes: [
     {
       title: "Technical Support",
       description: "Help with technical issues",
       conditions: ["user reports technical problem"],
+      // NEW: Routes specify required fields instead of schemas
+      requiredFields: ["customerName", "email", "issueType", "issueDescription"],
+      optionalFields: ["phone", "priority"],
       initialStep: {
         prompt:
           "I understand you're having a technical issue. Can you describe what's happening?",
-        collect: ["problem", "severity"],
+        collect: ["issueType", "issueDescription"], // Collects into agent-level data
       },
     },
     {
-      title: "Billing Inquiry",
+      title: "Billing Inquiry", 
       description: "Handle billing and payment questions",
       conditions: ["user asks about billing or payment"],
+      requiredFields: ["customerName", "email", "issueType"],
       initialStep: {
         prompt:
           "I'd be happy to help with your billing question. What can I assist with?",
-        collect: ["billingIssue"],
+        collect: ["issueType"], // Maps to agent schema field
       },
     },
   ],
@@ -356,18 +394,21 @@ const agent = new Agent({
 ### Programmatic Route Creation
 
 ```typescript
-// Create routes dynamically
+// Create routes dynamically with required fields
 const supportRoute = agent
   .createRoute({
     title: "Customer Support",
+    requiredFields: ["customerName", "email", "issueType"], // NEW: Required fields
+    optionalFields: ["phone"], // NEW: Optional fields
     initialStep: {
       prompt: "How can I help you today?",
-      collect: ["intent"],
+      collect: ["customerName", "email"], // Collects into agent-level data
     },
   })
   .nextStep({
-    prompt: "I understand you need help with {{intent}}",
-    requires: ["intent"],
+    prompt: "I understand you need help, {{customerName}}. What type of issue are you experiencing?",
+    collect: ["issueType"],
+    requires: ["customerName", "email"], // Prerequisites from agent data
   });
 
 // Access created routes
@@ -404,6 +445,110 @@ const route = agent.createRoute({
 2. **Route-level tools**
 3. **Agent-level tools** (lowest priority)
 
+## Agent-Level Data Collection
+
+### Centralized Data Schema
+
+The new architecture centralizes data collection at the agent level, allowing all routes to work with the same data structure:
+
+```typescript
+interface ComprehensiveData {
+  // Customer identification
+  customerId?: string;
+  customerName?: string;
+  email?: string;
+  phone?: string;
+  
+  // Issue tracking
+  issueType?: 'booking' | 'billing' | 'technical' | 'other';
+  issueDescription?: string;
+  priority?: 'low' | 'medium' | 'high';
+  
+  // Feedback
+  rating?: number;
+  comments?: string;
+  recommendToFriend?: boolean;
+}
+
+const agent = new Agent<Context, ComprehensiveData>({
+  name: "Customer Service Agent",
+  schema: {
+    type: "object",
+    properties: {
+      customerId: { type: "string" },
+      customerName: { type: "string" },
+      email: { type: "string", format: "email" },
+      phone: { type: "string" },
+      issueType: { type: "string", enum: ["booking", "billing", "technical", "other"] },
+      issueDescription: { type: "string" },
+      priority: { type: "string", enum: ["low", "medium", "high"] },
+      rating: { type: "number", minimum: 1, maximum: 5 },
+      comments: { type: "string" },
+      recommendToFriend: { type: "boolean" }
+    }
+  }
+});
+```
+
+### Route Completion Based on Required Fields
+
+Routes now specify which fields they need to complete, enabling cross-route data sharing:
+
+```typescript
+// Support route needs basic info + issue details
+const supportRoute = agent.createRoute({
+  title: "Customer Support",
+  requiredFields: ["customerName", "email", "issueType", "issueDescription"],
+  optionalFields: ["phone", "priority"]
+});
+
+// Feedback route needs basic info + rating
+const feedbackRoute = agent.createRoute({
+  title: "Feedback Collection",
+  requiredFields: ["customerName", "email", "rating"],
+  optionalFields: ["comments", "recommendToFriend"]
+});
+
+// Routes can complete when their required data is available,
+// regardless of which route collected it
+```
+
+### Cross-Route Data Sharing
+
+Data collected by any route is available to all other routes:
+
+```typescript
+// User starts with support, provides name and email
+const response1 = await agent.respond("I need help, my name is John Doe, email john@example.com");
+// Agent data now contains: { customerName: "John Doe", email: "john@example.com" }
+
+// User switches to feedback - already has 2/3 required fields
+const response2 = await agent.respond("Actually, I want to leave feedback. I'd rate you 5 stars.");
+// Feedback route completes immediately with: { customerName: "John Doe", email: "john@example.com", rating: 5 }
+```
+
+### Agent Data Management Methods
+
+Access and update agent-level data programmatically:
+
+```typescript
+// Get current collected data
+const currentData = agent.getCollectedData();
+console.log(currentData); // { customerName: "John", email: "john@example.com" }
+
+// Update data programmatically
+await agent.updateCollectedData({
+  customerId: "CUST-12345",
+  priority: "high"
+});
+
+// Validate data against schema
+const validation = agent.validateData({ email: "invalid-email" });
+if (!validation.valid) {
+  console.log(validation.errors); // Detailed validation errors
+}
+```
+
 ## Response Generation
 
 ### Simple Response API
@@ -412,7 +557,7 @@ const route = agent.createRoute({
 // Simple message-based API (recommended)
 const response = await agent.respond("How do I reset my password?");
 console.log(response.message);
-console.log(agent.session.getData()); // Any collected data
+console.log(agent.session.getData<CustomerData>()); // Agent-level collected data
 console.log(response.toolCalls); // Any tool calls made
 console.log(response.isRouteComplete); // Whether route finished
 

package/docs/core/agent/context-management.md

@@ -8,28 +8,45 @@ The `@falai/agent` framework provides **automatic session management** through t
 
 ## 🎯 Automatic Session Management
 
-The `SessionManager` automatically tracks three key aspects of a conversation:
+The `SessionManager` automatically tracks four key aspects of a conversation:
 
 1. **Current Route** - Which conversation flow the user is in
 2. **Current Step** - Where in the flow they currently are
-3. **Collected data** - Structured data collected so far
+3. **Agent-Level Data** - Centralized structured data collected across all routes
 4. **Conversation History** - Complete message history within the session
 
 ```typescript
-// Define your data extraction type
-interface FlightData {
+// Define your agent-level data extraction type
+interface TravelData {
   destination: string;
   departureDate: string;
   passengers: number;
   cabinClass: "economy" | "business" | "first";
+  hotelPreference?: string;
+  budgetRange?: string;
+  specialRequests?: string;
 }
 
-// Agent with automatic session management
-const agent = new Agent({
+// Agent with automatic session management and agent-level schema
+const agent = new Agent<{}, TravelData>({
   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
+  sessionId: "user-123", // Automatically loads or creates session
+  
+  // Agent-level schema for all data collection
+  schema: {
+    type: "object",
+    properties: {
+      destination: { type: "string" },
+      departureDate: { type: "string", format: "date" },
+      passengers: { type: "number", minimum: 1, maximum: 9 },
+      cabinClass: { type: "string", enum: ["economy", "business", "first"] },
+      hotelPreference: { type: "string" },
+      budgetRange: { type: "string" },
+      specialRequests: { type: "string" }
+    }
+  }
 });
 
 // Simple conversation - session managed automatically
@@ -37,7 +54,7 @@ const response = await agent.respond("I want to book a flight to Paris");
 
 // Access session information
 console.log(agent.session.id); // "user-123"
-console.log(agent.session.getData<FlightData>()); // { destination: "Paris", ... }
+console.log(agent.session.getData<TravelData>()); // { destination: "Paris", ... }
 console.log(agent.session.getHistory()); // Conversation history
 ```
 
@@ -64,12 +81,13 @@ const sessionManager = agent.session;
 await sessionManager.getOrCreate("user-123");
 await sessionManager.getOrCreate(); // Auto-generates ID
 
-// Data management
-const data = sessionManager.getData<FlightData>();
+// Agent-level data management
+const data = sessionManager.getData<TravelData>();
 await sessionManager.setData({
   destination: "Paris",
   departureDate: "2025-10-15",
   passengers: 2,
+  cabinClass: "economy"
 });
 
 // History management
@@ -128,19 +146,25 @@ const agent = new Agent({
       await saveUserData(newContext.userId, newContext);
     },
 
-    // NEW: Validate and enrich collected data
+    // Agent-level data validation and enrichment
     onDataUpdate: async (data, previousData) => {
       // Normalize passenger count
       if (data.passengers < 1) data.passengers = 1;
       if (data.passengers > 9) data.passengers = 9;
 
-      // Enrich with computed fields
-      if (data.destination) {
+      // Enrich with computed fields using agent-level data
+      if (data.destination && !data.destinationCode) {
         data.destinationCode = await lookupAirportCode(data.destination);
       }
 
-      // Auto-trigger actions
-      if (hasAllRequires(data)) {
+      // Auto-set budget range based on cabin class
+      if (data.cabinClass && !data.budgetRange) {
+        data.budgetRange = data.cabinClass === 'first' ? 'premium' : 
+                          data.cabinClass === 'business' ? 'high' : 'standard';
+      }
+
+      // Auto-trigger actions when we have complete booking data
+      if (data.destination && data.departureDate && data.passengers) {
         data.shouldSearchFlights = true;
       }
 

package/docs/core/agent/session-management.md

@@ -6,22 +6,28 @@ The `@falai/agent` framework provides **automatic session management** through t
 
 ## Core Design Principles
 
-### 1. 🎯 Schema-First Data Extraction
+### 1. 🎯 Agent-Level Schema-First Data Extraction
 
-Define what data to collect upfront using JSON Schema, then extract it reliably:
+Define what data to collect upfront using JSON Schema at the agent level, then extract it reliably across all routes:
 
 ```typescript
-// Define your data contract
-interface FlightData {
+// Define your agent-level data contract
+interface TravelData {
   destination: string;
   departureDate: string;
   passengers: number;
   cabinClass: "economy" | "business" | "first";
+  hotelPreference?: string;
+  budgetRange?: string;
+  specialRequests?: string;
 }
 
-const route = agent.createRoute<FlightData>({
-  title: "Book Flight",
-  description: "Help user book a flight",
+// Agent with centralized schema
+const agent = new Agent<{}, TravelData>({
+  name: "Travel Agent",
+  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  
+  // Agent-level schema defines all possible data fields
   schema: {
     type: "object",
     properties: {
@@ -33,40 +39,67 @@ const route = agent.createRoute<FlightData>({
         enum: ["economy", "business", "first"],
         default: "economy",
       },
+      hotelPreference: { type: "string" },
+      budgetRange: { type: "string" },
+      specialRequests: { type: "string" }
     },
     required: ["destination", "departureDate", "passengers"],
-  },
+  }
+});
+
+// Routes specify required fields instead of schemas
+const flightRoute = agent.createRoute({
+  title: "Book Flight",
+  description: "Help user book a flight",
+  requiredFields: ["destination", "departureDate", "passengers", "cabinClass"],
+  optionalFields: ["specialRequests"]
+});
+
+const hotelRoute = agent.createRoute({
+  title: "Book Hotel", 
+  description: "Help user book accommodation",
+  requiredFields: ["destination", "departureDate", "hotelPreference"],
+  optionalFields: ["budgetRange", "specialRequests"]
 });
 ```
 
-**Why?** Schema-first extraction provides:
+**Why?** Agent-level schema-first extraction provides:
 
-- **Type Safety** - Full TypeScript types from definition to extraction
+- **Type Safety** - Full TypeScript types from definition to extraction across all routes
 - **Reliability** - Provider-enforced schemas, not prompt-based parsing
-- **Predictability** - Same data structure every time
+- **Predictability** - Same data structure every time, shared across routes
 - **Efficiency** - Extract multiple fields in one LLM call
+- **Cross-Route Data Sharing** - Data collected by any route is available to all routes
+- **Route Completion** - Routes complete when their required fields are satisfied
 
 ### 2. 🤖 Automatic Session Management
 
 Sessions are automatically managed through the `SessionManager` class integrated into every `Agent`:
 
 ```typescript
-// Server-side: Agent with automatic session management
-const agent = new Agent({
+// Server-side: Agent with automatic session management and agent-level data
+const agent = new Agent<{}, TravelData>({
   name: "Travel Agent",
   provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
   persistence: { adapter: new PrismaAdapter({ prisma }) },
-  sessionId: "user-123" // Automatically loads or creates this session
+  sessionId: "user-123", // Automatically loads or creates this session
+  
+  // Agent-level schema
+  schema: { /* comprehensive travel data schema */ }
 });
 
 // Simple conversation - no manual session management
 const response1 = await agent.respond("I want to book a flight to Paris");
 console.log(agent.session.id); // Session ID
-console.log(agent.session.getData()); // Collected data
+console.log(agent.session.getData<TravelData>()); // Agent-level collected data
 
 // Continue conversation - session automatically maintained
 const response2 = await agent.respond("Make that Tokyo instead");
-// Session automatically updated with new data
+// Session automatically updated with new data in agent-level structure
+
+// Switch to hotel booking - data is shared
+const response3 = await agent.respond("Also book me a hotel in Tokyo");
+// Hotel route can access destination data collected by flight route
 ```
 
 **SessionManager API:**

package/docs/core/ai-integration/prompt-composition.md

@@ -103,35 +103,59 @@ Assistant: Great! Let me check flights for next week. Could you tell me which ai
 Current session information including:
 
 - Active route and step
-- Collected data (with privacy filtering)
+- Agent-level collected data (with privacy filtering)
 - Route progress and completion status
+- Cross-route data availability
+
+```
+Current Session:
+- Route: Flight Booking (2/3 required fields collected)
+- Step: ask_passengers
+- Agent Data: { destination: "Paris", departureDate: "2025-01-15" }
+- Missing Required: passengers
+- Available from other routes: { hotelPreference: "luxury" }
+```
 
 ## Dynamic Schema Generation
 
-For data collection steps, the prompt includes JSON schemas:
+For data collection steps, the prompt includes agent-level JSON schemas:
 
 ```typescript
-// Route schema
-schema: {
-  type: "object",
-  properties: {
-    destination: { type: "string" },
-    departureDate: { type: "string", format: "date" },
-    passengers: { type: "number", minimum: 1 }
-  },
-  required: ["destination", "departureDate"]
-}
+// Agent-level schema
+const agent = new Agent<{}, TravelData>({
+  schema: {
+    type: "object",
+    properties: {
+      destination: { type: "string" },
+      departureDate: { type: "string", format: "date" },
+      passengers: { type: "number", minimum: 1 },
+      hotelPreference: { type: "string" },
+      budgetRange: { type: "string" }
+    },
+    required: ["destination", "departureDate"]
+  }
+});
+
+// Route specifies which fields to collect
+const flightRoute = agent.createRoute({
+  title: "Flight Booking",
+  requiredFields: ["destination", "departureDate", "passengers"],
+  optionalFields: ["budgetRange"]
+});
 ```
 
 Generates:
 
 ```
-Extract the following information from the user's response:
+Extract the following information from the user's response based on the agent schema:
 - destination: string - Where the user wants to fly
 - departureDate: string (date format) - When they want to depart
 - passengers: number (minimum 1) - How many people are traveling
+- budgetRange: string (optional) - Budget preference for the trip
 
-Return extracted data as valid JSON matching this schema.
+Return extracted data as valid JSON matching the agent schema.
+Current route requires: destination, departureDate, passengers
+Route completion: 2/3 required fields collected
 ```
 
 ## Tool Integration

package/docs/core/ai-integration/response-processing.md

@@ -20,26 +20,33 @@ AI responses are parsed to extract:
 3. **Tool Calls** - Instructions to execute tools
 4. **Routing Decisions** - Route or step transitions
 
-## Schema-Driven Extraction
+## Agent-Level Schema-Driven Extraction
 
-When steps specify `collect` fields, the AI response is validated against JSON schemas:
+When steps specify `collect` fields, the AI response is validated against the agent-level JSON schema:
 
 ```typescript
-const step = route.initialStep.nextStep({
-  prompt: "What's your name and email?",
-  collect: ["name", "email"],
+// Agent defines comprehensive schema
+const agent = new Agent<{}, UserData>({
   schema: {
     type: "object",
     properties: {
       name: { type: "string" },
       email: { type: "string", format: "email" },
+      phone: { type: "string" },
+      preferences: { type: "object" }
     },
-    required: ["name", "email"],
-  },
+    required: ["name", "email"]
+  }
+});
+
+// Steps collect into agent schema
+const step = route.initialStep.nextStep({
+  prompt: "What's your name and email?",
+  collect: ["name", "email"], // Maps to agent schema fields
 });
 ```
 
-The AI receives instructions to return structured data alongside natural language responses.
+The AI receives instructions to return structured data that matches the agent-level schema, enabling cross-route data sharing.
 
 ## Tool Execution Pipeline
 
@@ -65,26 +72,30 @@ When tools are called, the response engine:
 
 ## Data Validation
 
-Extracted data is validated against route schemas:
+Extracted data is validated against the agent-level schema:
 
-- **Type checking** - Ensures correct data types
-- **Required fields** - Validates mandatory data presence
-- **Format validation** - Email, dates, custom formats
-- **Business rules** - Custom validation logic
+- **Type checking** - Ensures correct data types against agent schema
+- **Required fields** - Validates mandatory data presence for route completion
+- **Format validation** - Email, dates, custom formats from agent schema
+- **Business rules** - Custom validation logic in agent-level hooks
+- **Cross-route consistency** - Ensures data consistency across all routes
 
 ## Context Updates
 
 Response processing updates multiple context layers:
 
-### Session Data
+### Agent-Level Data
 
 ```typescript
-// Collected data merged into session
-session.data = {
-  ...session.data,
+// Collected data merged into agent-level data structure
+agent.collectedData = {
+  ...agent.collectedData,
   ...extractedData,
   ...toolResults,
 };
+
+// Session references agent data
+session.data = agent.collectedData;
 ```
 
 ### Route Context