@falai/agent 0.8.1 → 0.9.0-alpha-2

package/docs/{ARCHITECTURE.md → core/agent/session-management.md}

@@ -1,27 +1,33 @@
-# Architecture & Design Principles
+# Session Management
 
 ## Overview
 
-`@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.
+The `@falai/agent` framework provides **automatic session management** through the `SessionManager` class, eliminating the need for manual session creation, persistence, and state management. Sessions are automatically created, loaded, and saved, allowing developers to focus on building conversation logic rather than managing session lifecycle.
 
 ## Core Design Principles
 
-### 1. 🎯 Schema-First Data Extraction
+### 1. 🎯 Agent-Level Schema-First Data Extraction
 
-Define what data to collect upfront using JSON Schema, then extract it reliably:
+Define what data to collect upfront using JSON Schema at the agent level, then extract it reliably across all routes:
 
 ```typescript
-// Define your data contract
-interface FlightData {
+// Define your agent-level data contract
+interface TravelData {
   destination: string;
   departureDate: string;
   passengers: number;
   cabinClass: "economy" | "business" | "first";
+  hotelPreference?: string;
+  budgetRange?: string;
+  specialRequests?: string;
 }
 
-const route = agent.createRoute<FlightData>({
-  title: "Book Flight",
-  description: "Help user book a flight",
+// Agent with centralized schema
+const agent = new Agent<{}, TravelData>({
+  name: "Travel Agent",
+  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  
+  // Agent-level schema defines all possible data fields
   schema: {
     type: "object",
     properties: {
@@ -33,73 +39,106 @@ const route = agent.createRoute<FlightData>({
         enum: ["economy", "business", "first"],
         default: "economy",
       },
+      hotelPreference: { type: "string" },
+      budgetRange: { type: "string" },
+      specialRequests: { type: "string" }
     },
     required: ["destination", "departureDate", "passengers"],
-  },
+  }
+});
+
+// Routes specify required fields instead of schemas
+const flightRoute = agent.createRoute({
+  title: "Book Flight",
+  description: "Help user book a flight",
+  requiredFields: ["destination", "departureDate", "passengers", "cabinClass"],
+  optionalFields: ["specialRequests"]
+});
+
+const hotelRoute = agent.createRoute({
+  title: "Book Hotel", 
+  description: "Help user book accommodation",
+  requiredFields: ["destination", "departureDate", "hotelPreference"],
+  optionalFields: ["budgetRange", "specialRequests"]
 });
 ```
 
-**Why?** Schema-first extraction provides:
+**Why?** Agent-level schema-first extraction provides:
 
-- **Type Safety** - Full TypeScript types from definition to extraction
+- **Type Safety** - Full TypeScript types from definition to extraction across all routes
 - **Reliability** - Provider-enforced schemas, not prompt-based parsing
-- **Predictability** - Same data structure every time
+- **Predictability** - Same data structure every time, shared across routes
 - **Efficiency** - Extract multiple fields in one LLM call
+- **Cross-Route Data Sharing** - Data collected by any route is available to all routes
+- **Route Completion** - Routes complete when their required fields are satisfied
 
-### 2. 📊 Session Step Management
+### 2. 🤖 Automatic Session Management
 
-Track conversation progress and collected data across turns:
+Sessions are automatically managed through the `SessionManager` class integrated into every `Agent`:
 
 ```typescript
-import { createSession, enterRoute, enterStep, mergeData } from "@falai/agent";
-
-// Create session with optional metadata including session ID
-let session = createSession<FlightData>(sessionId, {
-  userId: "user_456",
-  createdAt: new Date(),
+// Server-side: Agent with automatic session management and agent-level data
+const agent = new Agent<{}, TravelData>({
+  name: "Travel Agent",
+  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  persistence: { adapter: new PrismaAdapter({ prisma }) },
+  sessionId: "user-123", // Automatically loads or creates this session
+  
+  // Agent-level schema
+  schema: { /* comprehensive travel data schema */ }
 });
 
-// Turn 1 - Extract data
-const response1 = await agent.respond({ history, session });
-session = response1.session!; // Updated with collected data
+// Simple conversation - no manual session management
+const response1 = await agent.respond("I want to book a flight to Paris");
+console.log(agent.session.id); // Session ID
+console.log(agent.session.getData<TravelData>()); // Agent-level collected data
 
-// Turn 2 - User changes mind (always-on routing)
-const response2 = await agent.respond({ history, session: response1.session });
-session = response2.session!; // Route/step updated if user changed direction
+// Continue conversation - session automatically maintained
+const response2 = await agent.respond("Make that Tokyo instead");
+// Session automatically updated with new data in agent-level structure
 
-// Access session metadata
-console.log(session.metadata?.sessionId); // "unique-session-123"
+// Switch to hotel booking - data is shared
+const response3 = await agent.respond("Also book me a hotel in Tokyo");
+// Hotel route can access destination data collected by flight route
 ```
 
-**Session with Persistence:**
+**SessionManager API:**
 
-When using persistence adapters, set the session ID from the database:
+The `SessionManager` provides a clean API for session operations:
 
 ```typescript
-// Create database session and in-memory session step
-const { sessionData, sessionStep } =
-  await persistence.createSessionWithStep<FlightData>({
-    userId: "user_123",
-    agentName: "Travel Agent",
-  });
-
-// 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: sessionStep, // Auto-saves to database!
-});
+// Access the session manager
+const sessionManager = agent.session;
+
+// Get or create session (works for existing, new, or auto-generated IDs)
+await sessionManager.getOrCreate("user-123");
+await sessionManager.getOrCreate(); // Auto-generates ID
+
+// History management
+await sessionManager.addMessage("user", "Hello");
+await sessionManager.addMessage("assistant", "Hi there!");
+const history = sessionManager.getHistory();
+sessionManager.clearHistory();
+
+// Data access
+const data = sessionManager.getData<FlightData>();
+await sessionManager.setData({ destination: "Paris" });
+
+// Session operations
+await sessionManager.save(); // Manual save (auto-saves on addMessage)
+await sessionManager.delete();
+const newSession = await sessionManager.reset(true); // Preserve history
 ```
 
-**Why?** Session step enables:
+**Why?** Automatic session management provides:
 
+- **Zero Boilerplate** - No manual session creation or persistence code
+- **Server-Friendly** - Perfect for stateless server environments
 - **Always-on Routing** - Users can change their mind mid-conversation
 - **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
+- **Data Persistence** - Collected data automatically saved and restored
+- **History Management** - Conversation history automatically maintained
+- **Session Tracking** - Easy session identification for client/server communication
 
 ### 3. 🔧 Code-Based Step Logic + AI-Driven Transitions
 
@@ -109,7 +148,7 @@ Use TypeScript functions for deterministic flow control AND text conditions for
 // 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",
+  prompt: "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
@@ -117,7 +156,7 @@ const askDestination = route.initialStep.nextStep({
 
 const askDate = askDestination.nextStep({
   id: "ask_date", // Optional: custom step ID for easier tracking
-  instructions: "Ask about travel dates",
+  prompt: "Ask about travel dates",
   collect: ["departureDate"],
   skipIf: (data) => !!data.departureDate,
   requires: ["destination"], // Prerequisites
@@ -133,7 +172,7 @@ You can optionally provide custom IDs for steps to make them easier to track and
 ```typescript
 const confirmBooking = askDate.nextStep({
   id: "confirm_booking", // ✅ Custom ID instead of auto-generated
-  instructions: "Confirm all booking details",
+  prompt: "Confirm all booking details",
   requires: ["destination", "departureDate", "passengers"],
 });
 ```
@@ -170,9 +209,16 @@ If you don't provide an ID, one is automatically generated from the route ID and
 Tools execute with full context including collected data:
 
 ```typescript
-const searchFlights = defineTool<Context, [], void, FlightData>(
-  "search_flights",
-  async (toolContext) => {
+import { Tool } from "@falai/agent";
+
+const searchFlights: Tool<Context, [], void, FlightData> = {
+  id: "search_flights",
+  description: "Search for available flights based on collected data",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: async (toolContext) => {
     const { data, context, history } = toolContext;
 
     // Access collected data directly
@@ -188,8 +234,8 @@ const searchFlights = defineTool<Context, [], void, FlightData>(
         departureDateParsed: parseDate(data.departureDate),
       },
     };
-  }
-);
+  },
+};
 ```
 
 **Why?** Tools with data access enable:
@@ -207,7 +253,10 @@ Routing happens every turn, allowing users to change direction:
 // User starts booking a flight
 const response1 = await agent.respond({
   history: [
-    createMessageEvent(EventSource.CUSTOMER, "User", "I want to fly to Paris"),
+    {
+      role: "user",
+      content: "I want to fly to Paris",
+    },
   ],
   session,
 });
@@ -216,11 +265,10 @@ const response1 = await agent.respond({
 const response2 = await agent.respond({
   history: [
     ...previousHistory,
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "Actually, make that Tokyo instead"
-    ),
+    {
+      role: "user",
+      content: "Actually, make that Tokyo instead",
+    },
   ],
   session: response1.session, // Router sees context and switches appropriately
 });
@@ -372,7 +420,7 @@ const bookingRoute = agent.createRoute<BookingData>({
 
 bookingRoute.initialStep
   .nextStep({
-    instructions: "Ask destination",
+    prompt: "Ask destination",
     collect: ["destination"],
     skipIf: (data) => !!data.destination,
   })
@@ -381,7 +429,7 @@ bookingRoute.initialStep
     requires: ["destination"],
   })
   .nextStep({
-    instructions: "Ask dates",
+    prompt: "Ask dates",
     collect: ["dates"],
     skipIf: (data) => !!data.dates,
   });
@@ -399,7 +447,7 @@ const qnaRoute = agent.createRoute({
 });
 
 // Just use initial step
-qnaRoute.initialStep.instructions = "Answer from knowledge base";
+qnaRoute.initialStep.prompt = "Answer from knowledge base";
 ```
 
 ### Mixed Architecture
@@ -436,9 +484,9 @@ This framework draws inspiration from:
 
 ## Further Reading
 
-- [Getting Started Guide](./GETTING_STARTED.md) - Build your first agent
+- [Getting Started Guide](../guides/getting-started/README.md) - Build your first agent
 - [Session Step Guide](./CONTEXT_MANAGEMENT.md) - Session management patterns
-- [API Reference](./API_REFERENCE.md) - Complete API documentation
+- [API Reference](../api/README.md) - Complete API documentation
 - [Examples](../examples/) - Real-world implementations
 
 ---

package/docs/core/ai-integration/prompt-composition.md

@@ -0,0 +1,220 @@
+# Prompt Composition
+
+@fali/agent automatically builds comprehensive prompts for AI providers by combining agent configuration, route context, conversation history, and current session state.
+
+## Overview
+
+The `PromptComposer` class is responsible for constructing detailed prompts that provide AI models with all necessary context to make intelligent routing and response decisions.
+
+## Prompt Structure
+
+Prompts are built with multiple sections in a specific order:
+
+1. **Agent Identity** - Core agent persona and personality
+2. **Routing Overview** - Available routes and current context
+3. **Knowledge Base** - Agent and route-specific knowledge
+4. **Guidelines & Rules** - Behavioral constraints and preferences
+5. **Conversation History** - Previous messages and context
+6. **Current Session** - Active route, collected data, and step state
+7. **Task-Specific Instructions** - Route-specific prompts and schemas
+
+## Agent Identity Section
+
+```typescript
+// Agent configuration contributes to identity
+const agent = new Agent({
+  name: "TravelBot",
+  description: "AI assistant for travel planning and booking",
+  goal: "Help users plan perfect trips efficiently",
+  personality: "Friendly, knowledgeable, and efficient",
+});
+```
+
+This generates:
+
+```
+You are TravelBot, an AI assistant for travel planning and booking.
+Your goal is to help users plan perfect trips efficiently.
+You are friendly, knowledgeable, and efficient.
+```
+
+## Routing Overview Section
+
+Provides the AI with information about available conversation routes:
+
+```
+Available Routes:
+1. Flight Booking - Help users book flights
+2. Hotel Reservation - Find and book accommodations
+3. Travel Itinerary - Create detailed trip plans
+4. Customer Support - Handle travel-related questions
+
+Current Route: Flight Booking
+Route Description: Help users book flights with the best options
+```
+
+## Knowledge Base Integration
+
+Agent and route knowledge bases are formatted and included:
+
+```typescript
+const agent = new Agent({
+  knowledgeBase: {
+    company: "Acme Travel - Premium travel services since 1995",
+    policies: {
+      cancellation: "Free cancellation up to 24 hours before departure",
+      refund: "Refunds processed within 3-5 business days",
+    },
+  },
+});
+```
+
+## Guidelines & Rules Section
+
+Combines agent-level and route-level behavioral constraints:
+
+```
+Guidelines:
+- Always be polite and helpful
+- Ask clarifying questions when needed
+- Provide options rather than single recommendations
+
+Rules for this route:
+- Always confirm flight details before booking
+- Never share personal information
+- Use specific date formats (YYYY-MM-DD)
+```
+
+## Conversation History
+
+Recent conversation history with context updates:
+
+```
+Previous Messages:
+User: I want to book a flight to Paris
+Assistant: I'd be happy to help you book a flight to Paris. When would you like to travel?
+
+User: Next week, for 3 nights
+Assistant: Great! Let me check flights for next week. Could you tell me which airport you'd like to depart from?
+```
+
+## Session State
+
+Current session information including:
+
+- Active route and step
+- Agent-level collected data (with privacy filtering)
+- Route progress and completion status
+- Cross-route data availability
+
+```
+Current Session:
+- Route: Flight Booking (2/3 required fields collected)
+- Step: ask_passengers
+- Agent Data: { destination: "Paris", departureDate: "2025-01-15" }
+- Missing Required: passengers
+- Available from other routes: { hotelPreference: "luxury" }
+```
+
+## Dynamic Schema Generation
+
+For data collection steps, the prompt includes agent-level JSON schemas:
+
+```typescript
+// Agent-level schema
+const agent = new Agent<{}, TravelData>({
+  schema: {
+    type: "object",
+    properties: {
+      destination: { type: "string" },
+      departureDate: { type: "string", format: "date" },
+      passengers: { type: "number", minimum: 1 },
+      hotelPreference: { type: "string" },
+      budgetRange: { type: "string" }
+    },
+    required: ["destination", "departureDate"]
+  }
+});
+
+// Route specifies which fields to collect
+const flightRoute = agent.createRoute({
+  title: "Flight Booking",
+  requiredFields: ["destination", "departureDate", "passengers"],
+  optionalFields: ["budgetRange"]
+});
+```
+
+Generates:
+
+```
+Extract the following information from the user's response based on the agent schema:
+- destination: string - Where the user wants to fly
+- departureDate: string (date format) - When they want to depart
+- passengers: number (minimum 1) - How many people are traveling
+- budgetRange: string (optional) - Budget preference for the trip
+
+Return extracted data as valid JSON matching the agent schema.
+Current route requires: destination, departureDate, passengers
+Route completion: 2/3 required fields collected
+```
+
+## Tool Integration
+
+When tools are available, they're described in the prompt:
+
+```
+Available Tools:
+1. searchFlights - Search for available flights
+   Parameters:
+   - origin: string - Departure airport code
+   - destination: string - Arrival airport code
+   - date: string - Travel date (YYYY-MM-DD)
+
+2. checkWeather - Get weather forecast
+   Parameters:
+   - location: string - City or airport code
+   - date: string - Date for forecast
+```
+
+## Context Updates
+
+Real-time context changes are included:
+
+```
+Current Context:
+- User tier: premium
+- Preferred language: English
+- Last login: 2024-01-15
+- Current location: New York
+```
+
+## Route-Specific Customization
+
+Routes can override agent-level settings:
+
+```typescript
+const supportRoute = agent.createRoute({
+  title: "Customer Support",
+  personality: "Extra patient and detailed when explaining issues",
+  knowledgeBase: {
+    supportHours: "24/7 for premium members, 9-5 EST for others",
+  },
+});
+```
+
+## Performance Optimization
+
+Prompts are optimized for token efficiency:
+
+- Knowledge bases are formatted as clean markdown
+- Redundant information is deduplicated
+- Context is truncated when approaching token limits
+- Only relevant route information is included
+
+## Best Practices
+
+- Keep knowledge bases structured and concise
+- Use clear, specific guidelines rather than vague instructions
+- Leverage route-specific overrides for specialized behavior
+- Monitor token usage and optimize prompt length
+- Test prompts with different AI providers for consistency