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

package/dist/src/utils/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/utils/session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/utils/session.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -35,7 +35,7 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
 
 - **[Routes](./core/conversation-flows/routes.md)** - Route definition, lifecycle & completion
 - **[Steps](./core/conversation-flows/steps.md)** - Step configuration, data collection & validation
-- **[Data Collection](./core/conversation-flows/data-collection.md)** - Schema-driven data extraction
+- **[Data Collection](./core/conversation-flows/data-collection.md)** - Agent-level schema-driven data extraction
 
 #### AI Integration
 
@@ -74,7 +74,7 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
 → See [Route DSL](./core/conversation-flows/route-dsl.md), [Intelligent Routing](./core/routing/intelligent-routing.md), and [Step Transitions](./core/conversation-flows/step-transitions.md)
 
 **🎯 Collecting structured data?**
-→ Learn [Data Collection](./core/conversation-flows/data-collection.md) and [Schema-Driven Extraction](../examples/core-concepts/schema-driven-extraction.ts)
+→ Learn [Agent-Level Data Collection](./core/conversation-flows/data-collection.md) and [Schema-Driven Extraction](../examples/core-concepts/schema-driven-extraction.ts)
 
 **🔧 Working with tools?**
 → See [Tool Definition](./core/tools/tool-definition.md), [Tool Execution](./core/tools/tool-execution.md), and [Tool Scoping](./core/tools/tool-scoping.md)
@@ -89,7 +89,7 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
 
 - **Agent Architecture**: [Agent](./core/agent/README.md) | [Context](./core/agent/context-management.md) | [Sessions](./core/agent/session-management.md)
 - **AI Routing System**: [Intelligent Routing](./core/routing/intelligent-routing.md) | [Route DSL](./core/conversation-flows/route-dsl.md) | [Step Transitions](./core/conversation-flows/step-transitions.md)
-- **Conversation Flows**: [Routes](./core/conversation-flows/routes.md) | [Steps](./core/conversation-flows/steps.md) | [Data Collection](./core/conversation-flows/data-collection.md)
+- **Conversation Flows**: [Routes](./core/conversation-flows/routes.md) | [Steps](./core/conversation-flows/steps.md) | [Agent-Level Data Collection](./core/conversation-flows/data-collection.md)
 - **AI Integration**: [Providers](./core/ai-integration/providers.md) | [Prompts](./core/ai-integration/prompt-composition.md) | [Responses](./core/ai-integration/response-processing.md)
 - **Tools & Execution**: [Tool Definition](./core/tools/tool-definition.md) | [Tool Execution](./core/tools/tool-execution.md) | [Tool Scoping](./core/tools/tool-scoping.md)
 - **Persistence**: [Session Storage](./core/persistence/session-storage.md) | [Adapters](./core/persistence/adapters.md)

package/docs/api/README.md

@@ -17,14 +17,14 @@ Complete API documentation for `@falai/agent`. This framework provides a strongl
 
 ## Core Classes
 
-### `Agent<TContext>`
+### `Agent<TContext, TData>`
 
-Main agent class for managing conversational AI.
+Main agent class for managing conversational AI with agent-level data collection.
 
 #### Constructor
 
 ```typescript
-new Agent<TContext>(options: AgentOptions<TContext>)
+new Agent<TContext, TData>(options: AgentOptions<TContext, TData>)
 ```
 
 See [Agent](./AGENT.md) for full details.
@@ -33,7 +33,38 @@ See [Agent](./AGENT.md) for full details.
 
 ##### `createRoute(options: RouteOptions): Route`
 
-Creates a new conversation 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`
 

package/docs/api/overview.md

@@ -23,12 +23,12 @@ Complete API documentation for `@falai/agent`. This framework provides a strongl
 
 ### Agent
 
-The central orchestrator class that manages conversation flow, routing, and tool execution.
+The central orchestrator class that manages conversation flow, routing, tool execution, and agent-level data collection.
 
 #### Constructor
 
 ```typescript
-new Agent<TContext = unknown>(options: AgentOptions<TContext>)
+new Agent<TContext = unknown, TData = unknown>(options: AgentOptions<TContext, TData>)
 ```
 
 #### Properties
@@ -44,10 +44,10 @@ new Agent<TContext = unknown>(options: AgentOptions<TContext>)
 ##### Route Management
 
 ```typescript
-createRoute<TData = unknown>(options: RouteOptions<TContext, TData>): Route<TContext, TData>
+createRoute(options: RouteOptions<TContext, TData>): Route<TContext, TData>
 ```
 
-Creates a new conversation route with the specified options.
+Creates a new conversation route with required fields specification that references the agent-level schema.
 
 ##### Context Management
 
@@ -63,6 +63,26 @@ getContext(): Promise<TContext | undefined>
 
 Gets current context, fetching from provider if configured.
 
+##### Agent-Level Data Management
+
+```typescript
+getCollectedData(): Partial<TData>
+```
+
+Gets the current agent-level collected data.
+
+```typescript
+updateCollectedData(updates: Partial<TData>): Promise<void>
+```
+
+Updates agent-level collected data and triggers validation and lifecycle hooks.
+
+```typescript
+validateData(data: Partial<TData>): ValidationResult
+```
+
+Validates data against the agent-level schema, returning detailed validation results.
+
 ##### Response Generation
 
 ```typescript
@@ -150,7 +170,7 @@ hasPersistence(): boolean
 
 ### Route
 
-Represents a conversational journey with structured steps and data collection.
+Represents a conversational journey with required fields specification and steps that collect data into the agent-level schema.
 
 #### Constructor
 
@@ -177,6 +197,26 @@ getStep(stepId: string): Step<TContext, TData> | undefined
 getAllSteps(): Step<TContext, TData>[]
 ```
 
+##### Route Completion Logic
+
+```typescript
+isComplete(data: Partial<TData>): boolean
+```
+
+Checks if the route is complete based on agent-level data.
+
+```typescript
+getMissingRequiredFields(data: Partial<TData>): (keyof TData)[]
+```
+
+Returns the fields still needed for route completion.
+
+```typescript
+getCompletionProgress(data: Partial<TData>): number
+```
+
+Returns completion progress as a number between 0 and 1.
+
 ##### Data Collection
 
 ```typescript
@@ -559,23 +599,28 @@ getSnapshot(): { sessions: SessionData[]; messages: MessageData[] }
 ### Core Types
 
 ```typescript
-interface AgentOptions<TContext = unknown> {
+interface AgentOptions<TContext = unknown, TData = unknown> {
   name: string;
   provider: AiProvider;
   description?: string;
   goal?: string;
-  personality?: Template<TContext>;
-  identity?: Template<TContext>;
+  personality?: Template<TContext, TData>;
+  identity?: Template<TContext, TData>;
   context?: TContext;
   contextProvider?: ContextProvider<TContext>;
-  hooks?: ContextLifecycleHooks<TContext>;
+  
+  // NEW: Agent-level data schema and initial data
+  schema?: StructuredSchema;
+  initialData?: Partial<TData>;
+  
+  hooks?: ContextLifecycleHooks<TContext, TData>;
   debug?: boolean;
   session?: SessionState;
   persistence?: PersistenceConfig;
   terms?: Term<TContext>[];
   guidelines?: Guideline<TContext>[];
-  tools?: Tool<TContext, unknown[], unknown, unknown>[];
-  routes?: RouteOptions<TContext, unknown>[];
+  tools?: Tool<TContext, unknown[], unknown, TData>[];
+  routes?: RouteOptions<TContext, TData>[];
   knowledgeBase?: Record<string, unknown>;
 }
 
@@ -588,7 +633,14 @@ interface RouteOptions<TContext = unknown, TData = unknown> {
   conditions?: Template<TContext, TData>[];
   rules?: Template<TContext, TData>[];
   prohibitions?: Template<TContext, TData>[];
-  schema?: StructuredSchema;
+  
+  // NEW: Required fields for route completion (replaces schema)
+  requiredFields?: (keyof TData)[];
+  optionalFields?: (keyof TData)[];
+  
+  // REMOVED: schema (now at agent level)
+  // schema?: StructuredSchema;
+  
   initialData?: Partial<TData>;
   steps?: StepOptions<TContext, TData>[];
   initialStep?: Omit<StepOptions<TContext, TData>, "step">;
@@ -795,4 +847,106 @@ generateStepId(routeId: string, description?: string): string
 generateToolId(name: string): string
 ```
 
+## Agent-Level Data Collection Example
+
+Here's a comprehensive example showing the new agent-level data collection architecture:
+
+```typescript
+import { Agent, OpenAIProvider } from "@falai/agent";
+
+// Define comprehensive agent-level data interface
+interface CustomerServiceData {
+  // 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;
+}
+
+// Create agent with centralized schema
+const agent = new Agent<{}, CustomerServiceData>({
+  name: "Customer Service Agent",
+  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY, model: "gpt-4" }),
+  
+  // Agent-level schema defines all possible data fields
+  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" }
+    }
+  },
+  
+  // Agent-level data validation and enrichment
+  hooks: {
+    onDataUpdate: async (data, previousData) => {
+      // Auto-set priority based on issue type
+      if (data.issueType === 'billing' && !data.priority) {
+        data.priority = 'high';
+      }
+      
+      // Enrich customer data
+      if (data.customerName && !data.customerId) {
+        data.customerId = await lookupCustomerId(data.customerName);
+      }
+      
+      return data;
+    }
+  }
+});
+
+// Routes specify required fields instead of schemas
+const supportRoute = agent.createRoute({
+  title: "Customer Support",
+  requiredFields: ["customerName", "email", "issueType", "issueDescription"],
+  optionalFields: ["phone", "priority"],
+  
+  initialStep: {
+    prompt: "I'm here to help with your issue. Can you tell me your name and email?",
+    collect: ["customerName", "email"]
+  }
+});
+
+const feedbackRoute = agent.createRoute({
+  title: "Feedback Collection",
+  requiredFields: ["customerName", "email", "rating"],
+  optionalFields: ["comments", "recommendToFriend"],
+  
+  initialStep: {
+    prompt: "I'd love to get your feedback. What's your name and email?",
+    collect: ["customerName", "email"]
+  }
+});
+
+// Cross-route data sharing example
+const response1 = await agent.respond("Hi, I'm John Doe, email john@example.com, I have a billing issue");
+// Agent data: { customerName: "John Doe", email: "john@example.com", issueType: "billing" }
+
+const response2 = await agent.respond("Actually, I want to leave feedback instead. I'd rate you 5 stars.");
+// Feedback route completes immediately: already has name, email, and now rating
+// { customerName: "John Doe", email: "john@example.com", rating: 5 }
+
+// Check route completion
+console.log(feedbackRoute.isComplete(agent.getCollectedData())); // true
+console.log(feedbackRoute.getCompletionProgress(agent.getCollectedData())); // 1.0
+```
+
 This API reference covers the complete @falai/agent framework. For more detailed examples and usage patterns, see the [examples directory](../../examples/) and [guides](../../docs/guides/).

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