@falai/agent 0.4.0 → 0.5.0

package/docs/GETTING_STARTED.md

@@ -47,8 +47,17 @@ import {
   GeminiProvider,
   createMessageEvent,
   EventSource,
+  createSession,
 } from "@falai/agent";
 
+// Define your data extraction type
+interface FlightData {
+  destination: string;
+  departureDate: string;
+  passengers: number;
+  cabinClass: "economy" | "business" | "first";
+}
+
 // Define your context type
 interface MyContext {
   userId: string;
@@ -63,8 +72,8 @@ const ai = new GeminiProvider({
 
 // Create your agent
 const agent = new Agent<MyContext>({
-  name: "MyBot",
-  description: "A helpful assistant",
+  name: "FlightBot",
+  description: "A helpful flight booking assistant",
   ai,
   context: {
     userId: "user_123",
@@ -72,20 +81,44 @@ const agent = new Agent<MyContext>({
   },
 });
 
-// Add a guideline
-agent.createGuideline({
-  condition: "User asks for help",
-  action: "Be friendly and offer specific assistance",
+// Create a data-driven route
+const bookingRoute = agent.createRoute<FlightData>({
+  title: "Book Flight",
+  description: "Help user book a flight",
+  conditions: ["User wants to book a flight"],
+  gatherSchema: {
+    type: "object",
+    properties: {
+      destination: { type: "string" },
+      departureDate: { type: "string" },
+      passengers: { type: "number", minimum: 1, maximum: 9 },
+      cabinClass: {
+        type: "string",
+        enum: ["economy", "business", "first"],
+        default: "economy",
+      },
+    },
+    required: ["destination", "departureDate", "passengers"],
+  },
 });
 
-// Generate a response
+// Initialize session state
+let session = createSession<FlightData>();
+
+// Generate a response with session state
 const response = await agent.respond({
   history: [
-    createMessageEvent(EventSource.CUSTOMER, "Alice", "Hi, I need help!"),
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Alice",
+      "I want to fly to Paris tomorrow with 2 people"
+    ),
   ],
+  session,
 });
 
 console.log("Agent:", response.message);
+console.log("Extracted:", response.session?.extracted);
 ```
 
 ### 3. Run It!
@@ -100,83 +133,102 @@ bun run index.ts
 
 ## Next Steps
 
-### Add a Domain Glossary
+### Add Session State Management
 
-Help your agent understand your business:
+Continue the conversation with extracted data:
 
 ```typescript
-agent
-  .createTerm({
-    name: "Premium Plan",
-    description: "Our top-tier subscription at $99/month",
-    synonyms: ["pro plan", "premium subscription"],
-  })
-  .createTerm({
-    name: "SLA",
-    description: "Service Level Agreement - our response time guarantee",
-  });
+// Turn 2 - User provides more details
+const response2 = await agent.respond({
+  history: [
+    createMessageEvent(EventSource.AI_AGENT, "Bot", response.message),
+    createMessageEvent(EventSource.CUSTOMER, "Alice", "Make it business class"),
+  ],
+  session: response.session, // Pass previous session state
+});
+
+console.log("Agent:", response2.message);
+console.log("Updated extracted:", response2.session?.extracted);
+// Agent remembers destination and passengers, updates cabin class
 ```
 
-### Create Tools
+### Create Tools with Data Access
 
-Give your agent superpowers:
+Tools can access and modify extracted data:
 
 ```typescript
 import { defineTool } from "@falai/agent";
 
-const checkBalance = defineTool<MyContext, [accountId: string], number>(
-  "check_balance",
-  async ({ context }, accountId) => {
-    // Your logic here
-    const balance = await fetchBalance(accountId);
-    return { data: balance };
+const searchFlights = defineTool<MyContext, [], void, FlightData>(
+  "search_flights",
+  async ({ context, extracted }) => {
+    // Access extracted data directly
+    if (!extracted.destination || !extracted.departureDate) {
+      return { data: undefined };
+    }
+
+    // Search for flights and enrich extracted data
+    const flights = await searchFlightAPI(
+      extracted.destination,
+      extracted.departureDate
+    );
+
+    return {
+      data: undefined,
+      contextUpdate: { availableFlights: flights },
+      extractedUpdate: {
+        destinationCode: await lookupAirportCode(extracted.destination),
+      },
+    };
   },
-  { description: "Checks account balance" }
+  { description: "Search for available flights based on extracted data" }
 );
 
-agent.createGuideline({
-  condition: "User asks about their balance",
-  action: "Use the check_balance tool to retrieve current balance",
-  tools: [checkBalance],
-});
+// Add tool to state machine
+const searchState = bookingRoute.initialState
+  .transitionTo({
+    chatState: "Extract travel details",
+    gather: ["destination", "departureDate", "passengers"],
+  })
+  .transitionTo({
+    toolState: searchFlights,
+    requiredData: ["destination", "departureDate", "passengers"],
+  });
 ```
 
-### Build Conversation Routes
+### Build Smart State Machines
 
-Create structured flows:
+Create intelligent flows with code-based logic:
 
 ```typescript
-import { END_ROUTE } from "@falai/agent";
-
-const onboardingRoute = agent.createRoute({
-  title: "User Onboarding",
-  description: "Guide new users through setup",
-  conditions: ["User is new and needs onboarding"],
+// State machine with smart bypassing and data validation
+const askDestination = bookingRoute.initialState.transitionTo({
+  chatState: "Ask where they want to fly",
+  gather: ["destination"],
+  skipIf: (extracted) => !!extracted.destination, // Skip if already have destination
 });
 
-// Build the flow - two approaches:
-
-// Approach 1: Step-by-step (great for complex flows with branching)
-const step1 = onboardingRoute.initialState.transitionTo({
-  chatState: "Ask for user's name",
+const enrichDestination = askDestination.transitionTo({
+  toolState: searchFlights, // Tool executes automatically
+  requiredData: ["destination"], // Prerequisites
 });
 
-const step2 = step1.transitionTo({
-  chatState: "Ask for user's email",
+const askDates = enrichDestination.transitionTo({
+  chatState: "Ask about travel dates",
+  gather: ["departureDate"],
+  skipIf: (extracted) => !!extracted.departureDate,
+  requiredData: ["destination"], // Must have destination first
 });
 
-const step3 = step2.transitionTo({
-  chatState: "Confirm details and welcome user",
+const askPassengers = askDates.transitionTo({
+  chatState: "How many passengers?",
+  gather: ["passengers"],
+  skipIf: (extracted) => !!extracted.passengers,
 });
 
-step3.transitionTo({ state: END_ROUTE });
-
-// Approach 2: Fluent chaining (concise for linear flows)
-onboardingRoute.initialState
-  .transitionTo({ chatState: "Ask for user's name" })
-  .transitionTo({ chatState: "Ask for user's email" })
-  .transitionTo({ chatState: "Confirm details and welcome user" })
-  .transitionTo({ state: END_ROUTE });
+const presentFlights = askPassengers.transitionTo({
+  chatState: "Present available flights from search results",
+});
 ```
 
 ### Handle Context Dynamically
@@ -232,26 +284,59 @@ if (user.isPremium) {
 }
 ```
 
-### Multi-Turn Conversations
+### Multi-Turn Conversations with Session State
 
-Build up conversation history:
+Track conversation progress and extracted data:
 
 ```typescript
-const history: Event[] = [];
-
-// Turn 1
-history.push(createMessageEvent(EventSource.CUSTOMER, "User", "Hello"));
-const response1 = await agent.respond({ history });
-history.push(
-  createMessageEvent(EventSource.AI_AGENT, "Bot", response1.message)
-);
-
-// Turn 2
-history.push(createMessageEvent(EventSource.CUSTOMER, "User", "Tell me more"));
-const response2 = await agent.respond({ history });
-history.push(
-  createMessageEvent(EventSource.AI_AGENT, "Bot", response2.message)
-);
+import { createSession, enterRoute, mergeExtracted } from "@falai/agent";
+
+// Initialize session
+let session = createSession<FlightData>();
+
+// Turn 1 - User starts booking
+const history1 = [
+  createMessageEvent(
+    EventSource.CUSTOMER,
+    "User",
+    "I want to fly to Paris tomorrow with 2 people"
+  ),
+];
+
+const response1 = await agent.respond({ history: history1, session });
+console.log("Turn 1 - Extracted:", response1.session?.extracted);
+// { destination: "Paris", departureDate: "tomorrow", passengers: 2 }
+
+session = response1.session!; // Update session with extracted data
+
+// Turn 2 - User changes their mind
+const history2 = [
+  ...history1,
+  createMessageEvent(EventSource.AI_AGENT, "Bot", response1.message),
+  createMessageEvent(
+    EventSource.CUSTOMER,
+    "User",
+    "Actually, make that Tokyo instead"
+  ),
+];
+
+const response2 = await agent.respond({ history: history2, session });
+console.log("Turn 2 - Updated:", response2.session?.extracted);
+// { destination: "Tokyo", departureDate: "tomorrow", passengers: 2 }
+
+session = response2.session!; // Router handled the route change
+
+// Turn 3 - Continue with updated data
+const response3 = await agent.respond({
+  history: [
+    ...history2,
+    createMessageEvent(EventSource.AI_AGENT, "Bot", response2.message),
+    createMessageEvent(EventSource.CUSTOMER, "User", "Business class please"),
+  ],
+  session,
+});
+console.log("Turn 3 - Final:", response3.session?.extracted);
+// { destination: "Tokyo", departureDate: "tomorrow", passengers: 2, cabinClass: "business" }
 ```
 
 ---
@@ -260,20 +345,24 @@ history.push(
 
 ### ✅ Do's
 
-- **Use TypeScript** - Full type safety and IntelliSense
-- **Define custom context** - Strongly typed context for your domain
-- **Add glossary terms** - Help the agent understand your terminology
-- **Use specific guidelines** - Clear conditions and actions
-- **Enable/disable guidelines** - Use the `enabled` flag for A/B testing
-- **Tag your guidelines** - Organize with tags for filtering
+- **Use TypeScript** - Full type safety and IntelliSense throughout
+- **Define extraction schemas** - Use JSON Schema for reliable data collection
+- **Leverage session state** - Track conversation progress across turns
+- **Use code-based logic** - `skipIf` and `requiredData` for deterministic flow
+- **Create type-safe routes** - Generic types for both context and extracted data
+- **Handle user changes** - Always-on routing respects "I changed my mind"
+- **Add lifecycle hooks** - Validate and enrich extracted data
+- **Mix stateful & stateless** - Use appropriate patterns for each use case
 
 ### ❌ Don'ts
 
-- **Don't use `any` for context** - Define proper types
-- **Don't skip error handling** - Wrap agent calls in try/catch
-- **Don't forget to set API key** - Use environment variables
-- **Don't create overly complex routes** - Keep flows simple and clear
-- **Don't ignore linter warnings** - Fix TypeScript errors
+- **Don't use `any` types** - Define proper interfaces for context and extracted data
+- **Don't rely on LLM conditions** - Use code (`skipIf`) for state logic
+- **Don't skip session management** - Pass session state between turns
+- **Don't forget error handling** - Wrap agent calls in try/catch
+- **Don't ignore type errors** - Fix TypeScript issues for reliability
+- **Don't create fuzzy logic** - Use explicit schemas over prompt-based parsing
+- **Don't forget API keys** - Set environment variables properly
 
 ---
 
@@ -330,7 +419,7 @@ new GeminiProvider({
 
 - 📚 Read the [Constructor Options Guide](./CONSTRUCTOR_OPTIONS.md)
 - 🔍 Check the [API Reference](./API_REFERENCE.md)
-- 🏗️ Understand the [Architecture](./STRUCTURE.md)
+- 🏗️ Understand the [Architecture](./ARCHITECTURE.md)
 - 🎯 Explore [Examples](../examples/)
 
 ---

package/docs/PERSISTENCE.md

@@ -1,15 +1,16 @@
 # Persistence with @falai/agent
 
-The `@falai/agent` framework provides optional, flexible persistence for automatically saving conversation sessions and messages to your database.
+The `@falai/agent` framework provides optional, flexible persistence for automatically saving conversation sessions, extracted data, and messages to your database.
 
 ## Features
 
 - ✅ **Optional** - Persistence is completely optional
 - ✅ **Provider Pattern** - Simple API like AI providers (`new PrismaAdapter({ prisma })`)
-- ✅ **Type-safe** - Full TypeScript support
-- ✅ **Prisma Ready** - Built-in Prisma ORM adapter
+- ✅ **Type-safe** - Full TypeScript support with generics
+- ✅ **Session State Integration** - Automatic saving of extracted data and conversation progress
+- ✅ **Multiple Adapters** - Prisma, Redis, MongoDB, PostgreSQL, SQLite, OpenSearch, Memory
 - ✅ **Extensible** - Create adapters for any database
-- ✅ **Auto-save** - Automatic message persistence
+- ✅ **Auto-save** - Automatic session state and message persistence
 
 ## Quick Start with Prisma
 
@@ -80,7 +81,7 @@ npx prisma generate
 npx prisma migrate dev --name init
 ```
 
-### 4. Use in Your Agent (That's it!)
+### 4. Use in Your Agent with Session State (That's it!)
 
 ```typescript
 import { Agent, PrismaAdapter, GeminiProvider } from "@falai/agent";
@@ -88,6 +89,13 @@ import { PrismaClient } from "@prisma/client";
 
 const prisma = new PrismaClient();
 
+// Define your extracted data type
+interface BookingData {
+  destination: string;
+  date: string;
+  passengers: number;
+}
+
 const agent = new Agent({
   name: "My Agent",
   ai: new GeminiProvider({ apiKey: "..." }),
@@ -95,27 +103,55 @@ const agent = new Agent({
   persistence: {
     adapter: new PrismaAdapter({ prisma }),
     userId: "user_123",
+    autoSave: true, // Auto-saves session state!
+  },
+});
+
+// Create a route with data extraction
+const bookingRoute = agent.createRoute<BookingData>({
+  title: "Book Flight",
+  gatherSchema: {
+    type: "object",
+    properties: {
+      destination: { type: "string" },
+      date: { type: "string" },
+      passengers: { type: "number" },
+    },
+    required: ["destination", "date", "passengers"],
   },
 });
 
+// Define states with smart data gathering
+bookingRoute.initialState.transitionTo({
+  chatState: "Collect booking details",
+  gather: ["destination", "date", "passengers"],
+});
+
 // Access persistence methods
 const persistence = agent.getPersistenceManager();
 
-// Create a session
-const session = await persistence.createSession({
-  userId: "user_123",
-  agentName: "My Agent",
-});
+// Create a session with state support
+const { sessionData, sessionState } =
+  await persistence.createSessionWithState<BookingData>({
+    userId: "user_123",
+    agentName: "My Agent",
+  });
 
 // Load history
-const history = await persistence.loadSessionHistory(session.id);
+const history = await persistence.loadSessionHistory(sessionData.id);
 
-// Generate response
-const response = await agent.respond({ history });
+// Generate response with session state
+const response = await agent.respond({
+  history,
+  session: sessionState, // Pass session state
+});
+
+// Session state is auto-saved! ✨
+console.log("Extracted data:", response.session?.extracted);
 
-// Save message (auto-saved if configured)
+// Save message
 await persistence.saveMessage({
-  sessionId: session.id,
+  sessionId: sessionData.id,
   role: "agent",
   content: response.message,
 });
@@ -220,6 +256,96 @@ const agent = new Agent({
 await agent.updateContext({ preferences: { theme: "dark" } });
 ```
 
+## Session State Integration
+
+The new architecture automatically saves and loads `SessionState<TExtracted>` which includes:
+
+- **Current route and state** - Track conversation progress
+- **Extracted data** - All data gathered via `gatherSchema` and `gather` fields
+- **Route history** - History of route transitions
+- **Metadata** - Session timestamps and custom data
+
+### How It Works
+
+1. **Auto-Save**: When `autoSave: true`, session state is automatically persisted after each `respond()` call
+2. **Conversion**: `SessionState` is automatically converted to `SessionData` for storage
+3. **Recovery**: Load session state from database to resume conversations
+
+### Create Session with State
+
+```typescript
+const { sessionData, sessionState } =
+  await persistence.createSessionWithState<YourDataType>({
+    userId: "user_123",
+    agentName: "My Agent",
+    initialData: {
+      /* optional pre-filled data */
+    },
+  });
+
+// sessionData: Database record
+// sessionState: In-memory session state ready to use
+```
+
+### Save Session State
+
+```typescript
+// Manual save (not needed if autoSave: true)
+await persistence.saveSessionState(sessionId, sessionState);
+```
+
+### Load Session State
+
+```typescript
+// Load session state from database
+const sessionState = await persistence.loadSessionState<YourDataType>(
+  sessionId
+);
+
+// Load message history
+const history = await persistence.loadSessionHistory(sessionId);
+
+// Resume conversation
+const response = await agent.respond({
+  history,
+  session: sessionState,
+});
+```
+
+### What Gets Persisted
+
+The session state stores:
+
+```typescript
+{
+  currentRoute: {
+    id: "book_flight",
+    title: "Book a Flight",
+    enteredAt: Date
+  },
+  currentState: {
+    id: "ask_dates",
+    description: "Ask about travel dates",
+    enteredAt: Date
+  },
+  extracted: {
+    destination: "Paris",
+    departureDate: "2025-06-15",
+    passengers: 2
+  },
+  routeHistory: [
+    { routeId: "book_flight", enteredAt: Date, completed: false }
+  ],
+  metadata: {
+    sessionId: "session_123",
+    createdAt: Date,
+    lastUpdatedAt: Date
+  }
+}
+```
+
+This data is stored in `collectedData` field as JSON in the database.
+
 ## PersistenceManager API
 
 Access via `agent.getPersistenceManager()`:
@@ -227,7 +353,25 @@ Access via `agent.getPersistenceManager()`:
 ### Session Methods
 
 ```typescript
-// Create session
+// Create session with state support (NEW!)
+const { sessionData, sessionState } =
+  await persistence.createSessionWithState<YourDataType>({
+    userId: "user_123",
+    agentName: "My Agent",
+    initialData: {
+      /* optional */
+    },
+  });
+
+// Save session state (NEW!)
+await persistence.saveSessionState(sessionId, sessionState);
+
+// Load session state (NEW!)
+const sessionState = await persistence.loadSessionState<YourDataType>(
+  sessionId
+);
+
+// Create session (legacy)
 await persistence.createSession({
   userId: "user_123",
   agentName: "My Agent",
@@ -375,13 +519,16 @@ await persistence.saveMessage({
 
 ## Best Practices
 
-1. ✅ Use lifecycle hooks for automatic context persistence
-2. ✅ Enable `autoSave` to track message counts automatically
-3. ✅ Store minimal data in `collectedData`
-4. ✅ Index frequently queried fields
-5. ✅ Use cascading deletes for cleanup
-6. ✅ Handle errors gracefully
-7. ✅ Complete or abandon sessions when done
+1. ✅ **Use `createSessionWithState()`** - Get both database record and session state in one call
+2. ✅ **Enable `autoSave: true`** - Automatically persist session state after each response
+3. ✅ **Define extraction schemas** - Use `gatherSchema` in routes for structured data collection
+4. ✅ **Pass session state** - Always pass `session` parameter to `agent.respond()`
+5. ✅ **Load session state** - Use `loadSessionState()` to resume conversations
+6. ✅ **Store extracted data** - Leverage `collectedData.extracted` for user input tracking
+7. ✅ **Index frequently queried fields** - Add database indexes on `userId`, `status`, etc.
+8. ✅ **Use cascading deletes** - Clean up messages automatically when deleting sessions
+9. ✅ **Complete sessions** - Mark sessions as completed when conversation ends
+10. ✅ **Handle errors gracefully** - Wrap persistence calls in try-catch blocks
 
 ## Troubleshooting
 

package/docs/README.md

@@ -10,10 +10,9 @@ Welcome to the `@falai/agent` documentation!
 
 ### Core Concepts
 
-- **[Architecture](./ARCHITECTURE.md)** - Design principles & philosophy ⭐ **NEW**
-- **[Constructor Options](./CONSTRUCTOR_OPTIONS.md)** - Comprehensive guide to declarative vs fluent configuration
-- **[Context Management](./CONTEXT_MANAGEMENT.md)** - Dynamic context variables & lifecycle hooks
-- **[Package Structure](./STRUCTURE.md)** - Package organization and module design
+- **[Architecture](./ARCHITECTURE.md)** - Design principles & philosophy (Data-driven sessions) ⭐ **UPDATED**
+- **[Constructor Options](./CONSTRUCTOR_OPTIONS.md)** - Comprehensive guide to declarative vs fluent configuration ⭐ **UPDATED**
+- **[Context Management](./CONTEXT_MANAGEMENT.md)** - Session state & data extraction patterns ⭐ **UPDATED**
 
 ### Reference
 
@@ -47,19 +46,15 @@ Welcome to the `@falai/agent` documentation!
 **Need specific API details?**
 → Browse the [API Reference](./API_REFERENCE.md)
 
-**Understanding the codebase?**
-→ Read [Package Structure](./STRUCTURE.md)
-
 **Need persistence?**
 → See [Persistence Guide](./PERSISTENCE.md)
 
 ### By Topic
 
-- **Architecture & Design**: [Architecture Guide](./ARCHITECTURE.md) | [Package Structure](./STRUCTURE.md)
+- **Architecture & Design**: [Architecture Guide](./ARCHITECTURE.md)
 - **Agent Configuration**: [Constructor Options](./CONSTRUCTOR_OPTIONS.md) | [Context Management](./CONTEXT_MANAGEMENT.md)
 - **Conversation Flows**: [API Reference - Routes](./API_REFERENCE.md#route)
 - **Tools & Domains**: [Domain Organization](./DOMAINS.md) | [API Reference - Tools](./API_REFERENCE.md#definetool)
-- **Disambiguation**: [API Reference - Observations](./API_REFERENCE.md#observation)
 - **AI Providers**: [Providers Guide](./PROVIDERS.md) | [API Reference](./API_REFERENCE.md#geminiprovider)
 - **Database Persistence**: [Persistence Guide](./PERSISTENCE.md) | [Adapters](./ADAPTERS.md)
 - **Contributing**: [Contributing Guide](./CONTRIBUTING.md) | [Publishing Guide](./PUBLISHING.md)
@@ -72,8 +67,9 @@ Check out the [`examples/`](../examples/) directory for complete, runnable examp
 
 - **[Declarative Agent](../examples/declarative-agent.ts)** - Full constructor-based configuration
 - **[Travel Agent](../examples/travel-agent.ts)** - Complex multi-route travel booking system
-- **[Healthcare Agent](../examples/healthcare-agent.ts)** - Disambiguation with observations
+- **[Healthcare Agent](../examples/healthcare-agent.ts)** - Full example
 - **[Streaming Agent](../examples/streaming-agent.ts)** - Real-time streaming responses
+- **[Company Q&A Agent](../examples/company-qna-agent.ts)** - Stateless question-answering with knowledge base
 
 ### Persistence Examples
 
@@ -90,6 +86,7 @@ Check out the [`examples/`](../examples/) directory for complete, runnable examp
 
 - **[Domain Scoping](../examples/domain-scoping.ts)** - Control tool access per route
 - **[Rules & Prohibitions](../examples/rules-prohibitions.ts)** - Fine-grained behavior control
+- **[Extracted Data Modification](../examples/extracted-data-modification.ts)** - Tools that validate and enrich extracted data
 
 ## 🤝 Contributing