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

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

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;
     },
   },