@falai/agent 0.7.0 → 0.8.1

package/docs/PERSISTENCE.md

@@ -98,7 +98,7 @@ interface BookingData {
 
 const agent = new Agent({
   name: "My Agent",
-  ai: new GeminiProvider({ apiKey: "..." }),
+  provider: new GeminiProvider({ apiKey: "..." }),
   // ✨ Just add this!
   persistence: {
     adapter: new PrismaAdapter({ prisma }),
@@ -219,7 +219,7 @@ Enable automatic message persistence:
 ```typescript
 const agent = new Agent({
   name: "My Agent",
-  ai: provider,
+  provider: provider,
   persistence: {
     adapter: new PrismaAdapter({ prisma }),
     autoSave: true, // Default: true
@@ -235,7 +235,7 @@ The most powerful pattern - auto-sync context with database:
 ```typescript
 const agent = new Agent({
   name: "Smart Assistant",
-  ai: provider,
+  provider: provider,
   context: {
     userId: "user_123",
     sessionId: session.id,
@@ -270,7 +270,7 @@ await agent.updateContext({ preferences: { theme: "dark" } });
 
 ## Session Step Integration
 
-The new architecture automatically saves and loads `SessionStep<TData>` which includes:
+The new architecture automatically saves and loads `SessionState<TData>` which includes:
 
 - **Current route and step** - Track conversation progress
 - **Collected data** - All data collected via `schema` and `collect` fields
@@ -280,7 +280,7 @@ The new architecture automatically saves and loads `SessionStep<TData>` which in
 ### How It Works
 
 1. **Auto-Save**: When `autoSave: true`, session step is automatically persisted after each `respond()` call
-2. **Conversion**: `SessionStep` is automatically converted to `SessionData` for storage
+2. **Conversion**: `SessionState` is automatically converted to `SessionData` for storage
 3. **Recovery**: Load session step from database to resume conversations
 
 ### Create Session with Step
@@ -303,14 +303,14 @@ const { sessionData, sessionStep } =
 
 ```typescript
 // Manual save (not needed if autoSave: true)
-await persistence.saveSessionStep(sessionId, sessionStep);
+await persistence.saveSessionState(sessionId, sessionStep);
 ```
 
 ### Load Session Step
 
 ```typescript
 // Load session step from database
-const sessionStep = await persistence.loadSessionStep<YourDataType>(sessionId);
+const sessionStep = await persistence.loadSessionState<YourDataType>(sessionId);
 
 // Load message history
 const history = await persistence.loadSessionHistory(sessionId);
@@ -374,10 +374,10 @@ const { sessionData, sessionStep } =
   });
 
 // Save session step (NEW!)
-await persistence.saveSessionStep(sessionId, sessionStep);
+await persistence.saveSessionState(sessionId, sessionStep);
 
 // Load session step (NEW!)
-const sessionStep = await persistence.loadSessionStep<YourDataType>(sessionId);
+const sessionStep = await persistence.loadSessionState<YourDataType>(sessionId);
 
 // Create session (legacy)
 await persistence.createSession({
@@ -478,7 +478,7 @@ import { PrismaClient } from "@prisma/client";
 const prisma = new PrismaClient();
 const agent = new Agent({
   name: "Assistant",
-  ai: provider,
+  provider: provider,
   persistence: {
     adapter: new PrismaAdapter({ prisma }),
   },
@@ -531,7 +531,7 @@ await persistence.saveMessage({
 2. ✅ **Enable `autoSave: true`** - Automatically persist session step after each response
 3. ✅ **Define extraction schemas** - Use `schema` in routes for structured data collection
 4. ✅ **Pass session step** - Always pass `session` parameter to `agent.respond()`
-5. ✅ **Load session step** - Use `loadSessionStep()` to resume conversations
+5. ✅ **Load session step** - Use `loadSessionState()` to resume conversations
 6. ✅ **Store collected data** - Leverage `collectedData.data` for user input tracking
 7. ✅ **Index frequently queried fields** - Add database indexes on `userId`, `status`, etc.
 8. ✅ **Use cascading deletes** - Clean up messages automatically when deleting sessions

package/docs/PROVIDERS.md

@@ -385,7 +385,7 @@ import {
 // Use Anthropic (Claude)
 const claudeAgent = new Agent({
   name: "Claude Assistant",
-  ai: new AnthropicProvider({
+  provider: new AnthropicProvider({
     apiKey: process.env.ANTHROPIC_API_KEY!,
     model: "claude-sonnet-4-5",
   }),
@@ -394,7 +394,7 @@ const claudeAgent = new Agent({
 // Use Gemini
 const geminiAgent = new Agent({
   name: "Gemini Assistant",
-  ai: new GeminiProvider({
+  provider: new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY!,
     model: "models/gemini-2.5-flash",
   }),
@@ -403,7 +403,7 @@ const geminiAgent = new Agent({
 // Use OpenAI
 const openaiAgent = new Agent({
   name: "OpenAI Assistant",
-  ai: new OpenAIProvider({
+  provider: new OpenAIProvider({
     apiKey: process.env.OPENAI_API_KEY!,
     model: "gpt-5",
   }),
@@ -412,7 +412,7 @@ const openaiAgent = new Agent({
 // Use OpenRouter (access to 200+ models)
 const openrouterAgent = new Agent({
   name: "OpenRouter Assistant",
-  ai: new OpenRouterProvider({
+  provider: new OpenRouterProvider({
     apiKey: process.env.OPENROUTER_API_KEY!,
     model: "anthropic/claude-sonnet-4-5",
   }),

package/examples/business-onboarding.ts

@@ -379,7 +379,7 @@ async function createBusinessOnboardingAgent(
     description:
       "A specialized assistant that helps businesses set up intelligent conversation routes for their customers.",
     goal: "Collect comprehensive business information and create personalized conversation routes",
-    ai: provider,
+    provider: provider,
     context: {
       userId,
       userName,

package/examples/company-qna-agent.ts

@@ -146,7 +146,7 @@ const agent = new Agent<CompanyContext>({
     "I'm here to help you learn about Acme Corp, our products, and policies",
   personality:
     "Friendly, helpful, and knowledgeable. Always professional but approachable.",
-  ai: new OpenAIProvider({
+  provider: new OpenAIProvider({
     apiKey: process.env.OPENAI_API_KEY || "test-key",
     model: "gpt-5o-mini",
   }),

package/examples/custom-database-persistence.ts

@@ -16,7 +16,7 @@ import {
   createMessageEvent,
   EventSource,
   createSession,
-  SessionStep,
+  SessionState,
   MessageEventData,
   Event,
   END_ROUTE,
@@ -133,7 +133,7 @@ async function example() {
     name: "Onboarding Assistant",
     description: "Help new customers get started",
     goal: "Collect customer information efficiently",
-    ai: new GeminiProvider({
+    provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.0-flash-exp",
     }),
@@ -218,9 +218,9 @@ async function example() {
   }
 
   /**
-   * Convert database session to agent SessionStep
+   * Convert database session to agent SessionState
    */
-  let agentSession: SessionStep<OnboardingData>;
+  let agentSession: SessionState<OnboardingData>;
 
   if (dbSession.currentRoute && dbSession.collectedData) {
     // Restore existing session from database
@@ -248,7 +248,7 @@ async function example() {
         >) || {},
       routeHistory:
         (dbSession.collectedData
-          ?.routeHistory as SessionStep<OnboardingData>["routeHistory"]) || [],
+          ?.routeHistory as SessionState<OnboardingData>["routeHistory"]) || [],
       metadata: {
         sessionId: dbSession.id,
         userId,
@@ -404,7 +404,7 @@ async function example() {
   if (!reloadedDbSession) throw new Error("Session not found");
 
   // Reconstruct session step
-  const recoveredSession: SessionStep<OnboardingData> = {
+  const recoveredSession: SessionState<OnboardingData> = {
     currentRoute: reloadedDbSession.currentRoute
       ? {
           id: reloadedDbSession.currentRoute,
@@ -430,7 +430,7 @@ async function example() {
       >) || {},
     routeHistory:
       (reloadedDbSession.collectedData
-        ?.routeHistory as SessionStep<OnboardingData>["routeHistory"]) || [],
+        ?.routeHistory as SessionState<OnboardingData>["routeHistory"]) || [],
     metadata: {
       sessionId: reloadedDbSession.id,
       userId,
@@ -479,7 +479,7 @@ async function advancedExample() {
 
   const agent = new Agent({
     name: "Smart Onboarding",
-    ai: new GeminiProvider({
+    provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.0-flash-exp",
     }),

package/examples/declarative-agent.ts

@@ -296,7 +296,7 @@ const agent = new Agent<HealthcareContext>({
     patientId: "p_12345",
     patientName: "Alice Johnson",
   },
-  ai: new GeminiProvider({
+  provider: new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY || "demo-key",
     model: "models/gemini-2.5-flash",
   }),

package/examples/domain-scoping.ts

@@ -23,7 +23,7 @@ import {
 import { OpenRouterProvider } from "../src/providers";
 
 // Initialize AI provider
-const ai = new OpenRouterProvider({
+const provider = new OpenRouterProvider({
   apiKey: process.env.OPENROUTER_API_KEY || "your-api-key-here",
   model: "google/gemini-2.0-flash-exp",
   backupModels: ["anthropic/claude-sonnet-4-5"],
@@ -34,7 +34,7 @@ const agent = new Agent({
   name: "Multi-Domain Assistant",
   description:
     "An assistant that handles different tasks with domain-scoped tools",
-  ai,
+  provider,
 });
 
 // Register different domains with their tools

package/examples/extracted-data-modification.ts

@@ -252,7 +252,7 @@ const agent = new Agent<FlightBookingContext>({
   name: "Flight Booking Agent",
   goal: "Help users book flights efficiently",
   description: "I help you find and book flights",
-  ai: new OpenAIProvider({
+  provider: new OpenAIProvider({
     apiKey: process.env.OPENAI_API_KEY || "your-api-key-here",
     model: "gpt-5o-mini",
   }),

package/examples/healthcare-agent.ts

@@ -106,7 +106,7 @@ async function createHealthcareAgent() {
   const agent = new Agent<HealthcareContext>({
     name: "Healthcare Agent",
     description: "Is empathetic and calming to the patient.",
-    ai: provider,
+    provider: provider,
     context: {
       patientId: "patient-123",
       patientName: "Test Patient",

package/examples/openai-agent.ts

@@ -84,7 +84,7 @@ async function main() {
       name: "Alice",
       preferences: ["concise answers", "weather updates"],
     },
-    ai: openaiProvider,
+    provider: openaiProvider,
   });
 
   // Add domain knowledge

package/examples/opensearch-persistence.ts

@@ -81,7 +81,7 @@ async function example() {
     name: "Customer Service Agent",
     description: "Handle customer complaints with full-text search",
     goal: "Resolve customer issues efficiently",
-    ai: new GeminiProvider({
+    provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.0-flash-exp",
     }),
@@ -248,7 +248,7 @@ async function example() {
 
   // Load session from OpenSearch
   console.log("\n--- Loading Session from OpenSearch ---");
-  const loadedSession = await persistence.loadSessionStep<ComplaintData>(
+  const loadedSession = await persistence.loadSessionState<ComplaintData>(
     sessionData.id
   );
 
@@ -331,7 +331,7 @@ async function analyticsExample() {
 
   const agent = new Agent({
     name: "Support Analyzer",
-    ai: new GeminiProvider({
+    provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.0-flash-exp",
     }),
@@ -442,7 +442,7 @@ async function timeSeriesExample() {
 
   const agent = new Agent({
     name: "Metrics Agent",
-    ai: new GeminiProvider({
+    provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.0-flash-exp",
     }),

package/examples/persistent-onboarding.ts

@@ -130,7 +130,7 @@ async function createPersistentOnboardingAgent(sessionId: string) {
     name: "OnboardingBot",
     description: "A friendly assistant that helps businesses get started",
     goal: "Collect business information efficiently while being conversational",
-    ai: provider,
+    provider: provider,
     // Context is loaded fresh from database on each respond() call
     contextProvider: async () => {
       console.log("🔄 Loading fresh context from database...");
@@ -359,7 +359,7 @@ async function createOnboardingAgentWithProvider(sessionId: string) {
   const agent = new Agent<OnboardingContext>({
     name: "OnboardingBot",
     description: "A friendly assistant that helps businesses get started",
-    ai: provider,
+    provider: provider,
 
     // Context is always fetched fresh from database
     contextProvider: async () => {

package/examples/prisma-persistence.ts

@@ -85,7 +85,7 @@ async function example() {
     name: "Travel Assistant",
     description: "A helpful travel booking assistant",
     goal: "Help users book flights with ease",
-    ai: new GeminiProvider({
+    provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.0-flash-exp",
     }),
@@ -333,7 +333,7 @@ async function example() {
    * Load session step from database (demonstrates persistence)
    */
   console.log("\n--- Loading Session from Database ---");
-  const loadedSession = await persistence.loadSessionStep<FlightBookingData>(
+  const loadedSession = await persistence.loadSessionState<FlightBookingData>(
     dbSessionId
   );
 
@@ -383,7 +383,7 @@ async function advancedExample() {
   const agent = new Agent<UserContext>({
     name: "Onboarding Assistant",
     description: "Help new users get started",
-    ai: new GeminiProvider({
+    provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.0-flash-exp",
     }),
@@ -517,7 +517,7 @@ async function quickStart() {
 
   const agent = new Agent({
     name: "Support Agent",
-    ai: new GeminiProvider({
+    provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.0-flash-exp",
     }),

package/examples/redis-persistence.ts

@@ -69,7 +69,7 @@ async function example() {
     name: "Support Assistant",
     description: "Fast, real-time support assistant",
     goal: "Help users resolve issues quickly",
-    ai: new GeminiProvider({
+    provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.0-flash-exp",
     }),
@@ -251,7 +251,7 @@ async function example() {
 
   // Load session step from Redis (demonstrates persistence)
   console.log("\n--- Loading Session from Redis ---");
-  const loadedSession = await persistence.loadSessionStep<SupportTicketData>(
+  const loadedSession = await persistence.loadSessionState<SupportTicketData>(
     sessionData.id
   );
 
@@ -281,7 +281,7 @@ async function highThroughputExample() {
   const agent = new Agent({
     name: "Chat Bot",
     description: "Fast chat responses",
-    ai: new GeminiProvider({
+    provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.0-flash-exp",
     }),
@@ -366,7 +366,7 @@ async function sessionRecoveryExample() {
 
   const agent = new Agent({
     name: "Order Assistant",
-    ai: new GeminiProvider({
+    provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.0-flash-exp",
     }),
@@ -433,7 +433,7 @@ async function sessionRecoveryExample() {
   console.log("\n--- User Reconnects ---");
 
   // Load session from Redis
-  const recoveredSession = await persistence.loadSessionStep<OrderData>(
+  const recoveredSession = await persistence.loadSessionState<OrderData>(
     sessionId
   );
 

package/examples/route-transitions.ts

@@ -14,7 +14,7 @@ import {
   createMessageEvent,
   EventSource,
   END_ROUTE,
-  type SessionStep,
+  type SessionState,
 } from "../src/index";
 
 // Type definitions for our booking data
@@ -34,7 +34,7 @@ async function main() {
   const agent = new Agent({
     name: "HotelBot",
     description: "A hotel booking assistant with feedback collection",
-    ai: new GeminiProvider({
+    provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.0-flash-exp",
     }),
@@ -138,7 +138,7 @@ async function main() {
   console.log("\n=== Route Transitions Example ===\n");
 
   // Conversation 1: User provides all booking info at once
-  let session: SessionStep | undefined;
+  let session: SessionState | undefined;
   let history = [
     createMessageEvent(
       EventSource.CUSTOMER,
@@ -209,7 +209,7 @@ async function main() {
   console.log("\n=== Manual Transition Example ===\n");
 
   // Demonstrate manual transition using agent.nextStepRoute()
-  let session2: SessionStep | undefined;
+  let session2: SessionState | undefined;
   let history2 = [
     createMessageEvent(
       EventSource.CUSTOMER,

package/examples/rules-prohibitions.ts

@@ -19,7 +19,7 @@ import { OpenAIProvider } from "../src/providers/OpenAIProvider";
 /**
  * Configuration for the AI provider
  */
-const ai = new OpenAIProvider({
+const provider = new OpenAIProvider({
   apiKey: process.env.OPENAI_API_KEY || "your-api-key-here",
   model: "gpt-5",
 });
@@ -32,7 +32,7 @@ const agent = new Agent({
   description:
     "A versatile customer service agent that adapts its behavior based on the conversation's context.",
   goal: "Provide excellent customer service by following route-specific rules and prohibitions.",
-  ai,
+  provider,
   debug: true,
 });
 
@@ -166,7 +166,7 @@ async function demonstrateRulesAndProhibitions() {
     description:
       "A versatile customer service agent that adapts its behavior based on the conversation's context.",
     goal: "Provide excellent customer service by following route-specific rules and prohibitions.",
-    ai,
+    provider,
     debug: true,
   });
 

package/examples/streaming-agent.ts

@@ -51,7 +51,7 @@ async function streamingWithAnthropic() {
         streamingEnabled: true,
       },
     },
-    ai: provider,
+    provider: provider,
   });
 
   // Add guidelines
@@ -127,7 +127,7 @@ async function streamingWithOpenAI() {
         streamingEnabled: true,
       },
     },
-    ai: provider,
+    provider: provider,
   });
 
   const history = [
@@ -187,7 +187,7 @@ async function streamingWithGemini() {
         streamingEnabled: true,
       },
     },
-    ai: provider,
+    provider: provider,
   });
 
   const history = [
@@ -244,7 +244,7 @@ async function streamingWithRoutes() {
         streamingEnabled: true,
       },
     },
-    ai: provider,
+    provider: provider,
   });
 
   // Create a route
@@ -357,7 +357,7 @@ async function streamingWithAbortSignal() {
         streamingEnabled: true,
       },
     },
-    ai: provider,
+    provider: provider,
   });
 
   const history = [

package/examples/travel-agent.ts

@@ -189,7 +189,7 @@ async function createTravelAgent() {
     description:
       "A knowledgeable travel agent who helps book flights, answer travel questions, and manage reservations.",
     goal: "Help customers book travel and manage their reservations",
-    ai: provider,
+    provider: provider,
     context: {
       customerId: "test-123",
       customerName: "Test Customer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/adapters/MemoryAdapter.ts

@@ -27,7 +27,7 @@ import type {
  *
  * const agent = new Agent({
  *   name: "My Agent",
- *   ai: provider,
+ *   provider: provider,
  *   persistence: {
  *     adapter: new MemoryAdapter(),
  *     userId: "user_123",

package/src/adapters/MongoAdapter.ts

@@ -87,7 +87,7 @@ export interface MongoAdapterOptions {
  *
  * const agent = new Agent({
  *   name: "My Agent",
- *   ai: provider,
+ *   provider: provider,
  *   persistence: {
  *     adapter: new MongoAdapter({
  *       client,

package/src/adapters/PostgreSQLAdapter.ts

@@ -68,7 +68,7 @@ export interface PostgreSQLAdapterOptions {
  *
  * const agent = new Agent({
  *   name: "My Agent",
- *   ai: provider,
+ *   provider: provider,
  *   persistence: {
  *     adapter: new PostgreSQLAdapter({ client }),
  *     userId: "user_123",

package/src/adapters/PrismaAdapter.ts

@@ -107,7 +107,7 @@ export interface PrismaAdapterOptions {
  *
  * const agent = new Agent({
  *   name: "My Agent",
- *   ai: provider,
+ *   provider: provider,
  *   persistence: {
  *     adapter: new PrismaAdapter({ prisma }),
  *     userId: "user_123",

package/src/adapters/RedisAdapter.ts

@@ -64,7 +64,7 @@ export interface RedisAdapterOptions {
  *
  * const agent = new Agent({
  *   name: "My Agent",
- *   ai: provider,
+ *   provider: provider,
  *   persistence: {
  *     adapter: new RedisAdapter({ redis }),
  *     userId: "user_123",

package/src/adapters/SQLiteAdapter.ts

@@ -60,7 +60,7 @@ export interface SQLiteAdapterOptions {
  *
  * const agent = new Agent({
  *   name: "My Agent",
- *   ai: provider,
+ *   provider: provider,
  *   persistence: {
  *     adapter: new SQLiteAdapter({ db }),
  *     userId: "user_123",