@falai/agent 0.7.0 → 0.8.0

package/docs/DOMAINS.md

@@ -32,7 +32,7 @@ Domains provide **optional** security and organization for your tools. If you ne
 ```typescript
 const agent = new Agent({
   name: "Simple Agent",
-  ai: provider,
+  provider: provider,
 });
 
 // Define tools however you want
@@ -57,7 +57,7 @@ route.initialStep
 ```typescript
 const agent = new Agent({
   name: "Production Agent",
-  ai: provider,
+  provider: provider,
 });
 
 // 1️⃣ Organize tools into domains

package/docs/EXAMPLES.md

@@ -68,7 +68,7 @@ Comprehensive example showing declarative agent configuration:
 ```typescript
 const agent = new Agent({
   name: "HealthBot",
-  ai: provider,
+  provider: provider,
   terms: [...],
   guidelines: [...],
   routes: [{

package/docs/GETTING_STARTED.md

@@ -65,7 +65,7 @@ interface MyContext {
 }
 
 // Create AI provider
-const ai = new GeminiProvider({
+const provider = new GeminiProvider({
   apiKey: process.env.GEMINI_API_KEY!,
   model: "models/gemini-2.5-pro",
 });
@@ -74,7 +74,7 @@ const ai = new GeminiProvider({
 const agent = new Agent<MyContext>({
   name: "FlightBot",
   description: "A helpful flight booking assistant",
-  ai,
+  provider,
   context: {
     userId: "user_123",
     userName: "Alice",
@@ -252,7 +252,7 @@ Load everything from config:
 ```typescript
 const agent = new Agent({
   name: "ConfiguredBot",
-  ai: provider,
+  provider: provider,
   terms: loadTermsFromFile(),
   guidelines: loadGuidelinesFromDB(),
   routes: [

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,
@@ -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 }),
   },

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

@@ -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",
     }),
@@ -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",
     }),
@@ -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",
     }),
@@ -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",
     }),
@@ -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",
     }),

package/examples/route-transitions.ts

@@ -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",
     }),

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.0",
   "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",

package/src/core/Agent.ts

@@ -412,7 +412,7 @@ export class Agent<TContext = unknown> {
           description: this.options.description,
           personality: this.options.personality,
         },
-        ai: this.options.ai,
+        provider: this.options.provider,
         context: effectiveContext,
         signal,
       });
@@ -491,7 +491,7 @@ export class Agent<TContext = unknown> {
       );
 
       // Generate message stream using AI provider
-      const stream = this.options.ai.generateMessageStream({
+      const stream = this.options.provider.generateMessageStream({
         prompt: responsePrompt,
         history,
         context: effectiveContext,
@@ -612,7 +612,7 @@ export class Agent<TContext = unknown> {
       );
 
       // Stream completion message using AI provider
-      const stream = this.options.ai.generateMessageStream({
+      const stream = this.options.provider.generateMessageStream({
         prompt: completionPrompt,
         history,
         context: effectiveContext,
@@ -698,7 +698,7 @@ export class Agent<TContext = unknown> {
         .addCapabilities(this.capabilities)
         .build();
 
-      const stream = this.options.ai.generateMessageStream({
+      const stream = this.options.provider.generateMessageStream({
         prompt: fallbackPrompt,
         history,
         context: effectiveContext,
@@ -872,7 +872,7 @@ export class Agent<TContext = unknown> {
           description: this.options.description,
           personality: this.options.personality,
         },
-        ai: this.options.ai,
+        provider: this.options.provider,
         context: effectiveContext,
         signal,
       });
@@ -956,7 +956,7 @@ export class Agent<TContext = unknown> {
       );
 
       // Generate message using AI provider
-      const result = await this.options.ai.generateMessage({
+      const result = await this.options.provider.generateMessage({
         prompt: responsePrompt,
         history,
         context: effectiveContext,
@@ -1044,7 +1044,7 @@ export class Agent<TContext = unknown> {
       );
 
       // Generate completion message using AI provider
-      const completionResult = await this.options.ai.generateMessage({
+      const completionResult = await this.options.provider.generateMessage({
         prompt: completionPrompt,
         history,
         context: effectiveContext,
@@ -1115,7 +1115,7 @@ export class Agent<TContext = unknown> {
         .addCapabilities(this.capabilities)
         .build();
 
-      const result = await this.options.ai.generateMessage({
+      const result = await this.options.provider.generateMessage({
         prompt: fallbackPrompt,
         history,
         context: effectiveContext,

package/src/core/RoutingEngine.ts

@@ -50,7 +50,7 @@ export class RoutingEngine<TContext = unknown> {
       description?: string;
       personality?: string;
     };
-    ai: AiProvider;
+    provider: AiProvider;
     context: TContext;
     signal?: AbortSignal;
   }): Promise<{
@@ -60,7 +60,8 @@ export class RoutingEngine<TContext = unknown> {
     session: SessionStep;
     isRouteComplete?: boolean;
   }> {
-    const { route, session, history, agentMeta, ai, context, signal } = params;
+    const { route, session, history, agentMeta, provider, context, signal } =
+      params;
 
     let updatedSession = session;
     const selectedRoute = route;
@@ -138,7 +139,7 @@ export class RoutingEngine<TContext = unknown> {
       candidates.map((c) => c.step.id)
     );
 
-    const stepResult = await ai.generateMessage<
+    const stepResult = await provider.generateMessage<
       TContext,
       {
         reasoning: string;
@@ -411,7 +412,7 @@ export class RoutingEngine<TContext = unknown> {
       description?: string;
       personality?: string;
     };
-    ai: AiProvider;
+    provider: AiProvider;
     context: TContext;
     signal?: AbortSignal;
   }): Promise<{
@@ -421,7 +422,8 @@ export class RoutingEngine<TContext = unknown> {
     session: SessionStep;
     isRouteComplete?: boolean;
   }> {
-    const { routes, session, history, agentMeta, ai, context, signal } = params;
+    const { routes, session, history, agentMeta, provider, context, signal } =
+      params;
 
     if (routes.length === 0) {
       return { session };
@@ -434,7 +436,7 @@ export class RoutingEngine<TContext = unknown> {
         session,
         history,
         agentMeta,
-        ai,
+        provider,
         context,
         signal,
       });
@@ -504,7 +506,7 @@ export class RoutingEngine<TContext = unknown> {
       activeRouteSteps
     );
 
-    const routingResult = await ai.generateMessage<
+    const routingResult = await provider.generateMessage<
       TContext,
       RoutingDecisionOutput
     >({

package/src/types/agent.ts

@@ -86,7 +86,7 @@ export interface AgentOptions<TContext = unknown> {
   /** Lifecycle hooks for context management */
   hooks?: ContextLifecycleHooks<TContext>;
   /** AI provider strategy for generating responses */
-  ai: AiProvider;
+  provider: AiProvider;
   /** Composition mode for response generation */
   compositionMode?: CompositionMode;
   /** Initial terms for domain glossary */