@falai/agent 0.5.5 → 0.6.1

package/dist/types/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,UAAU,GAAG,OAAO;IAChD,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,gBAAgB,CAAC;IACvC,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,gBAAgB,CAAC;IACxC;;;OAGG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;IACtE,2FAA2F;IAC3F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IAEnC,SAAS,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1C,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC;IACrD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO,CACxE,SAAQ,QAAQ;IAChB,iCAAiC;IACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,EAC1C,SAAS,CAAC,EAAE,MAAM,KACf,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;CAC7C"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,UAAU,GAAG,OAAO;IAChD,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,gBAAgB,CAAC;IACvC,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,gBAAgB,CAAC;IACxC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAClC;;;;OAIG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;IACtE,2FAA2F;IAC3F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IAEnC,SAAS,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1C,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC;IACrD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO,CACxE,SAAQ,QAAQ;IAChB,iCAAiC;IACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,KACvC,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;CAC7C"}

package/docs/ADAPTERS.md

@@ -4,6 +4,18 @@ All adapters follow the **provider pattern** - no dependencies required in the p
 
 **NEW**: All adapters now support the new **Session State** pattern with automatic persistence of extracted data, current route/state, and conversation progress!
 
+### 🎯 Available Adapters
+
+| Adapter               | Use Case                           | Install                                      |
+| --------------------- | ---------------------------------- | -------------------------------------------- |
+| **PrismaAdapter**     | Type-safe ORM with migrations      | `npm install @prisma/client`                 |
+| **RedisAdapter**      | Fast in-memory for real-time apps  | `npm install ioredis`                        |
+| **MongoAdapter**      | Flexible document storage          | `npm install mongodb`                        |
+| **PostgreSQLAdapter** | Raw SQL with auto table creation   | `npm install pg`                             |
+| **SQLiteAdapter**     | Lightweight local database         | `npm install better-sqlite3`                 |
+| **OpenSearchAdapter** | Full-text search & analytics       | `npm install @opensearch-project/opensearch` |
+| **MemoryAdapter**     | Testing & development (no install) | Built-in (no dependencies) ✨                |
+
 ## ✅ Implemented Adapters
 
 ### 1. **PrismaAdapter**
@@ -102,7 +114,7 @@ const agent = new Agent({
 // Create a route with data extraction
 const route = agent.createRoute<YourDataType>({
   title: "My Route",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       field1: { type: "string" },

package/docs/API_REFERENCE.md

@@ -321,7 +321,7 @@ interface RouteOptions<TExtracted = unknown> {
   prohibitions?: string[];  // Absolute prohibitions the agent MUST NEVER do in this route
 
   // NEW: Schema-first data extraction
-  gatherSchema?: {
+  extractionSchema?: {
     type: "object";
     properties: Record<string, any>;
     required?: string[];
@@ -395,7 +395,7 @@ Represents a state within a conversation route.
 
 #### Methods
 
-##### `transitionTo(spec: TransitionSpec, condition?: string): TransitionResult`
+##### `transitionTo(spec: TransitionSpec): TransitionResult`
 
 Creates a transition from this state and returns a chainable result.
 
@@ -413,22 +413,23 @@ interface TransitionSpec<TExtracted = unknown> {
 
   // NEW: Prerequisites that must be met to enter this state
   requiredData?: string[];
+
+  // Optional: AI-evaluated text condition for this transition
+  condition?: string;
 }
 
 interface TransitionResult<TExtracted = unknown> {
   id: string; // State identifier
   routeId: string; // Route identifier
   transitionTo: (
-    spec: TransitionSpec<TExtracted>,
-    condition?: string // Optional: AI-evaluated text condition for this transition
+    spec: TransitionSpec<TExtracted>
   ) => TransitionResult<TExtracted>;
 }
 ```
 
 **Parameters:**
 
-- `spec`: The transition specification (see `TransitionSpec` above)
-- `condition` (optional): Human-readable condition text that the AI evaluates when selecting states. Use this to guide the AI's state selection based on conversation context. Examples: "Customer confirmed payment", "All required data collected", "User wants to modify order"
+- `spec`: The transition specification (see `TransitionSpec` above). Can include an optional `condition` property for AI-evaluated state selection guidance.
 
 **Returns:** A `TransitionResult` that includes the target state's reference (`id`, `routeId`) and a `transitionTo` method for chaining additional transitions.
 
@@ -445,7 +446,7 @@ interface FlightData {
 // Create a data-driven route
 const flightRoute = agent.createRoute<FlightData>({
   title: "Book Flight",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },
@@ -457,24 +458,20 @@ const flightRoute = agent.createRoute<FlightData>({
 });
 
 // Approach 1: Step-by-step with data extraction and text conditions
-const askDestination = flightRoute.initialState.transitionTo(
-  {
-    chatState: "Ask where they want to fly",
-    gather: ["destination"],
-    skipIf: (extracted) => !!extracted.destination, // Skip if already have destination
-  },
-  "Customer hasn't specified destination yet" // AI-evaluated condition
-);
+const askDestination = flightRoute.initialState.transitionTo({
+  chatState: "Ask where they want to fly",
+  gather: ["destination"],
+  skipIf: (extracted) => !!extracted.destination, // Skip if already have destination
+  condition: "Customer hasn't specified destination yet", // AI-evaluated condition
+});
 
-const askDates = askDestination.transitionTo(
-  {
-    chatState: "Ask about travel dates",
-    gather: ["departureDate"],
-    skipIf: (extracted) => !!extracted.departureDate,
-    requiredData: ["destination"], // Must have destination first
-  },
-  "Destination confirmed, need travel dates"
-);
+const askDates = askDestination.transitionTo({
+  chatState: "Ask about travel dates",
+  gather: ["departureDate"],
+  skipIf: (extracted) => !!extracted.departureDate,
+  requiredData: ["destination"], // Must have destination first
+  condition: "Destination confirmed, need travel dates",
+});
 
 const askPassengers = askDates.transitionTo({
   chatState: "How many passengers?",
@@ -1557,7 +1554,7 @@ interface SessionState<TExtracted = Record<string, unknown>> {
 **Key Features:**
 
 - **`id`** - Optional session identifier that persists across database operations
-- **`extracted`** - Type-safe data collected via `gatherSchema`
+- **`extracted`** - Type-safe data collected via `extractionSchema`
 - **`currentRoute`** / **`currentState`** - Track conversation position
 - **`routeHistory`** - Full audit trail of route transitions
 - **`metadata`** - Custom data (timestamps, user info, etc.)

package/docs/ARCHITECTURE.md

@@ -22,7 +22,7 @@ interface FlightData {
 const route = agent.createRoute<FlightData>({
   title: "Book Flight",
   description: "Help user book a flight",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },
@@ -112,26 +112,22 @@ Use TypeScript functions for deterministic flow control AND text conditions for
 
 ```typescript
 // State with smart bypassing based on extracted data
-const askDestination = route.initialState.transitionTo(
-  {
-    id: "ask_destination", // Optional: custom state ID
-    chatState: "Ask where they want to fly",
-    gather: ["destination"],
-    skipIf: (extracted) => !!extracted.destination, // Code-based condition!
-  },
-  "Customer hasn't specified destination yet" // Text condition for AI
-);
+const askDestination = route.initialState.transitionTo({
+  id: "ask_destination", // Optional: custom state ID
+  chatState: "Ask where they want to fly",
+  gather: ["destination"],
+  skipIf: (extracted) => !!extracted.destination, // Code-based condition!
+  condition: "Customer hasn't specified destination yet", // Text condition for AI
+});
 
-const askDate = askDestination.transitionTo(
-  {
-    id: "ask_date", // Optional: custom state ID for easier tracking
-    chatState: "Ask about travel dates",
-    gather: ["departureDate"],
-    skipIf: (extracted) => !!extracted.departureDate,
-    requiredData: ["destination"], // Prerequisites
-  },
-  "Destination confirmed, need travel dates now"
-);
+const askDate = askDestination.transitionTo({
+  id: "ask_date", // Optional: custom state ID for easier tracking
+  chatState: "Ask about travel dates",
+  gather: ["departureDate"],
+  skipIf: (extracted) => !!extracted.departureDate,
+  requiredData: ["destination"], // Prerequisites
+  condition: "Destination confirmed, need travel dates now",
+});
 });
 ```
 
@@ -374,7 +370,7 @@ interface BookingData {
 
 const bookingRoute = agent.createRoute<BookingData>({
   title: "Flight Booking",
-  gatherSchema: {
+  extractionSchema: {
     /* schema for all fields */
   },
 });
@@ -404,7 +400,7 @@ For simple question-answering without state:
 const qnaRoute = agent.createRoute({
   title: "Company Q&A",
   conditions: ["User asks about company"],
-  // NO gatherSchema - stateless!
+  // NO extractionSchema - stateless!
 });
 
 // Just use initial state

package/docs/CONSTRUCTOR_OPTIONS.md

@@ -103,7 +103,7 @@ const agent = new Agent<FlightBookingContext>({
       title: 'Book Flight',
       description: 'Help user book a flight',
       conditions: ['User wants to book a flight'],
-      gatherSchema: {
+      extractionSchema: {
         type: 'object',
         properties: {
           destination: { type: 'string' },
@@ -175,7 +175,7 @@ interface RouteOptions<TExtracted = unknown> {
   prohibitions?: string[];  // Absolute prohibitions the agent MUST NEVER do
 
   // NEW: Schema-first data extraction
-  gatherSchema?: {
+  extractionSchema?: {
     type: "object";
     properties: Record<string, any>;
     required?: string[];

package/docs/CONTEXT_MANAGEMENT.md

@@ -182,7 +182,7 @@ interface FlightData {
 
 const route = agent.createRoute<FlightData>({
   title: "Book Flight",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },

package/docs/EXAMPLES.md

@@ -0,0 +1,419 @@
+# Examples
+
+This directory contains production-ready examples demonstrating all features of `@falai/agent`.
+
+## 🚀 Getting Started Examples
+
+### 📋 [Declarative Agent](../examples/declarative-agent.ts)
+
+**Perfect for:** Learning the full configuration API
+
+Comprehensive example showing declarative agent configuration:
+
+- ✅ Full constructor-based setup
+- ✅ Terms, guidelines, capabilities, routes defined upfront
+- ✅ Session state management with data extraction
+- ✅ Custom IDs for routes, states, and tools
+- ✅ Dynamic additions after construction
+
+**Key concepts:** Declarative configuration, session state, data extraction schemas
+
+```typescript
+const agent = new Agent({
+  name: "HealthBot",
+  ai: provider,
+  terms: [...],
+  guidelines: [...],
+  routes: [{
+    extractionSchema: { /* JSON Schema */ }
+  }]
+});
+```
+
+---
+
+## 🏢 Real-World Applications
+
+### 🏢 [Business Onboarding](../examples/business-onboarding.ts)
+
+**Perfect for:** Building complex multi-step workflows
+
+Production-ready business onboarding with advanced patterns:
+
+- ✅ Multi-step data collection flow
+- ✅ Branching logic (physical vs online business)
+- ✅ Tools with `contextUpdate` for automatic state management
+- ✅ Both step-by-step and fluent chaining approaches
+- ✅ Lifecycle hooks for persistence
+- ✅ Dynamic route creation based on collected data
+
+**Key concepts:** Complex flows, branching logic, context updates, lifecycle hooks
+
+```typescript
+// Branching based on business type
+const askPhysicalLocation = askLocation.transitionTo({
+  chatState: "Get physical store address",
+  condition: "User has a physical store",
+});
+
+const askOnlineLocation = askLocation.transitionTo({
+  chatState: "Get website and online support hours",
+  condition: "User does not have a physical store",
+});
+```
+
+### ✈️ [Travel Agent](../examples/travel-agent.ts)
+
+**Perfect for:** Multi-route systems with session state
+
+Complete travel booking system featuring:
+
+- ✅ Multi-step flight booking flow
+- ✅ Data extraction with JSON Schema
+- ✅ Session state tracking across turns
+- ✅ Tools with data access via `extracted` context
+- ✅ Alternative flow handling (booking vs status check)
+- ✅ Route-specific guidelines
+
+**Key concepts:** Session state, data extraction, multiple routes, tool data access
+
+```typescript
+const searchFlights = defineTool(
+  "search_flights",
+  async ({ context, extracted }) => {
+    // Tool has access to extracted booking data
+    if (!extracted?.destination || !extracted?.departureDate) {
+      return { data: [] };
+    }
+    // Use extracted data to search
+    const flights = await searchAPI(extracted);
+    return { data: flights };
+  }
+);
+```
+
+### 🏥 [Healthcare Assistant](../examples/healthcare-agent.ts)
+
+**Perfect for:** Sensitive data handling and compliance
+
+Healthcare-focused agent demonstrating:
+
+- ✅ Appointment scheduling with validation
+- ✅ Lab results retrieval
+- ✅ Route-based disambiguation with conditions
+- ✅ Sensitive data handling best practices
+- ✅ Urgent case prioritization
+- ✅ HIPAA-style security patterns
+
+**Key concepts:** Data security, route disambiguation, validation, compliance
+
+---
+
+## ⚡ Advanced Features
+
+### ⚡ [Streaming Responses](../examples/streaming-agent.ts)
+
+**Perfect for:** Real-time UX and better perceived performance
+
+Real-time streaming responses:
+
+- ✅ Stream responses from all providers (Anthropic, OpenAI, Gemini, OpenRouter)
+- ✅ Real-time text generation with `respondStream`
+- ✅ Cancellable streams with AbortSignal
+- ✅ Access route, state, and tool information in final chunk
+- ✅ 5 comprehensive examples covering different use cases
+
+**Key concepts:** Streaming, real-time UX, cancellation
+
+```typescript
+for await (const chunk of agent.respondStream({ history })) {
+  process.stdout.write(chunk.delta);
+
+  if (chunk.done) {
+    console.log("Route:", chunk.route?.title);
+    console.log("Extracted:", chunk.extracted);
+  }
+}
+```
+
+### 🔐 [Domain Scoping](../examples/domain-scoping.ts)
+
+**Perfect for:** Security-conscious applications
+
+Control tool access per route for security:
+
+- ✅ Organize tools into security domains
+- ✅ Restrict which tools each route can use
+- ✅ Prevent unauthorized tool calls
+- ✅ Improve AI performance by reducing decision space
+- ✅ Clear documentation of route capabilities
+
+**Key concepts:** Security, tool isolation, domain organization
+
+```typescript
+agent.addDomain("payment", { processPayment, refund });
+agent.addDomain("user", { updateProfile, sendEmail });
+
+// Checkout route can ONLY use payment tools
+agent.createRoute({
+  title: "Checkout",
+  domains: ["payment"], // ← Security boundary
+});
+```
+
+### 📜 [Rules & Prohibitions](../examples/rules-prohibitions.ts)
+
+**Perfect for:** Multi-channel bots with different styles
+
+Control agent behavior and communication style per route:
+
+- ✅ Define absolute rules the agent must follow
+- ✅ Set prohibitions for what agent must never do
+- ✅ Different communication styles per route
+- ✅ Perfect for multi-channel bots (WhatsApp, email, chat)
+- ✅ Automatic enforcement without manual checking
+
+**Key concepts:** Behavior control, tone management, channel-specific styling
+
+```typescript
+agent.createRoute({
+  title: "WhatsApp Support",
+  rules: ["Keep messages under 2 lines", "Use max 1 emoji"],
+  prohibitions: ["Never send long paragraphs", "Don't over-explain"],
+});
+
+agent.createRoute({
+  title: "Email Support",
+  rules: ["Use professional tone", "Include clear next steps"],
+  prohibitions: ["No emojis", "Avoid slang"],
+});
+```
+
+---
+
+## 💾 Persistence Examples
+
+### 💾 [Prisma Persistence](../examples/prisma-persistence.ts)
+
+**Perfect for:** Production apps with relational databases
+
+Auto-save sessions and messages with Prisma ORM:
+
+- ✅ Provider pattern - simple as `new PrismaAdapter({ prisma })`
+- ✅ Automatic session and message persistence
+- ✅ Seamless lifecycle hook integration
+- ✅ Type-safe database operations
+- ✅ 3-step setup guide
+
+**Key concepts:** Database persistence, Prisma ORM, auto-save
+
+```typescript
+const agent = new Agent({
+  persistence: {
+    adapter: new PrismaAdapter({ prisma }),
+    autoSave: true,
+    userId: "user_123",
+  },
+});
+```
+
+### ⚡ [Redis Persistence](../examples/redis-persistence.ts)
+
+**Perfect for:** High-throughput real-time applications
+
+Fast, in-memory persistence:
+
+- ✅ Lightning-fast session storage
+- ✅ Configurable TTLs for auto-cleanup
+- ✅ Custom key prefixes
+- ✅ Perfect for real-time chat applications
+- ✅ Simple setup with ioredis
+
+**Key concepts:** In-memory persistence, Redis, TTL management
+
+### 🔍 [OpenSearch Persistence](../examples/opensearch-persistence.ts)
+
+**Perfect for:** Analytics and full-text search requirements
+
+Full-text search and analytics-powered persistence:
+
+- ✅ Built-in full-text search across all messages
+- ✅ Powerful aggregations and analytics
+- ✅ Compatible with Elasticsearch 7.x
+- ✅ AWS OpenSearch Service ready
+- ✅ Index management and optimization
+
+**Key concepts:** Search, analytics, OpenSearch, Elasticsearch
+
+### 🗄️ [Custom Database Integration](../examples/custom-database-persistence.ts)
+
+**Perfect for:** Integrating with existing database schemas
+
+Manual session state management for existing schemas:
+
+- ✅ Full control over database operations
+- ✅ Works with any database (no adapter needed)
+- ✅ Manual session state save/restore
+- ✅ Perfect for integrating with existing schemas
+- ✅ Complete example with validation hooks
+
+**Key concepts:** Custom persistence, existing schemas, manual control
+
+---
+
+## 🔧 Context & State Management
+
+### 💾 [Persistent Onboarding Agent](../examples/persistent-onboarding.ts)
+
+**Perfect for:** Multi-turn conversations with persistence
+
+Multi-turn conversation with state persistence:
+
+- ✅ Context lifecycle hooks for database integration
+- ✅ Automatic persistence on context updates
+- ✅ Factory pattern for agent creation
+- ✅ Two approaches: lifecycle hooks vs context provider
+- ✅ Complete onboarding flow across multiple turns
+
+**Key concepts:** Context lifecycle, multi-turn conversations, factory pattern
+
+```typescript
+const agent = new Agent({
+  hooks: {
+    beforeRespond: async (context) => {
+      return await database.loadContext(sessionId);
+    },
+    onContextUpdate: async (newContext) => {
+      await database.saveContext(sessionId, newContext);
+    },
+  },
+});
+```
+
+### 🔄 [Extracted Data Modification](../examples/extracted-data-modification.ts)
+
+**Perfect for:** Data validation and enrichment
+
+Tools that validate and enrich extracted data:
+
+- ✅ Tools can modify extracted data with `extractedUpdate`
+- ✅ Data validation and enrichment patterns
+- ✅ Flag-based conditional execution
+- ✅ Error handling and data correction
+- ✅ Multi-step data refinement
+
+**Key concepts:** Data validation, enrichment, extractedUpdate, flags
+
+```typescript
+const validateEmail = defineTool(
+  "validate_email",
+  async ({ extracted }) => {
+    const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(extracted.email);
+    return {
+      data: isValid,
+      extractedUpdate: {
+        emailValid: isValid, // Enrich extracted data
+      },
+    };
+  }
+);
+```
+
+---
+
+## 🤖 Provider Examples
+
+### 🌐 [OpenAI Agent](../examples/openai-agent.ts)
+
+**Perfect for:** Using GPT models
+
+GPT-5 integration with backup models:
+
+- ✅ OpenAI provider configuration
+- ✅ Backup model fallback
+- ✅ Retry configuration
+- ✅ Weather checking example
+
+**Key concepts:** OpenAI integration, model fallback
+
+### 🌐 Multiple Providers
+
+See how different AI providers work:
+
+- **[OpenAI Agent](../examples/openai-agent.ts)** - GPT-5 integration
+- **[Healthcare Agent](../examples/healthcare-agent.ts)** - Claude 3.5 Sonnet (Anthropic)
+- **[Travel Agent](../examples/travel-agent.ts)** - OpenRouter with backup models
+- All examples include backup model configuration and retry settings
+
+---
+
+## 📚 Additional Examples
+
+### 📊 [Company Q&A Agent](../examples/company-qna-agent.ts)
+
+**Perfect for:** Stateless question-answering systems
+
+Simple Q&A agent with knowledge base:
+
+- ✅ Stateless routes (no data extraction)
+- ✅ Knowledge base integration
+- ✅ Simple request-response pattern
+- ✅ Perfect for FAQ bots
+
+**Key concepts:** Stateless routing, Q&A patterns
+
+---
+
+## 🎯 How to Use These Examples
+
+### Running Examples
+
+```bash
+# Install dependencies
+bun install
+
+# Set up environment variables
+echo "GEMINI_API_KEY=your_key" > .env
+
+# Run an example
+bun examples/travel-agent.ts
+```
+
+### Learning Path
+
+1. **Start here:** [Declarative Agent](../examples/declarative-agent.ts) - Learn the basics
+2. **Simple flow:** [Travel Agent](../examples/travel-agent.ts) - Session state & extraction
+3. **Complex flow:** [Business Onboarding](../examples/business-onboarding.ts) - Branching & lifecycle
+4. **Add persistence:** [Prisma Persistence](../examples/prisma-persistence.ts) - Database integration
+5. **Add security:** [Domain Scoping](../examples/domain-scoping.ts) - Tool isolation
+
+### Quick Reference
+
+| Example | Best For | Key Features |
+|---------|----------|--------------|
+| Declarative Agent | Learning basics | Full API coverage |
+| Travel Agent | Session state | Multi-turn conversations |
+| Business Onboarding | Complex flows | Branching, lifecycle hooks |
+| Healthcare Agent | Security | Data validation, compliance |
+| Streaming Agent | Real-time UX | Streaming responses |
+| Domain Scoping | Security | Tool isolation |
+| Prisma Persistence | Production | Database integration |
+
+---
+
+## 💡 Tips
+
+**For Production:**
+- Use [Prisma Persistence](../examples/prisma-persistence.ts) for relational data
+- Use [Redis Persistence](../examples/redis-persistence.ts) for high-throughput
+- Implement [Domain Scoping](../examples/domain-scoping.ts) for security
+- Add [Rules & Prohibitions](../examples/rules-prohibitions.ts) for brand consistency
+
+**For Development:**
+- Start with [Declarative Agent](../examples/declarative-agent.ts)
+- Use [Streaming Agent](../examples/streaming-agent.ts) for better UX
+- Check [Custom Database Integration](../examples/custom-database-persistence.ts) for existing schemas
+
+---
+
+**Need help?** Check the [full documentation](./README.md) or [open an issue](https://github.com/gusnips/falai/issues).

package/docs/GETTING_STARTED.md

@@ -86,7 +86,7 @@ const bookingRoute = agent.createRoute<FlightData>({
   title: "Book Flight",
   description: "Help user book a flight",
   conditions: ["User wants to book a flight"],
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },