@falai/agent 0.1.4 → 0.2.0

package/docs/CONSTRUCTOR_OPTIONS.md

@@ -18,16 +18,16 @@ interface AgentOptions<TContext = unknown> {
   // Required
   name: string;
   ai: AiProvider;
-  
+
   // Optional metadata
   description?: string;
   goal?: string;
   context?: TContext;
-  
+
   // Configuration
   maxEngineIterations?: number;
   compositionMode?: CompositionMode;
-  
+
   // Declarative initialization (NEW!)
   terms?: Term[];
   guidelines?: Guideline[];
@@ -44,43 +44,47 @@ const agent = new Agent({
   name: "SupportBot",
   description: "Helpful customer support",
   goal: "Resolve issues efficiently",
-  ai: new GeminiProvider({ apiKey: "..." }),
+  ai: new GeminiProvider({ apiKey: "...", model: "..." }),
   context: { userId: "123" },
-  
+
   terms: [
-    { name: "SLA", description: "Service Level Agreement", synonyms: ["response time"] }
+    {
+      name: "SLA",
+      description: "Service Level Agreement",
+      synonyms: ["response time"],
+    },
   ],
-  
+
   guidelines: [
     {
       condition: "User is frustrated",
       action: "Show empathy and offer escalation",
       tags: ["support"],
-      enabled: true
-    }
+      enabled: true,
+    },
   ],
-  
+
   capabilities: [
-    { title: "Ticket Management", description: "Create and track tickets" }
+    { title: "Ticket Management", description: "Create and track tickets" },
   ],
-  
+
   routes: [
     {
       title: "Create Ticket",
       description: "Help user create a support ticket",
       conditions: ["User wants to report an issue"],
       guidelines: [
-        { condition: "Issue is urgent", action: "Prioritize immediately" }
-      ]
-    }
+        { condition: "Issue is urgent", action: "Prioritize immediately" },
+      ],
+    },
   ],
-  
+
   observations: [
     {
       description: "User mentions problem but unclear what kind",
-      routeRefs: ["Create Ticket", "Check Ticket Status"] // By title!
-    }
-  ]
+      routeRefs: ["Create Ticket", "Check Ticket Status"], // By title!
+    },
+  ],
 });
 ```
 
@@ -92,7 +96,7 @@ const agent = new Agent({
 interface RouteOptions {
   // Required
   title: string;
-  
+
   // Optional
   description?: string;
   conditions?: string[];
@@ -115,16 +119,16 @@ const agent = new Agent({
         {
           condition: "User skips a step",
           action: "Gently remind them it's important",
-          tags: ["onboarding"]
+          tags: ["onboarding"],
         },
         {
           condition: "User seems confused",
           action: "Offer a quick tutorial video",
-          tags: ["help"]
-        }
-      ]
-    }
-  ]
+          tags: ["help"],
+        },
+      ],
+    },
+  ],
 });
 ```
 
@@ -187,18 +191,21 @@ obs.disambiguate([route1, route2]);
 ## 🎨 Best Practices
 
 ### Use Declarative When:
+
 - ✅ Configuration is **static** and known upfront
 - ✅ Loading config from **JSON/YAML files**
 - ✅ Building **reusable agent templates**
 - ✅ You want **clean, readable initialization**
 
 ### Use Fluent When:
+
 - ✅ Logic is **dynamic** or **conditional**
 - ✅ Building routes with **complex state machines**
 - ✅ Adding features **based on runtime conditions**
 - ✅ You prefer **step-by-step construction**
 
 ### Mix Both!
+
 ```typescript
 // Start with static config
 const agent = new Agent({
@@ -212,7 +219,7 @@ const agent = new Agent({
 if (user.isPremium) {
   agent.createGuideline({
     condition: "User asks for priority support",
-    action: "Escalate immediately to premium team"
+    action: "Escalate immediately to premium team",
   });
 }
 ```
@@ -221,15 +228,15 @@ if (user.isPremium) {
 
 ## 📊 Complete Comparison
 
-| Feature | Declarative (Constructor) | Fluent (Methods) |
-|---------|--------------------------|------------------|
-| **Terms** | `terms: Term[]` | `agent.createTerm(...)` |
-| **Guidelines** | `guidelines: Guideline[]` | `agent.createGuideline(...)` |
-| **Capabilities** | `capabilities: Capability[]` | `agent.createCapability(...)` |
-| **Routes** | `routes: RouteOptions[]` | `agent.createRoute(...)` |
-| **Route Guidelines** | `route.guidelines: Guideline[]` | `route.createGuideline(...)` |
-| **Observations** | `observations: ObservationOptions[]` | `agent.createObservation(...)` |
-| **Disambiguation** | `routeRefs: string[]` | `obs.disambiguate([...])` |
+| Feature              | Declarative (Constructor)            | Fluent (Methods)               |
+| -------------------- | ------------------------------------ | ------------------------------ |
+| **Terms**            | `terms: Term[]`                      | `agent.createTerm(...)`        |
+| **Guidelines**       | `guidelines: Guideline[]`            | `agent.createGuideline(...)`   |
+| **Capabilities**     | `capabilities: Capability[]`         | `agent.createCapability(...)`  |
+| **Routes**           | `routes: RouteOptions[]`             | `agent.createRoute(...)`       |
+| **Route Guidelines** | `route.guidelines: Guideline[]`      | `route.createGuideline(...)`   |
+| **Observations**     | `observations: ObservationOptions[]` | `agent.createObservation(...)` |
+| **Disambiguation**   | `routeRefs: string[]`                | `obs.disambiguate([...])`      |
 
 ---
 

package/docs/CONTEXT_MANAGEMENT.md

@@ -0,0 +1,447 @@
+# Context Management & Persistence
+
+## Overview
+
+The `@falai/agent` framework provides flexible patterns for managing context in both **single-turn** and **multi-turn persistent** conversations. This guide explains how to handle stateful conversations that persist across requests.
+
+---
+
+## 🤔 The Context Lifecycle Problem
+
+### Single-Turn Conversations (Simple)
+
+```typescript
+// ✅ Works great for single-turn conversations
+const agent = new Agent({
+  name: "Bot",
+  ai: provider,
+  context: { userId: "123", preferences: {} },
+});
+
+const response = await agent.respond({ history });
+```
+
+**Works because:** Agent is used once and discarded.
+
+### Multi-Turn Conversations (Complex)
+
+```typescript
+// ❌ PROBLEM: Context updates don't persist
+const agent = new Agent({
+  name: "Bot",
+  ai: provider,
+  context: { userId: "123", preferences: {} },
+});
+
+// Turn 1
+await agent.respond({ history: [message1] });
+// Tool modifies context in memory...
+
+// Turn 2 (new request, agent recreated)
+const agent2 = new Agent({ context: { userId: "123", preferences: {} } });
+await agent2.respond({ history: [message2] });
+// ❌ Lost the context changes from Turn 1!
+```
+
+**Problem:** When agents are recreated (e.g., across HTTP requests), context updates are lost.
+
+---
+
+## 💡 Solution: Context Lifecycle Hooks
+
+The framework provides **lifecycle hooks** to integrate with your persistence layer (database, cache, etc.).
+
+### Pattern 1: `beforeRespond` + `onContextUpdate` (Recommended)
+
+```typescript
+import { Agent, type ContextLifecycleHooks } from "@falai/agent";
+
+// Define hooks
+const hooks: ContextLifecycleHooks<MyContext> = {
+  // Load fresh context before each response
+  beforeRespond: async (currentContext) => {
+    return await database.loadContext(sessionId);
+  },
+
+  // Persist context after updates
+  onContextUpdate: async (newContext, previousContext) => {
+    await database.saveContext(sessionId, newContext);
+  },
+};
+
+// Create agent with hooks
+const agent = new Agent({
+  name: "Bot",
+  ai: provider,
+  context: initialContext,
+  hooks, // 🔑 Enable persistence
+});
+```
+
+**How it works:**
+
+1. `beforeRespond` fetches fresh context from your database before `respond()` is called
+2. Tools can update context using `toolContext.updateContext()` or returning `{ contextUpdate }`
+3. `onContextUpdate` automatically persists changes to your database
+4. Next request creates a new agent, `beforeRespond` loads the updated context
+
+---
+
+## 🔧 Tool Context Updates
+
+Tools can update context in **two ways**:
+
+### Option A: Return `contextUpdate`
+
+```typescript
+const saveName = defineTool<MyContext, [name: string], boolean>(
+  "save_name",
+  async (toolContext, name) => {
+    return {
+      data: true,
+      contextUpdate: {
+        userName: name,
+        updatedAt: new Date(),
+      },
+    };
+  }
+);
+```
+
+**Pros:**
+
+- Declarative and functional
+- Easy to test
+- Context update is part of the result
+
+### Option B: Call `updateContext()` directly
+
+```typescript
+const saveName = defineTool<MyContext, [name: string], boolean>(
+  "save_name",
+  async (toolContext, name) => {
+    await toolContext.updateContext({
+      userName: name,
+      updatedAt: new Date(),
+    });
+
+    return { data: true };
+  }
+);
+```
+
+**Pros:**
+
+- More imperative and direct
+- Can update context at any point in the tool
+- Useful for complex logic
+
+**Both approaches trigger the `onContextUpdate` hook automatically.**
+
+---
+
+## 🌐 Context Provider Pattern
+
+For scenarios where context is **always loaded from an external source**, use the `contextProvider` pattern:
+
+```typescript
+const agent = new Agent({
+  name: "Bot",
+  ai: provider,
+
+  // Instead of static context:
+  contextProvider: async () => {
+    // Fetch context fresh on every respond() call
+    return await database.loadContext(sessionId);
+  },
+
+  hooks: {
+    // Still persist updates
+    onContextUpdate: async (newContext) => {
+      await database.saveContext(sessionId, newContext);
+    },
+  },
+});
+```
+
+**When to use:**
+
+- Context is always loaded from a database/cache
+- You never have a static starting context
+- You want guaranteed fresh data on every request
+
+**Difference from `beforeRespond`:**
+
+- `contextProvider`: **Replaces** the context entirely
+- `beforeRespond`: **Updates** the existing context (can access previous state)
+
+---
+
+## 🎯 Complete Example: Multi-Turn Onboarding
+
+```typescript
+import { Agent, defineTool } from "@falai/agent";
+
+interface OnboardingContext {
+  sessionId: string;
+  userId: string;
+  businessName?: string;
+  industry?: string;
+  completedSteps: string[];
+}
+
+// Database simulation
+const db = {
+  async loadSession(sessionId: string) {
+    return await database.findSession(sessionId);
+  },
+  async saveSession(sessionId: string, data: Partial<OnboardingContext>) {
+    await database.updateSession(sessionId, data);
+  },
+};
+
+// Factory function for creating agents
+async function createOnboardingAgent(sessionId: string) {
+  const session = await db.loadSession(sessionId);
+
+  const agent = new Agent<OnboardingContext>({
+    name: "OnboardingBot",
+    ai: provider,
+    context: {
+      sessionId,
+      userId: session.userId,
+      businessName: session.businessName,
+      industry: session.industry,
+      completedSteps: session.completedSteps || [],
+    },
+    hooks: {
+      // Load fresh context before responding
+      beforeRespond: async (current) => {
+        const fresh = await db.loadSession(sessionId);
+        return { ...current, ...fresh };
+      },
+
+      // Persist context after updates
+      onContextUpdate: async (newContext) => {
+        await db.saveSession(sessionId, {
+          businessName: newContext.businessName,
+          industry: newContext.industry,
+          completedSteps: newContext.completedSteps,
+        });
+      },
+    },
+  });
+
+  // Define tools with context updates
+  const saveBusinessName = defineTool(
+    "save_business_name",
+    async (ctx, name: string) => {
+      return {
+        data: true,
+        contextUpdate: {
+          businessName: name,
+          completedSteps: [...ctx.context.completedSteps, "business_name"],
+        },
+      };
+    }
+  );
+
+  const saveIndustry = defineTool(
+    "save_industry",
+    async (ctx, industry: string) => {
+      // Alternative: use updateContext directly
+      await ctx.updateContext({
+        industry,
+        completedSteps: [...ctx.context.completedSteps, "industry"],
+      });
+
+      return { data: true };
+    }
+  );
+
+  // Build conversation routes...
+  const route = agent.createRoute({ title: "Onboarding" });
+  // ...
+
+  return agent;
+}
+
+// Usage across multiple turns
+async function handleUserMessage(sessionId: string, message: string) {
+  // Recreate agent for each turn (context is loaded fresh)
+  const agent = await createOnboardingAgent(sessionId);
+
+  const response = await agent.respond({
+    history: [createMessageEvent(EventSource.CUSTOMER, "User", message)],
+  });
+
+  return response.message;
+}
+```
+
+---
+
+## 📋 Best Practices
+
+### ✅ DO
+
+- **Recreate agents** for each request in multi-turn conversations
+- **Use lifecycle hooks** to integrate with your database
+- **Store context** in your database/cache (Redis, PostgreSQL, etc.)
+- **Load fresh context** via `beforeRespond` or `contextProvider`
+- **Test persistence** by simulating multiple turns
+- **Handle errors** in hooks gracefully (fallback to current context)
+
+### ❌ DON'T
+
+- **Cache agent instances** across requests (context gets stale)
+- **Mutate context directly** without using `updateContext()` or `contextUpdate`
+- **Rely on in-memory state** for multi-turn conversations
+- **Forget to handle** `onContextUpdate` failures (could lose data)
+- **Mix** `context` and `contextProvider` (will throw an error)
+
+---
+
+## 🔍 Debugging Context Issues
+
+### Problem: Context updates aren't persisting
+
+**Check:**
+
+1. Are you using `onContextUpdate` hook?
+2. Is your database save actually working?
+3. Are you recreating the agent with fresh context each turn?
+
+```typescript
+// Debug your hooks
+hooks: {
+  beforeRespond: async (current) => {
+    console.log("📥 Loading context:", current);
+    const fresh = await db.load(sessionId);
+    console.log("✅ Loaded fresh:", fresh);
+    return fresh;
+  },
+
+  onContextUpdate: async (newContext) => {
+    console.log("💾 Saving context:", newContext);
+    await db.save(sessionId, newContext);
+    console.log("✅ Saved successfully");
+  },
+},
+```
+
+### Problem: Context is null/undefined
+
+**Check:**
+
+1. Did you provide either `context` or `contextProvider`?
+2. Is your `contextProvider` returning valid data?
+3. Is `beforeRespond` returning valid context?
+
+```typescript
+// Validate your contextProvider
+contextProvider: async () => {
+  const ctx = await db.load(sessionId);
+  if (!ctx) {
+    console.error("❌ Context not found!");
+    throw new Error("Session not found");
+  }
+  return ctx;
+},
+```
+
+### Problem: Tools not updating context
+
+**Check:**
+
+1. Are you returning `{ contextUpdate }` or calling `toolContext.updateContext()`?
+2. Is `onContextUpdate` being called? (Add console.log)
+3. Are your tools being executed at all?
+
+---
+
+## 🚀 Advanced Patterns
+
+### Pattern: Context Versioning
+
+```typescript
+interface VersionedContext extends MyContext {
+  version: number;
+}
+
+hooks: {
+  onContextUpdate: async (newContext) => {
+    await db.save(sessionId, {
+      ...newContext,
+      version: newContext.version + 1,
+    });
+  },
+
+  beforeRespond: async (current) => {
+    const fresh = await db.load(sessionId);
+    if (fresh.version > current.version) {
+      console.log("⚠️ Context changed by another request!");
+    }
+    return fresh;
+  },
+},
+```
+
+### Pattern: Selective Persistence
+
+```typescript
+// Only persist specific fields
+hooks: {
+  onContextUpdate: async (newContext) => {
+    // Don't persist temporary/computed fields
+    const { tempData, ...persistable } = newContext;
+    await db.save(sessionId, persistable);
+  },
+},
+```
+
+### Pattern: Multi-User Context
+
+```typescript
+interface MultiUserContext {
+  conversationId: string;
+  participants: Map<string, UserData>;
+}
+
+hooks: {
+  beforeRespond: async (current) => {
+    // Load all participant data
+    const conversation = await db.loadConversation(conversationId);
+    return {
+      conversationId,
+      participants: new Map(conversation.participants),
+    };
+  },
+},
+```
+
+---
+
+## 📚 Related Resources
+
+- [Complete Example: Persistent Onboarding](../examples/persistent-onboarding.ts)
+- [API Reference: AgentOptions](./API_REFERENCE.md#agentoptions)
+- [API Reference: ContextLifecycleHooks](./API_REFERENCE.md#contextlifecyclehooks)
+- [Getting Started](./GETTING_STARTED.md)
+
+---
+
+## 🆘 Need Help?
+
+If you're still having issues:
+
+1. Check the [examples](../examples/) for working implementations
+2. Review the [API Reference](./API_REFERENCE.md) for detailed type information
+3. Open an issue on GitHub with your use case
+
+**Remember:** The key to persistent conversations is:
+
+1. **Recreate agents** each turn
+2. **Load fresh context** via hooks/provider
+3. **Persist updates** via `onContextUpdate`
+4. **Never cache** agent instances across requests

package/docs/GETTING_STARTED.md

@@ -58,6 +58,7 @@ interface MyContext {
 // Create AI provider
 const ai = new GeminiProvider({
   apiKey: process.env.GEMINI_API_KEY!,
+  model: "models/gemini-2.5-pro",
 });
 
 // Create your agent
@@ -307,6 +308,7 @@ Increase timeout in provider config:
 ```typescript
 new GeminiProvider({
   apiKey: "...",
+  model: "models/gemini-2.5-flash",
   retryConfig: {
     timeout: 120000, // 2 minutes
     retries: 5,

package/docs/PROVIDERS.md

@@ -281,6 +281,7 @@ const geminiAgent = new Agent({
   name: "Gemini Assistant",
   ai: new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY!,
+    model: "models/gemini-2.5-flash",
   }),
 });
 
@@ -315,10 +316,12 @@ config();
 
 const geminiProvider = new GeminiProvider({
   apiKey: process.env.GEMINI_API_KEY!,
+  model: "models/gemini-2.5-flash",
 });
 
 const openaiProvider = new OpenAIProvider({
   apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5",
 });
 ```