@falai/agent 0.6.8 → 0.7.0

package/docs/EXAMPLES.md

@@ -13,9 +13,9 @@ Complete example demonstrating the new `onComplete` feature for seamless route t
 - ✅ Hotel booking flow transitioning to feedback collection
 - ✅ Three ways to define transitions (string, config, function)
 - ✅ Automatic transition after route completion
-- ✅ Manual transition control with `agent.transitionToRoute()`
-- ✅ Dynamic logic based on extracted data
-- ✅ Pending transition tracking in session state
+- ✅ Manual transition control with `agent.nextStepRoute()`
+- ✅ Dynamic logic based on collected data
+- ✅ Pending transition tracking in session step
 
 **Key concepts:** Route transitions, workflow chaining, feedback collection, onComplete handlers
 
@@ -27,13 +27,13 @@ const bookingRoute = agent.createRoute<BookingData>({
 
   // Or with AI condition:
   // onComplete: {
-  //   transitionTo: "Collect Feedback",
+  //   nextStep: "Collect Feedback",
   //   condition: "if booking was successful"
   // },
 
   // Or with function logic:
   // onComplete: (session) => {
-  //   if (session.extracted?.guests > 5) {
+  //   if (session.data?.guests > 5) {
   //     return "VIP Feedback";
   //   }
   //   return "Collect Feedback";
@@ -43,7 +43,7 @@ const bookingRoute = agent.createRoute<BookingData>({
 // Feedback route automatically triggered after booking
 const feedbackRoute = agent.createRoute<FeedbackData>({
   title: "Collect Feedback",
-  // ... states for collecting rating and comments
+  // ... steps for collecting rating and comments
 });
 ```
 
@@ -59,11 +59,11 @@ 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
+- ✅ Session step management with data extraction
+- ✅ Custom IDs for routes, steps, and tools
 - ✅ Dynamic additions after construction
 
-**Key concepts:** Declarative configuration, session state, data extraction schemas
+**Key concepts:** Declarative configuration, session step, data extraction schemas
 
 ```typescript
 const agent = new Agent({
@@ -72,7 +72,7 @@ const agent = new Agent({
   terms: [...],
   guidelines: [...],
   routes: [{
-    extractionSchema: { /* JSON Schema */ }
+    schema: { /* JSON Schema */ }
   }]
 });
 ```
@@ -89,7 +89,7 @@ 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
+- ✅ Tools with `contextUpdate` for automatic step management
 - ✅ Both step-by-step and fluent chaining approaches
 - ✅ Lifecycle hooks for persistence
 - ✅ Dynamic route creation based on collected data
@@ -98,43 +98,43 @@ Production-ready business onboarding with advanced patterns:
 
 ```typescript
 // Branching based on business type
-const askPhysicalLocation = askLocation.transitionTo({
-  chatState: "Get physical store address",
+const askPhysicalLocation = askLocation.nextStep({
+  instructions: "Get physical store address",
   condition: "User has a physical store",
 });
 
-const askOnlineLocation = askLocation.transitionTo({
-  chatState: "Get website and online support hours",
+const askOnlineLocation = askLocation.nextStep({
+  instructions: "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
+**Perfect for:** Multi-route systems with session step
 
 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
+- ✅ Session step tracking across turns
+- ✅ Tools with data access via `data` context
 - ✅ Alternative flow handling (booking vs status check)
 - ✅ Route-specific guidelines
 - ✅ **NEW:** Automatic feedback collection after booking with `onComplete`
 
-**Key concepts:** Session state, data extraction, multiple routes, tool data access, route transitions
+**Key concepts:** Session step, data extraction, multiple routes, tool data access, route transitions
 
 ```typescript
 const searchFlights = defineTool(
   "search_flights",
-  async ({ context, extracted }) => {
-    // Tool has access to extracted booking data
-    if (!extracted?.destination || !extracted?.departureDate) {
+  async ({ context, data }) => {
+    // Tool has access to data booking data
+    if (!data?.destination || !data?.departureDate) {
       return { data: [] };
     }
-    // Use extracted data to search
-    const flights = await searchAPI(extracted);
+    // Use collected data to search
+    const flights = await searchAPI(data);
     return { data: flights };
   }
 );
@@ -169,7 +169,7 @@ 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
+- ✅ Access route, step, and tool information in final chunk
 - ✅ 5 comprehensive examples covering different use cases
 
 **Key concepts:** Streaming, real-time UX, cancellation
@@ -180,7 +180,7 @@ for await (const chunk of agent.respondStream({ history })) {
 
   if (chunk.done) {
     console.log("Route:", chunk.route?.title);
-    console.log("Extracted:", chunk.extracted);
+    console.log("Data:", chunk.data);
   }
 }
 ```
@@ -298,11 +298,11 @@ Full-text search and analytics-powered persistence:
 
 **Perfect for:** Integrating with existing database schemas
 
-Manual session state management for existing schemas:
+Manual session step management for existing schemas:
 
 - ✅ Full control over database operations
 - ✅ Works with any database (no adapter needed)
-- ✅ Manual session state save/restore
+- ✅ Manual session step save/restore
 - ✅ Perfect for integrating with existing schemas
 - ✅ Complete example with validation hooks
 
@@ -310,13 +310,13 @@ Manual session state management for existing schemas:
 
 ---
 
-## 🔧 Context & State Management
+## 🔧 Context & Step Management
 
 ### 💾 [Persistent Onboarding Agent](../examples/persistent-onboarding.ts)
 
 **Perfect for:** Multi-turn conversations with persistence
 
-Multi-turn conversation with state persistence:
+Multi-turn conversation with step persistence:
 
 - ✅ Context lifecycle hooks for database integration
 - ✅ Automatic persistence on context updates
@@ -339,27 +339,27 @@ const agent = new Agent({
 });
 ```
 
-### 🔄 [Extracted Data Modification](../examples/extracted-data-modification.ts)
+### 🔄 [Collected data Modification](../examples/data-data-modification.ts)
 
 **Perfect for:** Data validation and enrichment
 
-Tools that validate and enrich extracted data:
+Tools that validate and enrich collected data:
 
-- ✅ Tools can modify extracted data with `extractedUpdate`
+- ✅ Tools can modify collected data with `dataUpdate`
 - ✅ 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
+**Key concepts:** Data validation, enrichment, dataUpdate, flags
 
 ```typescript
-const validateEmail = defineTool("validate_email", async ({ extracted }) => {
-  const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(extracted.email);
+const validateEmail = defineTool("validate_email", async ({ data }) => {
+  const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email);
   return {
     data: isValid,
-    extractedUpdate: {
-      emailValid: isValid, // Enrich extracted data
+    dataUpdate: {
+      emailValid: isValid, // Enrich collected data
     },
   };
 });
@@ -397,16 +397,16 @@ See how different AI providers work:
 
 ### 📊 [Company Q&A Agent](../examples/company-qna-agent.ts)
 
-**Perfect for:** Stateless question-answering systems
+**Perfect for:** Stepless question-answering systems
 
 Simple Q&A agent with knowledge base:
 
-- ✅ Stateless routes (no data extraction)
+- ✅ Stepless routes (no data extraction)
 - ✅ Knowledge base integration
 - ✅ Simple request-response pattern
 - ✅ Perfect for FAQ bots
 
-**Key concepts:** Stateless routing, Q&A patterns
+**Key concepts:** Stepless routing, Q&A patterns
 
 ---
 
@@ -428,7 +428,7 @@ 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
+2. **Simple flow:** [Travel Agent](../examples/travel-agent.ts) - Session step & 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
@@ -438,7 +438,7 @@ bun examples/travel-agent.ts
 | Example             | Best For        | Key Features                |
 | ------------------- | --------------- | --------------------------- |
 | Declarative Agent   | Learning basics | Full API coverage           |
-| Travel Agent        | Session state   | Multi-turn conversations    |
+| Travel Agent        | Session step    | Multi-turn conversations    |
 | Business Onboarding | Complex flows   | Branching, lifecycle hooks  |
 | Healthcare Agent    | Security        | Data validation, compliance |
 | Streaming Agent     | Real-time UX    | Streaming responses         |

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"],
-  extractionSchema: {
+  schema: {
     type: "object",
     properties: {
       destination: { type: "string" },
@@ -102,10 +102,10 @@ const bookingRoute = agent.createRoute<FlightData>({
   },
 });
 
-// Initialize session state
+// Initialize session step
 let session = createSession<FlightData>();
 
-// Generate a response with session state
+// Generate a response with session step
 const response = await agent.respond({
   history: [
     createMessageEvent(
@@ -118,7 +118,7 @@ const response = await agent.respond({
 });
 
 console.log("Agent:", response.message);
-console.log("Extracted:", response.session?.extracted);
+console.log("Data:", response.session?.data);
 ```
 
 ### 3. Run It!
@@ -133,9 +133,9 @@ bun run index.ts
 
 ## Next Steps
 
-### Add Session State Management
+### Add Session Step Management
 
-Continue the conversation with extracted data:
+Continue the conversation with collected data:
 
 ```typescript
 // Turn 2 - User provides more details
@@ -144,90 +144,87 @@ const response2 = await agent.respond({
     createMessageEvent(EventSource.AI_AGENT, "Bot", response.message),
     createMessageEvent(EventSource.CUSTOMER, "Alice", "Make it business class"),
   ],
-  session: response.session, // Pass previous session state
+  session: response.session, // Pass previous session step
 });
 
 console.log("Agent:", response2.message);
-console.log("Updated extracted:", response2.session?.extracted);
+console.log("Updated data:", response2.session?.data);
 // Agent remembers destination and passengers, updates cabin class
 ```
 
 ### Create Tools with Data Access
 
-Tools can access and modify extracted data:
+Tools can access and modify collected data:
 
 ```typescript
 import { defineTool } from "@falai/agent";
 
 const searchFlights = defineTool<MyContext, [], void, FlightData>(
   "search_flights",
-  async ({ context, extracted }) => {
-    // Access extracted data directly
-    if (!extracted.destination || !extracted.departureDate) {
+  async ({ context, data }) => {
+    // Access collected data directly
+    if (!data.destination || !data.departureDate) {
       return { data: undefined };
     }
 
-    // Search for flights and enrich extracted data
-    const flights = await searchFlightAPI(
-      extracted.destination,
-      extracted.departureDate
-    );
+    // Search for flights and enrich collected data
+    const flights = await searchFlightAPI(data.destination, data.departureDate);
 
     return {
       data: undefined,
       contextUpdate: { availableFlights: flights },
-      extractedUpdate: {
-        destinationCode: await lookupAirportCode(extracted.destination),
+      dataUpdate: {
+        destinationCode: await lookupAirportCode(data.destination),
       },
     };
   },
-  { description: "Search for available flights based on extracted data" }
+  { description: "Search for available flights based on collected data" }
 );
 
-// Add tool to state machine
-const searchState = bookingRoute.initialState
-  .transitionTo({
-    chatState: "Extract travel details",
-    gather: ["destination", "departureDate", "passengers"],
+// Add tool to step machine
+const searchStep = bookingRoute.initialStep
+  .nextStep({
+    instructions: "Extract travel details",
+    collect: ["destination", "departureDate", "passengers"],
   })
-  .transitionTo({
-    toolState: searchFlights,
-    requiredData: ["destination", "departureDate", "passengers"],
+  .nextStep({
+    tool: searchFlights,
+    requires: ["destination", "departureDate", "passengers"],
   });
 ```
 
-### Build Smart State Machines
+### Build Smart Step Machines
 
 Create intelligent flows with code-based logic:
 
 ```typescript
-// 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
+// Step machine with smart bypassing and data validation
+const askDestination = bookingRoute.initialStep.nextStep({
+  instructions: "Ask where they want to fly",
+  collect: ["destination"],
+  skipIf: (data) => !!data.destination, // Skip if already have destination
 });
 
-const enrichDestination = askDestination.transitionTo({
-  toolState: searchFlights, // Tool executes automatically
-  requiredData: ["destination"], // Prerequisites
+const enrichDestination = askDestination.nextStep({
+  tool: searchFlights, // Tool executes automatically
+  requires: ["destination"], // Prerequisites
 });
 
-const askDates = enrichDestination.transitionTo({
-  chatState: "Ask about travel dates",
-  gather: ["departureDate"],
-  skipIf: (extracted) => !!extracted.departureDate,
-  requiredData: ["destination"], // Must have destination first
+const askDates = enrichDestination.nextStep({
+  instructions: "Ask about travel dates",
+  collect: ["departureDate"],
+  skipIf: (data) => !!data.departureDate,
+  requires: ["destination"], // Must have destination first
 });
 
-const askPassengers = askDates.transitionTo({
-  chatState: "How many passengers?",
-  gather: ["passengers"],
-  skipIf: (extracted) => !!extracted.passengers,
+const askPassengers = askDates.nextStep({
+  instructions: "How many passengers?",
+  collect: ["passengers"],
+  skipIf: (data) => !!data.passengers,
 });
 
-const presentFlights = askPassengers.transitionTo({
-  chatState: "Present available flights from search results",
+const presentFlights = askPassengers.nextStep({
+  instructions: "Present available flights from search results",
 });
 ```
 
@@ -284,12 +281,12 @@ if (user.isPremium) {
 }
 ```
 
-### Multi-Turn Conversations with Session State
+### Multi-Turn Conversations with Session Step
 
-Track conversation progress and extracted data:
+Track conversation progress and collected data:
 
 ```typescript
-import { createSession, enterRoute, mergeExtracted } from "@falai/agent";
+import { createSession, enterRoute, mergeData } from "@falai/agent";
 
 // Initialize session
 let session = createSession<FlightData>();
@@ -304,10 +301,10 @@ const history1 = [
 ];
 
 const response1 = await agent.respond({ history: history1, session });
-console.log("Turn 1 - Extracted:", response1.session?.extracted);
+console.log("Turn 1 - Data:", response1.session?.data);
 // { destination: "Paris", departureDate: "tomorrow", passengers: 2 }
 
-session = response1.session!; // Update session with extracted data
+session = response1.session!; // Update session with collected data
 
 // Turn 2 - User changes their mind
 const history2 = [
@@ -321,7 +318,7 @@ const history2 = [
 ];
 
 const response2 = await agent.respond({ history: history2, session });
-console.log("Turn 2 - Updated:", response2.session?.extracted);
+console.log("Turn 2 - Updated:", response2.session?.data);
 // { destination: "Tokyo", departureDate: "tomorrow", passengers: 2 }
 
 session = response2.session!; // Router handled the route change
@@ -335,7 +332,7 @@ const response3 = await agent.respond({
   ],
   session,
 });
-console.log("Turn 3 - Final:", response3.session?.extracted);
+console.log("Turn 3 - Final:", response3.session?.data);
 // { destination: "Tokyo", departureDate: "tomorrow", passengers: 2, cabinClass: "business" }
 ```
 
@@ -347,18 +344,18 @@ console.log("Turn 3 - Final:", response3.session?.extracted);
 
 - **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
+- **Leverage session step** - Track conversation progress across turns
+- **Use code-based logic** - `skipIf` and `requires` for deterministic flow
+- **Create type-safe routes** - Generic types for both context and collected 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
+- **Add lifecycle hooks** - Validate and enrich collected data
+- **Mix stepful & stepless** - Use appropriate patterns for each use case
 
 ### ❌ Don'ts
 
-- **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 use `any` types** - Define proper interfaces for context and collected data
+- **Don't rely on LLM conditions** - Use code (`skipIf`) for step logic
+- **Don't skip session management** - Pass session step 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