@falai/agent 0.6.7 → 0.6.9

package/README.md

@@ -2,9 +2,9 @@
 
 # 🤖 @falai/agent
 
-### Build intelligent, conversational AI agents with TypeScript
+### Type-Safe AI Conversational Agents That Actually Work in Production
 
-**Standalone • Strongly-Typed • Production-Ready**
+**Schema-driven data extraction • Predictable conversations • Enterprise-ready**
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
@@ -17,6 +17,46 @@
 
 ---
 
+## ⚡ The @falai/agent Difference
+
+### Traditional AI Chat:
+```typescript
+// User: "I want to book the Grand Hotel for 2 people"
+// AI: "Sure! Which hotel would you like?" // 😠 Asked already!
+// User: "Grand Hotel"
+// AI: "How many guests?"                 // 😠 You just told me!
+// User: "2 people"
+// AI: "What date?"                        // Finally...
+```
+
+### With @falai/agent:
+```typescript
+// User: "I want to book the Grand Hotel for 2 people"
+// AI: "Sure! For what date would you like to book?"  // ✅ Skips known info
+// User: "Next Friday"
+// AI: "Booking confirmed for 2 guests at Grand Hotel on Friday!" // ✅ All data extracted
+```
+
+**No more repetitive questions. No more guessing what the AI will ask next.**
+
+Schema-first extraction means the AI automatically captures what you've already said, and only asks for what's missing.
+
+---
+
+## 🤔 Why @falai/agent?
+
+After building production AI applications, we found existing solutions either:
+
+- **Too unpredictable** - AI decides everything, including which tools to call (unreliable in production)
+- **Too complex** - Heavy Python frameworks with massive dependencies
+- **Too basic** - No structured data extraction or state management
+
+@falai/agent gives you **predictable AI** - the creativity of LLMs with the reliability of code.
+
+**The key insight:** Let AI do what it's good at (understanding intent, generating responses, extracting data), and let TypeScript handle the rest (state logic, tool execution, validation).
+
+---
+
 ## 🌟 Features
 
 <table>
@@ -51,6 +91,7 @@
 - **Text-Based Conditions** - Human-readable transition conditions for the AI to evaluate
 - **Code-Based Logic** - Deterministic state progression with `skipIf` and `requiredData`
 - **Always-On Routing** - Context-aware routing respects user intent changes
+- **Route Transitions** - Automatic transitions between routes with `onComplete` for seamless workflows
 
 </td>
 <td width="50%">
@@ -112,7 +153,50 @@ yarn add @falai/agent
 
 ## 🚀 Quick Start
 
-Build a data-driven conversational AI agent in minutes. This example shows how to intelligently gather structured data over multiple turns.
+### Level 1: Your First Agent (30 seconds)
+
+Create a minimal conversational agent:
+
+```typescript
+import { Agent, GeminiProvider } from "@falai/agent";
+
+// Create your agent
+const agent = new Agent({
+  name: "Assistant",
+  description: "A helpful assistant",
+  ai: new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY!,
+    model: "models/gemini-2.0-flash-exp",
+  }),
+});
+
+// Create a simple route
+agent.createRoute({
+  title: "General Help",
+  description: "Answers user questions",
+  conditions: ["User needs help or asks a question"],
+  initialState: {
+    chatState: "Answer the user's question helpfully",
+  },
+});
+
+// Start chatting
+const response = await agent.respond({
+  history: [
+    { source: "customer", name: "Alice", content: "What can you do?" },
+  ],
+});
+
+console.log(response.message);
+```
+
+**That's it!** You now have a working conversational AI agent.
+
+---
+
+### Level 2: Data Extraction (The Real Power)
+
+Now let's build an agent that intelligently gathers structured data:
 
 ```typescript
 import {
@@ -168,6 +252,9 @@ const bookingRoute = agent.createRoute<HotelBookingData>({
     },
     required: ["hotelName", "date", "guests"],
   },
+  endState: {
+    chatState: "Confirm the booking details warmly and thank the user",
+  },
 });
 
 // 5️⃣ Build the flow to gather data step-by-step
@@ -243,7 +330,7 @@ for await (const chunk of agent.respondStream({ history })) {
 ```typescript
 let session = createSession<MyData>();
 const response = await agent.respond({ history, session });
-session = response.session!; // Tracks progress across turns
+session = response.session!; // Tracks progress across turns, you can use it to save the current state in your database
 ```
 
 **Database persistence** with any adapter:
@@ -282,45 +369,78 @@ const agent = new Agent({
 
 ---
 
-## 🎯 Examples
+## 🎯 Examples - Pick Your Use Case
 
-**Core Examples:**
+### 🤖 Conversational Flows
+Build intelligent data-gathering conversations:
 
-- 🏢 **[Business Onboarding](./examples/business-onboarding.ts)** - Complex multi-step flow with branching
-- ✈️ **[Travel Agent](./examples/travel-agent.ts)** - Multi-route booking system with session state
-- 🏥 **[Healthcare Assistant](./examples/healthcare-agent.ts)** - Appointment scheduling & lab results
-- 📋 **[Declarative Agent](./examples/declarative-agent.ts)** - Full constructor-based configuration
-- ⚡ **[Streaming Responses](./examples/streaming-agent.ts)** - Real-time response streaming
+- 🏢 **[Business Onboarding](./examples/business-onboarding.ts)** - Multi-step company setup with conditional branching
+- ✈️ **[Travel Agent](./examples/travel-agent.ts)** - Flight & hotel booking with session state
+- 🏥 **[Healthcare Assistant](./examples/healthcare-agent.ts)** - Appointment scheduling & lab result delivery
+
+### 🏢 Production Patterns
+Enterprise-ready features:
 
-**Persistence & Advanced:**
+- 💾 **[Prisma Persistence](./examples/prisma-persistence.ts)** - Auto-save sessions with Prisma ORM
+- ⚡ **[Redis Persistence](./examples/redis-persistence.ts)** - High-performance in-memory sessions
+- 🔐 **[Domain Scoping](./examples/domain-scoping.ts)** - Tool security & access control
 
-- 💾 **[Prisma Persistence](./examples/prisma-persistence.ts)** - Auto-save with Prisma ORM
-- ⚡ **[Redis Persistence](./examples/redis-persistence.ts)** - Fast in-memory sessions
-- 🔐 **[Domain Scoping](./examples/domain-scoping.ts)** - Tool security per route
+### ⚡ Advanced Techniques
+Power-user features:
+
+- 📋 **[Declarative Agent](./examples/declarative-agent.ts)** - Full constructor-based configuration
+- ⚡ **[Streaming Responses](./examples/streaming-agent.ts)** - Real-time response streaming
 - 📜 **[Rules & Prohibitions](./examples/rules-prohibitions.ts)** - Fine-grained behavior control
 
-📖 **[See all examples with descriptions →](./docs/EXAMPLES.md)**
+📖 **[See all examples with detailed explanations →](./docs/EXAMPLES.md)**
 
 ---
 
 ## 🏗️ How It Works
 
-`@falai/agent` uses a **state machine-driven architecture** where conversations flow through explicit states:
+`@falai/agent` uses a **schema-first, state machine-driven architecture**:
 
-1. **Router** - AI selects the best route based on conversation context
-2. **State Machine** - Routes define explicit states and transitions
-3. **Data Extraction** - JSON Schema defines data to extract during conversation
-4. **Tool Execution** - Tools run automatically when state conditions match
-5. **Message Generation** - AI generates natural responses based on current state
+```
+User Message
+    ↓
+┌─────────────────────────────────────────┐
+│ 1. PREPARATION (Tools)                  │
+│    • Execute tools for current state    │
+│    • Update context with results        │
+│    • Enrich extracted data              │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│ 2. ROUTING (AI-Driven)                  │
+│    • Evaluate all routes                │
+│    • Consider session context           │
+│    • Select best route (0-100 score)    │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│ 3. STATE SELECTION (Code + AI)          │
+│    • Filter states with skipIf (code)   │
+│    • AI picks best from valid states    │
+│    • Update session state               │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│ 4. RESPONSE (AI + Schema)               │
+│    • Extract data via JSON Schema       │
+│    • Generate natural message           │
+│    • Update session with new data       │
+└─────────────────────────────────────────┘
+    ↓
+Response with Structured Data
+```
 
-**Behind the scenes:**
+### Key Principles:
 
-- The AI only generates messages and extracts data - it never decides which tools to call
-- Tools execute deterministically based on state transitions and code-based conditions
-- Session state tracks progress and extracted data across conversation turns
-- Always-on routing lets users change direction mid-conversation
+✅ **AI decides:** Route selection, state selection (from valid options), message generation, data extraction
+✅ **Code decides:** Tool execution, state filtering (`skipIf`), data validation, flow control
+✅ **Result:** Predictable, testable agents with natural conversations
 
-This creates **predictable, testable agents** perfect for production use cases.
+**This architecture delivers 1-2 LLM calls per turn** (vs 3-5 in traditional approaches) while maintaining complete type safety.
 
 📖 **[Read the full architecture guide →](./docs/ARCHITECTURE.md)**
 
@@ -349,10 +469,22 @@ MIT © 2025
 
 <div align="center">
 
-**Made with ❤️ for the community**
+## 🚀 Ready to Build?
+
+**Choose your path:**
+
+👶 **New to AI agents?** → [5-minute tutorial](./docs/GETTING_STARTED.md)
+🏗️ **Building production app?** → [Architecture guide](./docs/ARCHITECTURE.md)
+💡 **Have questions?** → [Open a discussion](https://github.com/falai-dev/agent/discussions)
+
+---
+
+### ⭐ Star us on [GitHub](https://github.com/falai-dev/agent)
+
+**Help us reach more developers building production AI!**
 
 [Report Bug](https://github.com/falai-dev/agent/issues) • [Request Feature](https://github.com/falai-dev/agent/issues) • [Contribute](https://github.com/falai-dev/agent/pulls)
 
-⭐ Star us on [GitHub](https://github.com/falai-dev/agent) if this helped you build amazing agents!
+**Made with ❤️ for the community**
 
 </div>

package/dist/cjs/core/Agent.d.ts

@@ -175,5 +175,23 @@ export declare class Agent<TContext = unknown> {
      * @returns The extracted data from the current session
      */
     getExtractedData<TExtracted = unknown>(routeId?: string): Partial<TExtracted>;
+    /**
+     * Manually transition to a different route
+     * Sets a pending transition that will be executed on the next respond() call
+     *
+     * @param routeIdOrTitle - Route ID or title to transition to
+     * @param session - Session state to update (uses current session if not provided)
+     * @param condition - Optional AI-evaluated condition for the transition
+     * @returns Updated session with pending transition
+     *
+     * @example
+     * // After route completes
+     * if (response.isRouteComplete && response.session) {
+     *   const updatedSession = agent.transitionToRoute("feedback-collection", response.session);
+     *   // Next respond() call will automatically transition to feedback route
+     *   const nextResponse = await agent.respond({ history, session: updatedSession });
+     * }
+     */
+    transitionToRoute(routeIdOrTitle: string, session?: SessionState, condition?: string): SessionState;
 }
 //# sourceMappingURL=Agent.d.ts.map

package/dist/cjs/core/Agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}

package/dist/cjs/core/Agent.js

@@ -8,6 +8,7 @@ const session_1 = require("../types/session");
 const PromptComposer_1 = require("./PromptComposer");
 const logger_1 = require("../utils/logger");
 const Route_1 = require("./Route");
+const State_1 = require("./State");
 const DomainRegistry_1 = require("./DomainRegistry");
 const PersistenceManager_1 = require("./PersistenceManager");
 const RoutingEngine_1 = require("./RoutingEngine");
@@ -190,8 +191,7 @@ class Agent {
         };
         // Trigger lifecycle hook if configured
         if (this.options.hooks?.onExtractedUpdate) {
-            const updatedExtracted = (await this.options.hooks.onExtractedUpdate(newExtracted, previousExtracted));
-            newExtracted = updatedExtracted;
+            newExtracted = (await this.options.hooks.onExtractedUpdate(newExtracted, previousExtracted));
         }
         // Return updated session
         return (0, session_1.mergeExtracted)(session, newExtracted);
@@ -260,7 +260,34 @@ class Agent {
         let responseDirectives;
         let selectedState;
         let isRouteComplete = false;
-        if (this.routes.length > 0) {
+        // Check for pending transition from previous route completion
+        if (session.pendingTransition) {
+            const targetRoute = this.routes.find((r) => r.id === session.pendingTransition?.targetRouteId);
+            if (targetRoute) {
+                logger_1.logger.debug(`[Agent] Auto-transitioning from pending transition to route: ${targetRoute.title}`);
+                // Clear pending transition and enter new route
+                session = {
+                    ...session,
+                    pendingTransition: undefined,
+                };
+                session = (0, session_1.enterRoute)(session, targetRoute.id, targetRoute.title);
+                // Merge initial data if available
+                if (targetRoute.initialData) {
+                    session = (0, session_1.mergeExtracted)(session, targetRoute.initialData);
+                }
+                selectedRoute = targetRoute;
+            }
+            else {
+                logger_1.logger.warn(`[Agent] Pending transition target route not found: ${session.pendingTransition.targetRouteId}`);
+                // Clear invalid transition
+                session = {
+                    ...session,
+                    pendingTransition: undefined,
+                };
+            }
+        }
+        // If no pending transition or transition handled, do normal routing
+        if (this.routes.length > 0 && !selectedRoute) {
             const orchestration = await this.routingEngine.decideRouteAndState({
                 routes: this.routes,
                 session,
@@ -381,17 +408,74 @@ class Agent {
             }
         }
         else if (isRouteComplete && selectedRoute) {
-            // Route is complete - set state to END_STATE marker and yield completion signal
+            // Route is complete - generate completion message then check for onComplete transition
+            const lastUserMessage = (0, event_1.getLastMessageFromHistory)(history);
+            // Get endState spec from route
+            const endStateSpec = selectedRoute.endStateSpec;
+            // Create a temporary state for completion message generation using endState configuration
+            const completionState = new State_1.State(selectedRoute.id, endStateSpec.chatState || "Summarize what was accomplished and confirm completion", endStateSpec.id || constants_1.END_STATE_ID, endStateSpec.gather, undefined, endStateSpec.requiredData, endStateSpec.chatState || "Summarize what was accomplished and confirm completion based on the conversation history and collected data");
+            // Build response schema for completion
+            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, completionState);
+            // Build completion response prompt
+            const completionPrompt = this.responseEngine.buildResponsePrompt(selectedRoute, completionState, selectedRoute.getRules(), selectedRoute.getProhibitions(), undefined, // No directives for completion
+            history, lastUserMessage, {
+                name: this.options.name,
+                goal: this.options.goal,
+                description: this.options.description,
+                personality: this.options.personality,
+            });
+            // Stream completion message using AI provider
+            const stream = this.options.ai.generateMessageStream({
+                prompt: completionPrompt,
+                history,
+                context: effectiveContext,
+                signal,
+                parameters: {
+                    jsonSchema: responseSchema,
+                    schemaName: "completion_message_stream",
+                },
+            });
+            logger_1.logger.debug(`[Agent] Streaming completion message for route: ${selectedRoute.title}`);
+            // Check for onComplete transition
+            const transitionConfig = await selectedRoute.evaluateOnComplete({ extracted: session.extracted }, effectiveContext);
+            if (transitionConfig) {
+                // Find target route by ID or title
+                const targetRoute = this.routes.find((r) => r.id === transitionConfig.transitionTo ||
+                    r.title === transitionConfig.transitionTo);
+                if (targetRoute) {
+                    // Set pending transition in session
+                    session = {
+                        ...session,
+                        pendingTransition: {
+                            targetRouteId: targetRoute.id,
+                            condition: transitionConfig.condition,
+                            reason: "route_complete",
+                        },
+                    };
+                    logger_1.logger.debug(`[Agent] Route ${selectedRoute.title} completed with pending transition to: ${targetRoute.title}`);
+                }
+                else {
+                    logger_1.logger.warn(`[Agent] Route ${selectedRoute.title} completed but target route not found: ${transitionConfig.transitionTo}`);
+                }
+            }
+            // Set state to END_STATE marker
             session = (0, session_1.enterState)(session, constants_1.END_STATE_ID, "Route completed");
             logger_1.logger.debug(`[Agent] Route ${selectedRoute.title} completed. Entered END_STATE state.`);
-            yield {
-                delta: "",
-                accumulated: "",
-                done: true,
-                session,
-                toolCalls: undefined,
-                isRouteComplete: true,
-            };
+            // Stream completion chunks
+            for await (const chunk of stream) {
+                // Update current session if we have one
+                if (chunk.done && this.currentSession) {
+                    this.currentSession = session;
+                }
+                yield {
+                    delta: chunk.delta,
+                    accumulated: chunk.accumulated,
+                    done: chunk.done,
+                    session,
+                    toolCalls: undefined,
+                    isRouteComplete: true,
+                };
+            }
         }
         else {
             // Fallback: No routes defined, stream a simple response
@@ -492,7 +576,34 @@ class Agent {
         let responseDirectives;
         let selectedState;
         let isRouteComplete = false;
-        if (this.routes.length > 0) {
+        // Check for pending transition from previous route completion
+        if (session.pendingTransition) {
+            const targetRoute = this.routes.find((r) => r.id === session.pendingTransition?.targetRouteId);
+            if (targetRoute) {
+                logger_1.logger.debug(`[Agent] Auto-transitioning from pending transition to route: ${targetRoute.title}`);
+                // Clear pending transition and enter new route
+                session = {
+                    ...session,
+                    pendingTransition: undefined,
+                };
+                session = (0, session_1.enterRoute)(session, targetRoute.id, targetRoute.title);
+                // Merge initial data if available
+                if (targetRoute.initialData) {
+                    session = (0, session_1.mergeExtracted)(session, targetRoute.initialData);
+                }
+                selectedRoute = targetRoute;
+            }
+            else {
+                logger_1.logger.warn(`[Agent] Pending transition target route not found: ${session.pendingTransition.targetRouteId}`);
+                // Clear invalid transition
+                session = {
+                    ...session,
+                    pendingTransition: undefined,
+                };
+            }
+        }
+        // If no pending transition or transition handled, do normal routing
+        if (this.routes.length > 0 && !selectedRoute) {
             const orchestration = await this.routingEngine.decideRouteAndState({
                 routes: this.routes,
                 session,
@@ -591,9 +702,59 @@ class Agent {
             }
         }
         else if (isRouteComplete && selectedRoute) {
-            // Route is complete - set state to END_STATE marker and return completion signal
+            // Route is complete - generate completion message then check for onComplete transition
+            const lastUserMessage = (0, event_1.getLastMessageFromHistory)(history);
+            // Get endState spec from route
+            const endStateSpec = selectedRoute.endStateSpec;
+            // Create a temporary state for completion message generation using endState configuration
+            const completionState = new State_1.State(selectedRoute.id, endStateSpec.chatState || "Summarize what was accomplished and confirm completion", endStateSpec.id || constants_1.END_STATE_ID, endStateSpec.gather, undefined, endStateSpec.requiredData, endStateSpec.chatState || "Summarize what was accomplished and confirm completion based on the conversation history and collected data");
+            // Build response schema for completion
+            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, completionState);
+            // Build completion response prompt
+            const completionPrompt = this.responseEngine.buildResponsePrompt(selectedRoute, completionState, selectedRoute.getRules(), selectedRoute.getProhibitions(), undefined, // No directives for completion
+            history, lastUserMessage, {
+                name: this.options.name,
+                goal: this.options.goal,
+                description: this.options.description,
+                personality: this.options.personality,
+            });
+            // Generate completion message using AI provider
+            const completionResult = await this.options.ai.generateMessage({
+                prompt: completionPrompt,
+                history,
+                context: effectiveContext,
+                signal,
+                parameters: {
+                    jsonSchema: responseSchema,
+                    schemaName: "completion_message",
+                },
+            });
+            message = completionResult.structured?.message || completionResult.message;
+            logger_1.logger.debug(`[Agent] Generated completion message for route: ${selectedRoute.title}`);
+            // Check for onComplete transition
+            const transitionConfig = await selectedRoute.evaluateOnComplete({ extracted: session.extracted }, effectiveContext);
+            if (transitionConfig) {
+                // Find target route by ID or title
+                const targetRoute = this.routes.find((r) => r.id === transitionConfig.transitionTo ||
+                    r.title === transitionConfig.transitionTo);
+                if (targetRoute) {
+                    // Set pending transition in session
+                    session = {
+                        ...session,
+                        pendingTransition: {
+                            targetRouteId: targetRoute.id,
+                            condition: transitionConfig.condition,
+                            reason: "route_complete",
+                        },
+                    };
+                    logger_1.logger.debug(`[Agent] Route ${selectedRoute.title} completed with pending transition to: ${targetRoute.title}`);
+                }
+                else {
+                    logger_1.logger.warn(`[Agent] Route ${selectedRoute.title} completed but target route not found: ${transitionConfig.transitionTo}`);
+                }
+            }
+            // Set state to END_STATE marker
             session = (0, session_1.enterState)(session, constants_1.END_STATE_ID, "Route completed");
-            message = "";
             logger_1.logger.debug(`[Agent] Route ${selectedRoute.title} completed. Entered END_STATE state.`);
         }
         else {
@@ -750,6 +911,48 @@ class Agent {
         }
         return this.currentSession.extracted || {};
     }
+    /**
+     * Manually transition to a different route
+     * Sets a pending transition that will be executed on the next respond() call
+     *
+     * @param routeIdOrTitle - Route ID or title to transition to
+     * @param session - Session state to update (uses current session if not provided)
+     * @param condition - Optional AI-evaluated condition for the transition
+     * @returns Updated session with pending transition
+     *
+     * @example
+     * // After route completes
+     * if (response.isRouteComplete && response.session) {
+     *   const updatedSession = agent.transitionToRoute("feedback-collection", response.session);
+     *   // Next respond() call will automatically transition to feedback route
+     *   const nextResponse = await agent.respond({ history, session: updatedSession });
+     * }
+     */
+    transitionToRoute(routeIdOrTitle, session, condition) {
+        const targetSession = session || this.currentSession;
+        if (!targetSession) {
+            throw new Error("No session provided and no current session available. Please provide a session to transition.");
+        }
+        // Find target route by ID or title
+        const targetRoute = this.routes.find((r) => r.id === routeIdOrTitle || r.title === routeIdOrTitle);
+        if (!targetRoute) {
+            throw new Error(`Route not found: ${routeIdOrTitle}. Available routes: ${this.routes.map((r) => r.title).join(", ")}`);
+        }
+        const updatedSession = {
+            ...targetSession,
+            pendingTransition: {
+                targetRouteId: targetRoute.id,
+                condition,
+                reason: "manual",
+            },
+        };
+        // Update current session if using it
+        if (!session && this.currentSession) {
+            this.currentSession = updatedSession;
+        }
+        logger_1.logger.debug(`[Agent] Set pending manual transition to route: ${targetRoute.title}`);
+        return updatedSession;
+    }
 }
 exports.Agent = Agent;
 //# sourceMappingURL=Agent.js.map