@falai/agent 0.6.9 → 0.7.0

package/docs/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-`@falai/agent` is built on a **schema-first, data-driven architecture** that prioritizes type safety, structured data extraction, and code-based state management over fuzzy LLM conditions. This creates predictable, maintainable, and efficient conversational AI agents.
+`@falai/agent` is built on a **schema-first, data-driven architecture** that prioritizes type safety, structured data extraction, and code-based step management over fuzzy LLM conditions. This creates predictable, maintainable, and efficient conversational AI agents.
 
 ## Core Design Principles
 
@@ -22,7 +22,7 @@ interface FlightData {
 const route = agent.createRoute<FlightData>({
   title: "Book Flight",
   description: "Help user book a flight",
-  extractionSchema: {
+  schema: {
     type: "object",
     properties: {
       destination: { type: "string" },
@@ -46,17 +46,12 @@ const route = agent.createRoute<FlightData>({
 - **Predictability** - Same data structure every time
 - **Efficiency** - Extract multiple fields in one LLM call
 
-### 2. 📊 Session State Management
+### 2. 📊 Session Step Management
 
-Track conversation progress and extracted data across turns:
+Track conversation progress and collected data across turns:
 
 ```typescript
-import {
-  createSession,
-  enterRoute,
-  enterState,
-  mergeExtracted,
-} from "@falai/agent";
+import { createSession, enterRoute, enterStep, mergeData } from "@falai/agent";
 
 // Create session with optional metadata including session ID
 let session = createSession<FlightData>(sessionId, {
@@ -66,11 +61,11 @@ let session = createSession<FlightData>(sessionId, {
 
 // Turn 1 - Extract data
 const response1 = await agent.respond({ history, session });
-session = response1.session!; // Updated with extracted data
+session = response1.session!; // Updated with collected data
 
 // Turn 2 - User changes mind (always-on routing)
 const response2 = await agent.respond({ history, session: response1.session });
-session = response2.session!; // Route/state updated if user changed direction
+session = response2.session!; // Route/step updated if user changed direction
 
 // Access session metadata
 console.log(session.metadata?.sessionId); // "unique-session-123"
@@ -81,69 +76,69 @@ console.log(session.metadata?.sessionId); // "unique-session-123"
 When using persistence adapters, set the session ID from the database:
 
 ```typescript
-// Create database session and in-memory session state
-const { sessionData, sessionState } =
-  await persistence.createSessionWithState<FlightData>({
+// Create database session and in-memory session step
+const { sessionData, sessionStep } =
+  await persistence.createSessionWithStep<FlightData>({
     userId: "user_123",
     agentName: "Travel Agent",
   });
 
-// sessionState.metadata.sessionId is automatically set to sessionData.id
-console.log(sessionState.metadata?.sessionId); // "cuid_from_database"
+// sessionStep.metadata.sessionId is automatically set to sessionData.id
+console.log(sessionStep.metadata?.sessionId); // "cuid_from_database"
 
 // Use it in conversation
 const response = await agent.respond({
   history,
-  session: sessionState, // Auto-saves to database!
+  session: sessionStep, // Auto-saves to database!
 });
 ```
 
-**Why?** Session state enables:
+**Why?** Session step enables:
 
 - **Always-on Routing** - Users can change their mind mid-conversation
-- **Context Awareness** - Router sees current progress and extracted data
-- **Data Persistence** - Extracted data survives across turns
-- **State Recovery** - Resume conversations from any point
+- **Context Awareness** - Router sees current progress and collected data
+- **Data Persistence** - Collected data survives across turns
+- **Step Recovery** - Resume conversations from any point
 - **Session Tracking** - Track conversations via session ID in database
 
-### 3. 🔧 Code-Based State Logic + AI-Driven Transitions
+### 3. 🔧 Code-Based Step Logic + AI-Driven Transitions
 
-Use TypeScript functions for deterministic flow control AND text conditions for AI-driven state selection:
+Use TypeScript functions for deterministic flow control AND text conditions for AI-driven step selection:
 
 ```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!
+// Step with smart bypassing based on collected data
+const askDestination = route.initialStep.nextStep({
+  id: "ask_destination", // Optional: custom step ID
+  instructions: "Ask where they want to fly",
+  collect: ["destination"],
+  skipIf: (data) => !!data.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
+const askDate = askDestination.nextStep({
+  id: "ask_date", // Optional: custom step ID for easier tracking
+  instructions: "Ask about travel dates",
+  collect: ["departureDate"],
+  skipIf: (data) => !!data.departureDate,
+  requires: ["destination"], // Prerequisites
   condition: "Destination confirmed, need travel dates now",
 });
 });
 ```
 
-**Custom State IDs:**
+**Custom Step IDs:**
 
-You can optionally provide custom IDs for states to make them easier to track and reference:
+You can optionally provide custom IDs for steps to make them easier to track and reference:
 
 ```typescript
-const confirmBooking = askDate.transitionTo({
+const confirmBooking = askDate.nextStep({
   id: "confirm_booking", // ✅ Custom ID instead of auto-generated
-  chatState: "Confirm all booking details",
-  requiredData: ["destination", "departureDate", "passengers"],
+  instructions: "Confirm all booking details",
+  requires: ["destination", "departureDate", "passengers"],
 });
 ```
 
-If you don't provide an ID, one is automatically generated from the route ID and state description.
+If you don't provide an ID, one is automatically generated from the route ID and step description.
 
 **Why?** Code-based logic provides:
 
@@ -151,46 +146,46 @@ If you don't provide an ID, one is automatically generated from the route ID and
 - **Performance** - No extra LLM calls for condition checking
 - **Debugging** - Clear logic flow you can trace
 - **Type Safety** - Full TypeScript support for data validation
-- **Custom IDs** - Easier tracking and debugging with meaningful state identifiers
+- **Custom IDs** - Easier tracking and debugging with meaningful step identifiers
 
-**How State Transitions Work:**
+**How Step Transitions Work:**
 
-1. **Code filters first**: `skipIf` and `requiredData` filter out invalid states deterministically
-2. **AI selects best state**: From valid candidates, AI evaluates text conditions to choose optimal state
-3. **Combined decision**: Single AI call handles both route selection AND state selection (no extra calls!)
-4. **Completion detection**: When all states are skipped and `END_STATE` is reached, route is marked complete
+1. **Code filters first**: `skipIf` and `requires` filter out invalid steps deterministically
+2. **AI selects best step**: From valid candidates, AI evaluates text conditions to choose optimal step
+3. **Combined decision**: Single AI call handles both route selection AND step selection (no extra calls!)
+4. **Completion detection**: When all steps are skipped and `END_ROUTE` is reached, route is marked complete
 
 ```typescript
 // The AI sees:
-// "Available states: askDate, confirmBooking
+// "Available steps: askDate, confirmBooking
 //  - askDate: Destination confirmed, need travel dates now
 //  - confirmBooking: All required info collected, ready to book
-//  Current extracted: {destination: 'Paris', departureDate: '2025-01-15'}
+//  Current data: {destination: 'Paris', departureDate: '2025-01-15'}
 //
 //  → AI selects 'confirmBooking' based on context"
 ```
 
 ### 4. 🛠️ Tools with Data Access
 
-Tools execute with full context including extracted data:
+Tools execute with full context including collected data:
 
 ```typescript
 const searchFlights = defineTool<Context, [], void, FlightData>(
   "search_flights",
   async (toolContext) => {
-    const { extracted, context, history } = toolContext;
+    const { data, context, history } = toolContext;
 
-    // Access extracted data directly
-    if (!extracted.destination || !extracted.departureDate) {
+    // Access collected data directly
+    if (!data.destination || !data.departureDate) {
       return { data: undefined };
     }
 
-    // Enrich extracted data
+    // Enrich collected data
     return {
       data: undefined,
-      extractedUpdate: {
-        destinationCode: await lookupAirportCode(extracted.destination),
-        departureDateParsed: parseDate(extracted.departureDate),
+      dataUpdate: {
+        destinationCode: await lookupAirportCode(data.destination),
+        departureDateParsed: parseDate(data.departureDate),
       },
     };
   }
@@ -199,9 +194,9 @@ const searchFlights = defineTool<Context, [], void, FlightData>(
 
 **Why?** Tools with data access enable:
 
-- **Data Enrichment** - Tools can validate and enhance extracted data
-- **Computed Fields** - Calculate derived values from extracted data
-- **Conditional Execution** - Tools decide what to do based on data state
+- **Data Enrichment** - Tools can validate and enhance collected data
+- **Computed Fields** - Calculate derived values from collected data
+- **Conditional Execution** - Tools decide what to do based on data step
 - **Action Flags** - Tools can set flags for subsequent operations
 
 ### 5. 🎭 Always-On Routing
@@ -248,23 +243,23 @@ Clean separation of concerns in every response:
 
 **Phase 1: Preparation**
 
-- Execute tools if current state has `toolState`
+- Execute tools if current step has `tool`
 - Update context with tool results
-- Enrich extracted data if tools return `extractedUpdate`
+- Enrich collected data if tools return `dataUpdate`
 
 **Phase 2: Routing**
 
 - Build dynamic routing schema (scores for all routes 0-100)
 - Include session context in routing prompt
-- AI selects best route based on current state
+- AI selects best route based on current step
 - Update session if route changed
 
 **Phase 3: Response**
 
-- Determine next state using `skipIf` and `requiredData`
-- Build response schema including current state's `gather` fields
+- Determine next step using `skipIf` and `requires`
+- Build response schema including current step's `collect` fields
 - Generate message with schema-enforced data extraction
-- Update session with newly extracted data
+- Update session with newly collected data
 
 **Why?** This architecture enables:
 
@@ -291,17 +286,17 @@ const agent = new Agent({
       await saveContext(newCtx);
     },
 
-    // Validate and enrich extracted data
-    onExtractedUpdate: async (extracted, previous) => {
+    // Validate and enrich collected data
+    onDataUpdate: async (data, previous) => {
       // Normalize data
-      if (extracted.passengers < 1) extracted.passengers = 1;
+      if (data.passengers < 1) data.passengers = 1;
 
       // Auto-trigger actions
-      if (hasAllRequiredData(extracted)) {
-        extracted.shouldSearchFlights = true;
+      if (hasAllRequires(data)) {
+        data.shouldSearchFlights = true;
       }
 
-      return extracted;
+      return data;
     },
   },
 });
@@ -309,18 +304,18 @@ const agent = new Agent({
 
 **Why?** Lifecycle hooks provide:
 
-- **Data Validation** - Ensure extracted data meets business rules
+- **Data Validation** - Ensure collected data meets business rules
 - **Enrichment** - Add computed fields or normalize values
-- **Persistence** - Save/restore conversation state
+- **Persistence** - Save/restore conversation step
 - **Integration** - Connect with external systems
 
 ## Comparison with Other Approaches
 
-### @falai/agent vs Traditional State Machines
+### @falai/agent vs Traditional Step Machines
 
-| Aspect              | @falai/agent (Data-Driven) | Traditional State Machines            |
+| Aspect              | @falai/agent (Data-Driven) | Traditional Step Machines             |
 | ------------------- | -------------------------- | ------------------------------------- |
-| **State Logic**     | Code-based (`skipIf`)      | Manual condition checking             |
+| **Step Logic**      | Code-based (`skipIf`)      | Manual condition checking             |
 | **Data Collection** | Schema-driven extraction   | Manual parsing                        |
 | **Type Safety**     | Full TypeScript            | Often runtime validation              |
 | **LLM Calls/Turn**  | 1-2 (routing + response)   | 3-5 (conditions + routing + response) |
@@ -331,8 +326,8 @@ const agent = new Agent({
 
 | Aspect             | @falai/agent             | OpenAI Functions              |
 | ------------------ | ------------------------ | ----------------------------- |
-| **Tool Execution** | Automatic (state-driven) | AI-decided                    |
-| **Flow Control**   | Code-based state logic   | AI inference                  |
+| **Tool Execution** | Automatic (step-driven)  | AI-decided                    |
+| **Flow Control**   | Code-based step logic    | AI inference                  |
 | **Determinism**    | High - code-driven flow  | Low - AI may vary             |
 | **Data Handling**  | Structured schemas       | Unstructured function results |
 | **Type Safety**    | Full TypeScript          | Runtime type checking         |
@@ -352,14 +347,14 @@ const agent = new Agent({
 
 - **Open-Ended Chat** - General conversation without clear goals
 - **Creative Tasks** - Brainstorming, writing, ideation
-- **Simple Q&A** - Stateless question-answering (use stateless routes!)
+- **Simple Q&A** - Stepless question-answering (use stepless routes!)
 - **Rapid Prototyping** - When you need maximum flexibility
 
 ## Architecture Patterns
 
-### Stateful Routes (Data Collection)
+### Stepful Routes (Data Collection)
 
-For structured data gathering with state management:
+For structured data collecting with step management:
 
 ```typescript
 interface BookingData {
@@ -370,41 +365,41 @@ interface BookingData {
 
 const bookingRoute = agent.createRoute<BookingData>({
   title: "Flight Booking",
-  extractionSchema: {
+  schema: {
     /* schema for all fields */
   },
 });
 
-bookingRoute.initialState
-  .transitionTo({
-    chatState: "Ask destination",
-    gather: ["destination"],
+bookingRoute.initialStep
+  .nextStep({
+    instructions: "Ask destination",
+    collect: ["destination"],
     skipIf: (data) => !!data.destination,
   })
-  .transitionTo({
-    toolState: enrichDestination, // Validates and enriches
-    requiredData: ["destination"],
+  .nextStep({
+    tool: enrichDestination, // Validates and enriches
+    requires: ["destination"],
   })
-  .transitionTo({
-    chatState: "Ask dates",
-    gather: ["dates"],
+  .nextStep({
+    instructions: "Ask dates",
+    collect: ["dates"],
     skipIf: (data) => !!data.dates,
   });
 ```
 
-### Stateless Routes (Q&A)
+### Stepless Routes (Q&A)
 
-For simple question-answering without state:
+For simple question-answering without step:
 
 ```typescript
 const qnaRoute = agent.createRoute({
   title: "Company Q&A",
   conditions: ["User asks about company"],
-  // NO extractionSchema - stateless!
+  // NO schema - stepless!
 });
 
-// Just use initial state
-qnaRoute.initialState.chatState = "Answer from knowledge base";
+// Just use initial step
+qnaRoute.initialStep.instructions = "Answer from knowledge base";
 ```
 
 ### Mixed Architecture
@@ -412,7 +407,7 @@ qnaRoute.initialState.chatState = "Answer from knowledge base";
 Combine both patterns in one agent:
 
 ```typescript
-// Q&A routes (stateless)
+// Q&A routes (stepless)
 const companyInfoRoute = agent.createRoute({
   /* no schema */
 });
@@ -420,7 +415,7 @@ const productInfoRoute = agent.createRoute({
   /* no schema */
 });
 
-// Booking routes (stateful)
+// Booking routes (stepful)
 const bookingRoute = agent.createRoute<BookingData>({
   /* with schema */
 });
@@ -434,15 +429,15 @@ const supportRoute = agent.createRoute<SupportData>({
 This framework draws inspiration from:
 
 1. **Schema-First APIs** - JSON Schema for data contracts
-2. **State Machines** - Explicit state modeling for predictability
+2. **Step Machines** - Explicit step modeling for predictability
 3. **TypeScript** - Full type safety throughout
-4. **Functional Programming** - Pure functions for state logic
+4. **Functional Programming** - Pure functions for step logic
 5. **React Hooks** - Lifecycle patterns for extensibility
 
 ## Further Reading
 
 - [Getting Started Guide](./GETTING_STARTED.md) - Build your first agent
-- [Session State Guide](./CONTEXT_MANAGEMENT.md) - Session management patterns
+- [Session Step Guide](./CONTEXT_MANAGEMENT.md) - Session management patterns
 - [API Reference](./API_REFERENCE.md) - Complete API documentation
 - [Examples](../examples/) - Real-world implementations