@falai/agent 0.9.0-alpha-1 → 0.9.0

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

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

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

@@ -17,7 +17,7 @@ The tool execution system provides:
 ### Basic Tool Structure
 
 ```typescript
-interface Tool<TContext, TArgs extends unknown[], TResult, TData> {
+interface Tool<TContext, TData, TArgs extends unknown[], TResult> {
   id: string;
   name?: string; // Human-readable name shown to AI models
   description: string;
@@ -32,7 +32,7 @@ interface Tool<TContext, TArgs extends unknown[], TResult, TData> {
 import { Tool } from "@falai/agent";
 
 // Simple data retrieval tool
-const getWeather: Tool<unknown, [], string, WeatherData> = {
+const getWeather: Tool<unknown, WeatherData, [], string> = {
   id: "get_weather",
   name: "Weather Checker",
   description: "Get current weather for a location",
@@ -56,7 +56,7 @@ const getWeather: Tool<unknown, [], string, WeatherData> = {
 };
 
 // Data modification tool
-const updateUserProfile: Tool<unknown, [], string, ProfileData> = {
+const updateUserProfile: Tool<unknown, ProfileData, [], string> = {
   id: "update_profile",
   name: "Profile Updater",
   description: "Update user profile information",
@@ -136,9 +136,9 @@ Tools can modify agent context:
 ```typescript
 const locationTracker: Tool<
   { currentLocation?: string; locationHistory?: string[] },
+  { location: string },
   [],
-  string,
-  { location: string }
+  string
 > = {
   id: "track_location",
   description: "Track and update location information",
@@ -169,9 +169,9 @@ Tools can access current context:
 ```typescript
 const contextualTool: Tool<
   { userName?: string; currentLocation?: string },
+  {},
   [],
-  string,
-  {}
+  string
 > = {
   id: "personalized_greeting",
   description: "Generate personalized greeting based on context",
@@ -196,7 +196,7 @@ const contextualTool: Tool<
 Tools can modify session-collected data:
 
 ```typescript
-const dataEnrichmentTool: Tool<{}, [], string, { email?: string }> = {
+const dataEnrichmentTool: Tool<{}, { email?: string }, [], string> = {
   id: "enrich_user_data",
   description: "Enrich user profile with additional information",
   handler: async ({ data }) => {
@@ -221,7 +221,7 @@ const dataEnrichmentTool: Tool<{}, [], string, { email?: string }> = {
 ### Validation Integration
 
 ```typescript
-const validatingTool: Tool<{}, [], string, any> = {
+const validatingTool: Tool<{}, any, [], string> = {
   id: "validate_and_save",
   description: "Validate collected data and save to database",
   handler: async ({ data }) => {
@@ -362,9 +362,9 @@ while (hasToolCalls && toolLoopCount < MAX_TOOL_LOOPS) {
 ```typescript
 const robustTool: Tool<
   { lastApiCall?: string; errorCount?: number },
+  { endpoint: string },
   [],
-  string,
-  { endpoint: string }
+  string
 > = {
   id: "api_call",
   description: "Make external API call with error handling",
@@ -400,9 +400,9 @@ const robustTool: Tool<
 ```typescript
 const fallbackTool: Tool<
   { searchFallbackUsed?: boolean },
+  { query: string },
   [],
-  string,
-  { query: string }
+  string
 > = {
   id: "fallback_search",
   description: "Search with automatic fallback mechanisms",
@@ -452,9 +452,9 @@ let toolState = { conversationId: null };
 
 const conversationalTool: Tool<
   { conversationState?: any; lastMessage?: string },
+  { message: string },
   [],
-  string,
-  { message: string }
+  string
 > = {
   id: "continue_conversation",
   description: "Continue multi-turn conversation with state management",
@@ -493,9 +493,9 @@ Tools that set up data for other tools:
 ```typescript
 const setupTool: Tool<
   { activeWorkflowId?: string; workflowType?: string; workflowStep?: number },
+  { workflowType: string },
   [],
-  string,
-  { workflowType: string }
+  string
 > = {
   id: "setup_workflow",
   description: "Initialize a new workflow process",
@@ -526,9 +526,9 @@ const setupTool: Tool<
 
 const stepTool: Tool<
   { activeWorkflowId?: string; workflowStep?: number; lastStepResult?: any },
+  {},
   [],
-  string,
-  {}
+  string
 > = {
   id: "execute_workflow_step",
   description: "Execute the next step in active workflow",
@@ -559,7 +559,7 @@ const stepTool: Tool<
 
 ```typescript
 // Cache expensive operations
-const cachedTool: Tool<{ lastCacheHit?: boolean }, [], any, { key: string }> = {
+const cachedTool: Tool<{ lastCacheHit?: boolean }, { key: string }, [], any> = {
   id: "cached_data_lookup",
   description: "Lookup data with caching for performance",
   parameters: {
@@ -592,9 +592,9 @@ const cachedTool: Tool<{ lastCacheHit?: boolean }, [], any, { key: string }> = {
 ```typescript
 const batchTool: Tool<
   {},
+  { items: string[]; processedItems?: any[]; batchCompletedAt?: string },
   [],
-  string,
-  { items: string[]; processedItems?: any[]; batchCompletedAt?: string }
+  string
 > = {
   id: "batch_process",
   description: "Process multiple items in a single batch operation",
@@ -629,7 +629,7 @@ const batchTool: Tool<
 ### Tool Permissions
 
 ```typescript
-const secureTool: Tool<{ userRole?: string }, [], any, { action: string }> = {
+const secureTool: Tool<{ userRole?: string }, { action: string }, [], any> = {
   id: "admin_action",
   description: "Perform administrative actions with permission checks",
   parameters: {
@@ -662,9 +662,9 @@ const secureTool: Tool<{ userRole?: string }, [], any, { action: string }> = {
 ```typescript
 const validatedTool: Tool<
   { userId?: string; userRole?: string },
+  { userId: string; updates: any },
   [],
-  any,
-  { userId: string; updates: any }
+  any
 > = {
   id: "user_update",
   description: "Update user data with validation and permission checks",
@@ -717,7 +717,7 @@ const agent = new Agent({
 ### Performance Monitoring
 
 ```typescript
-const monitoredTool: Tool<{}, [], any, { args: any }> = {
+const monitoredTool: Tool<{}, { args: any }, [], any> = {
   id: "monitored_operation",
   description: "Execute operation with performance monitoring",
   parameters: {

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

@@ -214,7 +214,7 @@ const secureTool = {
 ```typescript
 import { Tool } from "@falai/agent";
 
-const contextSecureTool: Tool<SecureContext, [], UserData> = {
+const contextSecureTool: Tool<SecureContext, UserData, [], any> = {
   id: "user_data_access",
   description: "Access user data with security checks",
   parameters: {
@@ -415,9 +415,9 @@ class ToolRegistry {
 ```typescript
 const multiTenantTool: Tool<
   { tenantId: string },
+  { query: string },
   [],
-  string,
-  { query: string }
+  string
 > = {
   id: "tenant_search",
   description: "Search within tenant's data scope",
@@ -472,7 +472,7 @@ const timeSensitiveTool = {
 ### Usage-Based Limiting
 
 ```typescript
-const limitedTool: Tool<{ userId: string }, [args: any], string, any> = {
+const limitedTool: Tool<{ userId: string }, any, [args: any], string> = {
   id: "premium_feature",
   description: "Execute premium feature with usage limits",
   parameters: {
@@ -528,7 +528,7 @@ const agent = new Agent({
 ### Access Audit Logging
 
 ```typescript
-const auditedTool: Tool<{ userId: string }, [args: any], string, any> = {
+const auditedTool: Tool<{ userId: string }, any, [args: any], string> = {
   id: "sensitive_operation",
   description: "Perform sensitive operation with audit logging",
   parameters: {

package/docs/guides/getting-started/README.md

@@ -128,7 +128,7 @@ interface BookingData {
 }
 ```
 
-### Create a Schema-Driven Route
+### Create an Agent with Centralized Data Schema
 
 ```typescript
 import { Agent, GeminiProvider, type Tool } from "@falai/agent";
@@ -154,53 +154,66 @@ const checkAvailability: Tool<{}, [], string, BookingData> = {
   },
 };
 
-// Create agent
-const agent = new Agent({
+// Create agent with centralized data schema
+const agent = new Agent<{}, BookingData>({
   name: "TravelAgent",
   provider: new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY!,
   }),
-});
-
-// Data collection schema
-const bookingSchema = {
-  type: "object",
-  properties: {
-    destination: { type: "string", description: "Travel destination" },
-    travelDate: { type: "string", description: "Travel date" },
-    travelers: { type: "number", minimum: 1, maximum: 10 },
-    budget: { type: "number", description: "Budget in USD" },
+  
+  // Agent-level schema defines all possible data fields
+  schema: {
+    type: "object",
+    properties: {
+      destination: { type: "string", description: "Travel destination" },
+      travelDate: { type: "string", description: "Travel date" },
+      travelers: { type: "number", minimum: 1, maximum: 10 },
+      budget: { type: "number", description: "Budget in USD" },
+    },
+    required: ["destination", "travelers"],
   },
-  required: ["destination", "travelers"],
-} as const;
+  
+  // Agent-level tools available to all routes
+  tools: [checkAvailability],
+  
+  // Agent-level data validation and enrichment
+  hooks: {
+    onDataUpdate: async (data, previousData) => {
+      // Auto-set budget range based on travelers
+      if (data.travelers && !data.budget) {
+        data.budget = data.travelers * 500; // Default $500 per person
+      }
+      return data;
+    }
+  }
+});
 
-// Create route with schema
-const bookingRoute = agent.createRoute<BookingData>({
+// Routes specify required fields instead of schemas
+const bookingRoute = agent.createRoute({
   title: "Travel Booking",
   description: "Help users book travel",
-  schema: bookingSchema,
   conditions: ["User wants to book travel"],
+  requiredFields: ["destination", "travelDate", "travelers"], // Required for completion
+  optionalFields: ["budget"], // Nice to have but not required
+  
   initialStep: {
     prompt: "I'd love to help you book a trip! Where would you like to go?",
     collect: ["destination"],
   },
 });
 
-// Add tool to route
-bookingRoute.createTool(checkAvailability);
-
-// Build conversation flow
+// Build conversation flow with agent-level data awareness
 const askDate = bookingRoute.initialStep.nextStep({
   prompt: "When would you like to travel?",
   collect: ["travelDate"],
-  requires: ["destination"],
-  skipIf: (data) => !!data.travelDate,
+  requires: ["destination"], // Must have destination from agent data
+  skipIf: (data) => !!data.travelDate, // Skip if already collected
 });
 
 const askTravelers = askDate.nextStep({
   prompt: "How many people are traveling?",
   collect: ["travelers"],
-  requires: ["destination"],
+  requires: ["destination"], // Prerequisites from agent data
   skipIf: (data) => data.travelers !== undefined,
 });
 
@@ -213,22 +226,27 @@ const askBudget = askTravelers.nextStep({
 
 const checkAndBook = askBudget.nextStep({
   prompt: "Let me check availability for your trip.",
-  tool: checkAvailability,
-  requires: ["destination", "travelers"],
+  tool: checkAvailability, // Tool accesses complete agent data
+  requires: ["destination", "travelers"], // Minimum data needed
 });
 ```
 
-### Test the Data-Driven Agent
+### Test the Agent-Level Data Collection
 
 ```typescript
 async function testBookingAgent() {
-  // Create agent with automatic session management
-  const sessionAgent = new Agent({
+  // Create agent with automatic session management and agent-level schema
+  const sessionAgent = new Agent<{}, BookingData>({
     name: "TravelAgent",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
     }),
     sessionId: "user-alice", // Automatically manages this session
+    
+    // Same agent-level schema and configuration
+    schema: agent.schema,
+    tools: agent.tools,
+    hooks: agent.hooks
   });
 
   // Copy the route to the session agent
@@ -238,13 +256,17 @@ async function testBookingAgent() {
   const response1 = await sessionAgent.respond("I want to go to Paris");
 
   console.log("Bot:", response1.message);
-  console.log("Collected:", sessionAgent.session.getData<BookingData>());
+  console.log("Agent data:", sessionAgent.getCollectedData()); // Agent-level data access
 
   // User provides more details - session automatically maintained
   const response2 = await sessionAgent.respond("Next Friday, 2 people, $2000 budget");
 
   console.log("Bot:", response2.message);
-  console.log("Final data:", sessionAgent.session.getData<BookingData>());
+  console.log("Final agent data:", sessionAgent.getCollectedData());
+  
+  // Check route completion
+  console.log("Route complete:", bookingRoute.isComplete(sessionAgent.getCollectedData()));
+  console.log("Progress:", Math.round(bookingRoute.getCompletionProgress(sessionAgent.getCollectedData()) * 100) + "%");
 }
 
 testBookingAgent();

package/docs/guides/migration/README.md

@@ -0,0 +1,72 @@
+# Migration Guides
+
+This directory contains migration guides for major changes and updates to the `@falai/agent` framework.
+
+## Available Migration Guides
+
+### [ResponseModal Refactor Migration Guide](./response-modal-refactor.md)
+
+**Latest Update** - Comprehensive guide for migrating to the new ResponseModal architecture.
+
+**What's New:**
+- 🚀 **Modern Streaming API**: Simple `agent.stream('message')` interface
+- 🏗️ **Better Architecture**: Separated response logic from Agent class
+- 🔄 **Full Backward Compatibility**: All existing code continues to work
+- ⚡ **Performance Improvements**: Unified response logic and optimizations
+
+**Key Benefits:**
+- Automatic session management with `stream()` API
+- Simplified streaming interface compared to `respondStream()`
+- Better error handling with `ResponseGenerationError`
+- Improved maintainability and testability
+
+**Migration Status:**
+- ✅ **Backward Compatible**: No breaking changes
+- ✅ **Gradual Migration**: Adopt new APIs at your own pace
+- ✅ **Production Ready**: New APIs are fully tested and stable
+
+---
+
+## Migration Philosophy
+
+Our migration approach prioritizes:
+
+1. **🔄 Backward Compatibility**: Existing code continues to work without changes
+2. **📈 Gradual Adoption**: New features can be adopted incrementally
+3. **📚 Clear Documentation**: Comprehensive guides with examples
+4. **🛠️ Developer Experience**: Improved APIs that are easier to use
+5. **⚡ Performance**: Better performance without breaking existing functionality
+
+## Getting Help
+
+- **📖 Documentation**: Each migration guide includes detailed examples and comparisons
+- **💡 Examples**: Check the [examples directory](../../../examples/) for updated code samples
+- **🐛 Issues**: Report migration issues on [GitHub Issues](https://github.com/falai-dev/agent/issues)
+- **💬 Discussions**: Ask questions in [GitHub Discussions](https://github.com/falai-dev/agent/discussions)
+
+## Best Practices
+
+### Before Migrating
+
+1. **Read the migration guide** thoroughly
+2. **Test in development** before applying to production
+3. **Review examples** to understand new patterns
+4. **Check for breaking changes** (though we avoid them when possible)
+
+### During Migration
+
+1. **Migrate gradually** - don't change everything at once
+2. **Keep existing code working** while adopting new APIs
+3. **Test thoroughly** after each migration step
+4. **Monitor performance** to ensure improvements
+
+### After Migration
+
+1. **Update documentation** to reflect new patterns
+2. **Train team members** on new APIs and best practices
+3. **Monitor for issues** and report any problems
+4. **Share feedback** to help improve future migrations
+
+---
+
+**Stay Updated**: Watch the repository for new migration guides and updates.