@falai/agent 0.9.0 → 1.0.0

package/docs/core/agent/README.md

@@ -168,18 +168,26 @@ const agent = new Agent<CustomerContext, CustomerData>({
     },
   ],
 
-  // Behavioral guidelines
+  // Enhanced behavioral guidelines with ConditionTemplate
   guidelines: [
     {
-      condition: "Customer seems frustrated",
+      condition: [
+        "Customer seems frustrated or upset", // AI context
+        (ctx) => ctx.data?.priority === 'high' // Programmatic check
+      ],
       action: "Apologize sincerely and offer to escalate to human agent",
       enabled: true,
     },
     {
-      condition: "Premium customer requests",
+      condition: (ctx) => ctx.accountTier === 'premium', // Function-only condition
       action: "Provide expedited service and additional options",
       enabled: true,
     },
+    {
+      condition: "User is asking for help with billing", // String-only condition
+      action: "Be extra careful with financial information and offer phone support",
+      enabled: true,
+    },
   ],
 
   // Global tools available to all routes
@@ -366,7 +374,7 @@ const agent = new Agent<CustomerContext, CustomerData>({
     {
       title: "Technical Support",
       description: "Help with technical issues",
-      conditions: ["user reports technical problem"],
+      when: ["user reports technical problem"],
       // NEW: Routes specify required fields instead of schemas
       requiredFields: ["customerName", "email", "issueType", "issueDescription"],
       optionalFields: ["phone", "priority"],
@@ -379,7 +387,7 @@ const agent = new Agent<CustomerContext, CustomerData>({
     {
       title: "Billing Inquiry", 
       description: "Handle billing and payment questions",
-      conditions: ["user asks about billing or payment"],
+      when: ["user asks about billing or payment"],
       requiredFields: ["customerName", "email", "issueType"],
       initialStep: {
         prompt:
@@ -416,6 +424,113 @@ const routes = agent.getRoutes();
 console.log(routes.map((r) => r.title)); // ["Customer Support", ...]
 ```
 
+## Enhanced Guideline System
+
+### Flexible Guideline Conditions
+
+Guidelines now support the powerful `ConditionTemplate` system, allowing for more sophisticated behavioral control:
+
+```typescript
+// String-only condition (AI context)
+agent.addGuideline({
+  condition: "User is asking for technical help",
+  action: "Provide detailed technical explanations with examples"
+});
+
+// Function-only condition (programmatic)
+agent.addGuideline({
+  condition: (ctx) => ctx.data?.userType === 'premium',
+  action: "Offer priority support and additional features"
+});
+
+// Mixed array condition (hybrid approach)
+agent.addGuideline({
+  condition: [
+    "User seems confused or needs clarification", // AI context
+    (ctx) => ctx.data?.attemptCount > 2 // Programmatic check
+  ],
+  action: "Slow down, use simpler language, and offer to connect with human support"
+});
+
+// Complex conditional guidelines
+agent.addGuideline({
+  condition: [
+    "User is reporting a critical issue", // AI context
+    (ctx) => ctx.data?.accountTier === 'enterprise', // Account check
+    (ctx) => new Date().getHours() >= 9 && new Date().getHours() <= 17 // Business hours
+  ],
+  action: "Immediately escalate to senior technical support and provide direct contact information"
+});
+```
+
+### Guideline Evaluation Logic
+
+Guidelines use **AND logic** for arrays - all conditions must be met:
+
+- **String conditions**: Provide context to AI for guideline matching
+- **Function conditions**: Must return `true` for guideline to activate
+- **Arrays**: All functions must return `true`, strings provide AI context
+
+### Context-Aware Guidelines
+
+Guidelines can access both agent context and collected data:
+
+```typescript
+interface SupportContext {
+  userTier: 'free' | 'premium' | 'enterprise';
+  supportTicketCount: number;
+  lastContactDate?: Date;
+}
+
+interface SupportData {
+  issueType?: string;
+  severity?: 'low' | 'medium' | 'high' | 'critical';
+  previousAttempts?: number;
+}
+
+agent.addGuideline({
+  condition: [
+    "User has contacted support multiple times recently", // AI context
+    (ctx) => ctx.context?.supportTicketCount > 3, // Context check
+    (ctx) => ctx.data?.severity === 'high' // Data check
+  ],
+  action: "Acknowledge their patience, apologize for the inconvenience, and prioritize their case"
+});
+```
+
+### Dynamic Guideline Activation
+
+Guidelines can be activated based on conversation state:
+
+```typescript
+// Time-based guidelines
+agent.addGuideline({
+  condition: (ctx) => {
+    const hour = new Date().getHours();
+    return hour < 9 || hour > 17; // Outside business hours
+  },
+  action: "Inform user that live support is available during business hours (9 AM - 5 PM)"
+});
+
+// Progress-based guidelines
+agent.addGuideline({
+  condition: [
+    "User is making good progress", // AI context
+    (ctx) => Object.keys(ctx.data || {}).length > 3 // Has collected significant data
+  ],
+  action: "Acknowledge their cooperation and let them know we're almost done"
+});
+
+// Route-specific guidelines
+agent.addGuideline({
+  condition: [
+    "User is in the payment process", // AI context
+    (ctx) => ctx.session?.currentRoute?.id === 'payment_flow' // Route check
+  ],
+  action: "Be extra careful with payment information and confirm all details before processing"
+});
+```
+
 ## Tool Integration
 
 ### Agent-Level Tools

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

@@ -104,7 +104,7 @@ const response3 = await agent.respond("Also book me a hotel in Tokyo");
 
 **SessionManager API:**
 
-The `SessionManager` provides a clean API for session operations:
+The `SessionManager` provides a clean API for session operations with comprehensive error handling:
 
 ```typescript
 // Access the session manager
@@ -114,13 +114,19 @@ const sessionManager = agent.session;
 await sessionManager.getOrCreate("user-123");
 await sessionManager.getOrCreate(); // Auto-generates ID
 
-// History management
-await sessionManager.addMessage("user", "Hello");
-await sessionManager.addMessage("assistant", "Hi there!");
+// History management with error handling
+try {
+  await sessionManager.addMessage("user", "Hello");
+  await sessionManager.addMessage("assistant", "Hi there!");
+} catch (error) {
+  console.error("Failed to add message to history:", error);
+  // Message will be rolled back automatically
+}
+
 const history = sessionManager.getHistory();
 sessionManager.clearHistory();
 
-// Data access
+// Data access with synchronization
 const data = sessionManager.getData<FlightData>();
 await sessionManager.setData({ destination: "Paris" });
 
@@ -130,6 +136,147 @@ await sessionManager.delete();
 const newSession = await sessionManager.reset(true); // Preserve history
 ```
 
+### Agent-Session Data Synchronization
+
+The framework ensures bidirectional synchronization between agent collected data and session data:
+
+```typescript
+// Agent data updates automatically sync with session
+const agent = new Agent<{}, BookingData>({
+  sessionId: "user-123",
+  // ... other config
+});
+
+try {
+  // Update agent data - automatically syncs with session
+  await agent.updateCollectedData({
+    destination: "Tokyo",
+    passengers: 2
+  });
+  
+  // Session data is automatically updated
+  const sessionData = agent.session.getData<BookingData>();
+  console.log(sessionData.destination); // "Tokyo"
+  
+  // Update session data - automatically syncs with agent
+  await agent.session.setData({
+    checkInDate: "2025-03-15"
+  });
+  
+  // Agent data is automatically updated
+  const agentData = agent.getCollectedData();
+  console.log(agentData.checkInDate); // "2025-03-15"
+  
+} catch (error) {
+  console.error("Data synchronization failed:", error);
+  // Both agent and session data remain in consistent state
+}
+```
+
+### Error Handling in Data Synchronization
+
+```typescript
+class SessionManager<TData> {
+  async setData(data: Partial<TData>): Promise<void> {
+    const previousData = { ...this.session.data };
+    
+    try {
+      // Validate data if schema is available
+      if (this.schema) {
+        this.validateData(data);
+      }
+      
+      // Update session data
+      this.session.data = { ...this.session.data, ...data };
+      
+      // Sync with agent collected data
+      if (this.agent) {
+        await this.agent.updateCollectedData(data);
+      }
+      
+      // Persist changes
+      await this.save();
+      
+    } catch (error) {
+      // Rollback session data on any failure
+      this.session.data = previousData;
+      
+      console.error("Session data update failed, rolled back:", error);
+      throw new Error(`Data synchronization failed: ${error.message}`);
+    }
+  }
+  
+  async addMessage(role: "user" | "assistant", content: string): Promise<void> {
+    const message: HistoryItem = {
+      role,
+      content,
+      timestamp: new Date().toISOString()
+    };
+    
+    try {
+      // Add to session history
+      this.session.history.push(message);
+      
+      // Persist immediately for reliability
+      await this.save();
+      
+    } catch (error) {
+      // Remove message from history on persistence failure
+      this.session.history.pop();
+      
+      console.error("Failed to persist message:", error);
+      throw new Error(`Message persistence failed: ${error.message}`);
+    }
+  }
+}
+```
+
+### Chat Method with Proper Error Handling
+
+```typescript
+class Agent<TContext, TData> {
+  async chat(message: string, sessionId?: string): Promise<AgentResponse<TData>> {
+    try {
+      // Ensure session is loaded
+      if (!this.session || this.session.id !== sessionId) {
+        await this.loadSession(sessionId);
+      }
+      
+      // Add user message to history BEFORE processing
+      await this.session.addMessage("user", message);
+      
+      // Process the message
+      const response = await this.respond({
+        message,
+        sessionId: this.session.id
+      });
+      
+      // Add assistant response to history
+      if (response.message) {
+        await this.session.addMessage("assistant", response.message);
+      }
+      
+      return response;
+      
+    } catch (error) {
+      console.error("Chat method failed:", error);
+      
+      // Try to remove the user message if response failed
+      try {
+        const history = this.session.getHistory();
+        if (history.length > 0 && history[history.length - 1].role === "user") {
+          await this.session.removeLastMessage();
+        }
+      } catch (rollbackError) {
+        console.error("Failed to rollback user message:", rollbackError);
+      }
+      
+      throw new Error(`Chat failed: ${error.message}`);
+    }
+  }
+}
+```
+
 **Why?** Automatic session management provides:
 
 - **Zero Boilerplate** - No manual session creation or persistence code
@@ -442,7 +589,7 @@ For simple question-answering without step:
 ```typescript
 const qnaRoute = agent.createRoute({
   title: "Company Q&A",
-  conditions: ["User asks about company"],
+  when: ["User asks about company"],
   // NO schema - stepless!
 });
 

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

@@ -218,3 +218,138 @@ Prompts are optimized for token efficiency:
 - Leverage route-specific overrides for specialized behavior
 - Monitor token usage and optimize prompt length
 - Test prompts with different AI providers for consistency
+
+## BatchPromptBuilder for Multi-Step Execution
+
+When multiple steps execute in a single batch, the `BatchPromptBuilder` combines their prompts into a single coherent prompt.
+
+### Combined Prompt Structure
+
+```
+[Agent Identity & Personality]
+[Route Context]
+
+## Current Conversation Flow
+
+You are handling multiple aspects of this conversation in a single response.
+
+### Step 1: [Step Description]
+[Step Prompt]
+
+### Step 2: [Step Description]  
+[Step Prompt]
+
+[... additional steps ...]
+
+## Data Collection
+
+Extract the following information from your response:
+- field1 (type): description
+- field2 (type): description
+
+## Response Format
+
+Return JSON with:
+- message: Your response to the user
+- [collected fields as top-level properties]
+```
+
+### How Prompts Are Merged
+
+The `BatchPromptBuilder` preserves each step's intent while creating a unified prompt:
+
+```typescript
+// Individual step prompts
+const step1 = { prompt: "What's your name?", collect: ["name"] };
+const step2 = { prompt: "What's your email?", collect: ["email"] };
+const step3 = { prompt: "How can I help?", collect: ["request"] };
+
+// Combined prompt includes all three
+const result = await batchPromptBuilder.buildBatchPrompt({
+  steps: [step1, step2, step3],
+  route,
+  history,
+  context,
+  session,
+  agentOptions,
+});
+
+// result.prompt contains unified prompt
+// result.collectFields = ["name", "email", "request"]
+// result.stepCount = 3
+```
+
+### Collect Fields Aggregation
+
+All `collect` fields from all steps are combined and deduplicated:
+
+```typescript
+// Steps with overlapping collect fields
+const steps = [
+  { collect: ["name", "email"] },
+  { collect: ["email", "phone"] },  // email appears twice
+  { collect: ["preferences"] }
+];
+
+// Combined collect fields (deduplicated)
+// ["name", "email", "phone", "preferences"]
+```
+
+### Schema-Aware Field Descriptions
+
+When the agent has a schema, field descriptions are included in the prompt:
+
+```typescript
+// Agent schema
+const schema = {
+  properties: {
+    email: { type: "string", format: "email", description: "User's email address" },
+    guests: { type: "number", minimum: 1, description: "Number of guests" }
+  }
+};
+
+// Generated data collection section:
+// ## Data Collection
+// Extract the following information from your response:
+// - email (string): User's email address
+// - guests (number): Number of guests
+```
+
+### Single vs Multi-Step Prompts
+
+The prompt structure adapts based on batch size:
+
+```typescript
+// Single step batch
+// ## Current Step
+// [Step prompt]
+
+// Multi-step batch
+// ## Current Conversation Flow
+// You are handling multiple aspects of this conversation in a single response.
+// ### Step 1: ...
+// ### Step 2: ...
+```
+
+### Using BatchPromptBuilder
+
+```typescript
+import { BatchPromptBuilder } from "@falai/agent";
+
+const builder = new BatchPromptBuilder<MyContext, MyData>();
+
+const result = await builder.buildBatchPrompt({
+  steps: batchResult.steps,
+  route: currentRoute,
+  history: conversationHistory,
+  context: agentContext,
+  session: currentSession,
+  agentOptions: agent.getAgentOptions(),
+});
+
+// Use result.prompt for LLM call
+const llmResponse = await provider.generateMessage({
+  prompt: result.prompt,
+  // ...
+});
+```