@falai/agent 0.3.10 → 0.3.12

package/README.md

@@ -34,7 +34,7 @@
 ### 🚀 **Production Ready**
 
 - **Robust Retry Logic** - Exponential backoff & backup models
-- **AI Provider Strategy** - Pluggable backends (Gemini, OpenAI, OpenRouter)
+- **AI Provider Strategy** - Pluggable backends (Claude, Gemini, OpenAI, OpenRouter)
 - **Prompt Composition** - Sophisticated prompt building system
 
 </td>
@@ -57,6 +57,27 @@
 - **Domain Registry** - Organize capabilities by domain
 - **Context Awareness** - Tools receive typed context automatically
 
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 💾 **Optional Persistence**
+
+- **Provider Pattern** - Simple API like AI providers
+- **Prisma Ready** - Built-in ORM adapter
+- **Auto-save** - Automatic session & message persistence
+- **Extensible** - Create adapters for any database
+
+</td>
+<td width="50%">
+
+### 🎯 **Smart Routing**
+
+- **Deterministic IDs** - Consistent identifiers across restarts
+- **Route Scoping** - Control tool access per route
+- **Rules & Prohibitions** - Fine-grained behavior control
+
 </td>
 </tr>
 </table>
@@ -87,8 +108,10 @@ Get up and running in 60 seconds:
 ```typescript
 import {
   Agent,
+  AnthropicProvider,
   GeminiProvider,
-  OpenAIProvider, // or use OpenAI
+  OpenAIProvider,
+  OpenRouterProvider,
   createMessageEvent,
   EventSource,
 } from "@falai/agent";
@@ -101,15 +124,25 @@ interface SupportContext {
 }
 
 // 2️⃣ Create AI provider (choose one)
-const ai = new GeminiProvider({
-  apiKey: process.env.GEMINI_API_KEY!,
-  model: "models/gemini-2.5-flash",
+const ai = new AnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: "claude-sonnet-4-5",
 });
 
-// Or use OpenAI:
+// Or use other providers:
+// const ai = new GeminiProvider({
+//   apiKey: process.env.GEMINI_API_KEY!,
+//   model: "models/gemini-2.5-flash",
+// });
+
 // const ai = new OpenAIProvider({
 //   apiKey: process.env.OPENAI_API_KEY!,
-//   model: "gpt-5", // Required - specify your model
+//   model: "gpt-5",
+// });
+
+// const ai = new OpenRouterProvider({
+//   apiKey: process.env.OPENROUTER_API_KEY!,
+//   model: "anthropic/claude-sonnet-4-5", // Access to 200+ models
 // });
 
 // 3️⃣ Initialize your agent - two ways!
@@ -174,6 +207,36 @@ const response = await agent.respond({
 console.log(response.message); // 🎉 AI-powered response ready!
 ```
 
+### ⚡ Streaming Responses (NEW!)
+
+Stream AI responses in real-time for better user experience:
+
+```typescript
+// Use respondStream for real-time streaming
+for await (const chunk of agent.respondStream({ history })) {
+  // chunk.delta contains the new text
+  process.stdout.write(chunk.delta);
+
+  if (chunk.done) {
+    // Stream complete - access final metadata
+    console.log("\n✅ Complete!");
+    console.log("Route:", chunk.route?.title);
+    console.log("Tool calls:", chunk.toolCalls?.length);
+  }
+}
+```
+
+**Benefits:**
+
+- ✨ Real-time response generation
+- 🎯 Better perceived performance
+- 🛑 Cancellable with AbortSignal
+- 📊 Access to route/state/tool information in final chunk
+
+**Supported Providers:** All providers support streaming (Anthropic, OpenAI, Gemini, OpenRouter)
+
+See [streaming-agent.ts](./examples/streaming-agent.ts) for complete examples.
+
 ---
 
 ## 📚 Documentation
@@ -183,6 +246,7 @@ console.log(response.message); // 🎉 AI-powered response ready!
 - **[Getting Started](./docs/GETTING_STARTED.md)** - Your first agent in 5 minutes
 - **[Constructor Options](./docs/CONSTRUCTOR_OPTIONS.md)** - Declarative vs Fluent API patterns
 - **[Context Management](./docs/CONTEXT_MANAGEMENT.md)** - Persistent conversations & state management
+- **[Persistence](./docs/PERSISTENCE.md)** - Optional database persistence with Prisma **(NEW!)**
 - **[API Reference](./docs/API_REFERENCE.md)** - Complete API documentation
 - **[Architecture](./docs/STRUCTURE.md)** - Package structure and design principles
 
@@ -553,6 +617,66 @@ const saveTool = defineTool("save_data", async (ctx, data) => {
 
 See [Context Management Guide](./docs/CONTEXT_MANAGEMENT.md) for complete patterns and best practices.
 
+### 💾 Optional Database Persistence (NEW!)
+
+For **production applications** that need to persist sessions and messages:
+
+```typescript
+import { Agent, PrismaAdapter } from "@falai/agent";
+import { PrismaClient } from "@prisma/client";
+
+const prisma = new PrismaClient();
+
+const agent = new Agent({
+  name: "My Agent",
+  ai: provider,
+  // ✨ Just add this!
+  persistence: {
+    adapter: new PrismaAdapter({ prisma }),
+    autoSave: true,
+    userId: "user_123",
+  },
+});
+
+// Access persistence manager
+const persistence = agent.getPersistenceManager();
+
+// Create a session
+const session = await persistence.createSession({
+  userId: "user_123",
+  agentName: "My Agent",
+});
+
+// Load history
+const history = await persistence.loadSessionHistory(session.id);
+
+// Generate response
+const response = await agent.respond({ history });
+
+// Optionally Save message (automatically saves if autoSave: true)
+await persistence.saveMessage({
+  sessionId: session.id,
+  role: "agent",
+  content: response.message,
+});
+```
+
+**Features:**
+
+- ✅ **Provider Pattern** - Simple API like AI providers
+- ✅ **Prisma Built-in** - Ready-to-use ORM adapter
+- ✅ **Auto-save** - Automatic message tracking
+- ✅ **Custom Adapters** - Create for any database (MongoDB, Redis, etc.)
+- ✅ **Lifecycle Integration** - Works seamlessly with context hooks
+
+**Setup (3 steps):**
+
+1. Install: `npm install @prisma/client prisma`
+2. Copy schema from `examples/prisma-schema.example.prisma`
+3. Run: `npx prisma generate && npx prisma migrate dev`
+
+See [Persistence Guide](./docs/PERSISTENCE.md) for complete documentation and custom adapter examples.
+
 ### 📖 Domain Glossary
 
 Teach your agent business-specific language:
@@ -616,9 +740,27 @@ const event = createMessageEvent(
 
 ### ⚙️ Advanced Configuration
 
-Fine-tune AI provider behavior - works with both Gemini and OpenAI:
+Fine-tune AI provider behavior - works with all providers:
 
 ```typescript
+// Anthropic (Claude) configuration
+const anthropicProvider = new AnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: "claude-sonnet-4-5", // Primary model
+  backupModels: [
+    "claude-opus-4-1", // Backup if primary fails
+    "claude-sonnet-4-0", // Stable fallback
+  ],
+  config: {
+    temperature: 0.7,
+    top_p: 0.9,
+  },
+  retryConfig: {
+    timeout: 60000, // 60s timeout
+    retries: 3, // 3 attempts with exponential backoff
+  },
+});
+
 // Gemini configuration
 const geminiProvider = new GeminiProvider({
   apiKey: process.env.GEMINI_API_KEY!,
@@ -628,8 +770,8 @@ const geminiProvider = new GeminiProvider({
     "models/gemini-2.0-flash",
   ],
   retryConfig: {
-    timeout: 60000, // 60s timeout
-    retries: 3, // 3 attempts with exponential backoff
+    timeout: 60000,
+    retries: 3,
   },
 });
 
@@ -643,6 +785,19 @@ const openaiProvider = new OpenAIProvider({
     retries: 3,
   },
 });
+
+// OpenRouter configuration (access to 200+ models)
+const openrouterProvider = new OpenRouterProvider({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "anthropic/claude-sonnet-4-5",
+  backupModels: ["openai/gpt-5", "google/gemini-2.5-flash"],
+  siteUrl: "https://yourapp.com",
+  siteName: "Your App Name",
+  retryConfig: {
+    timeout: 60000,
+    retries: 3,
+  },
+});
 ```
 
 ---
@@ -658,6 +813,16 @@ const openaiProvider = new OpenAIProvider({
 - 🔗 Route references by title in observations
 - ➕ Dynamic additions after construction
 
+### ⚡ [Streaming Responses](./examples/streaming-agent.ts) **(NEW!)**
+
+**Real-time streaming responses for better UX:**
+
+- 🌊 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
+- 🎯 5 comprehensive examples covering different use cases
+
 ### 💾 [Persistent Onboarding Agent](./examples/persistent-onboarding.ts)
 
 **Multi-turn conversation with state persistence:**
@@ -668,6 +833,16 @@ const openaiProvider = new OpenAIProvider({
 - 🔧 Two approaches: lifecycle hooks vs context provider
 - 📝 Complete onboarding flow across multiple turns
 
+### 💾 [Prisma Persistence](./examples/prisma-persistence.ts) **(NEW!)**
+
+**Production-ready database persistence:**
+
+- ✨ Provider pattern - simple as `new PrismaAdapter({ prisma })`
+- 🗄️ Automatic session and message persistence
+- 🔄 Seamless lifecycle hook integration
+- 📊 Complete examples: basic, advanced, and minimal
+- 🎯 3-step setup with Prisma ORM
+
 ### 🏢 [Business Onboarding](./examples/business-onboarding.ts)
 
 **Production-ready business onboarding with advanced patterns:**
@@ -699,13 +874,14 @@ Healthcare-focused agent demonstrating:
 - 🔐 Sensitive data handling
 - ⚠️ Urgent case prioritization
 
-### 🌐 [OpenAI Agent](./examples/openai-agent.ts)
+### 🌐 Multiple Provider Examples
 
-Using OpenAI provider instead of Gemini:
+See how different AI providers work:
 
-- 🤖 OpenAI GPT-5 integration
-- 🔄 Backup model configuration
-- ⚙️ Custom retry settings
+- **[OpenAI Agent](./examples/openai-agent.ts)** - GPT-5 integration
+- **[Healthcare Agent](./examples/healthcare-agent.ts)** - Claude 3.5 Sonnet
+- **[Travel Agent](./examples/travel-agent.ts)** - OpenRouter with backup models
+- 🔄 All with backup model configuration and retry settings
 - 🌤️ Weather checking example
 
 ### 🔐 [Domain Scoping](./examples/domain-scoping.ts)
@@ -734,7 +910,7 @@ Control agent behavior and communication style per route:
 src/
 ├── types/          # Type definitions (strongly typed contracts)
 ├── core/           # Core framework (Agent, Route, State, Tools, etc.)
-├── providers/      # AI providers (Gemini with retry/backup logic)
+├── providers/      # AI providers (Anthropic, Gemini, OpenAI, OpenRouter)
 ├── utils/          # Utilities (retry, timeout, helpers)
 ├── constants/      # Constants (END_ROUTE, symbols)
 └── index.ts        # Public API exports

package/dist/adapters/PrismaAdapter.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Prisma adapter for persistence
+ * Simple, provider-like API with automatic schema creation
+ */
+import type { SessionRepository, MessageRepository, SessionData, MessageData, PersistenceAdapter } from "../types/persistence";
+/**
+ * Prisma model operations
+ */
+export interface PrismaModel {
+    create: (params: {
+        data: Record<string, unknown>;
+    }) => Promise<Record<string, unknown>>;
+    findUnique: (params: {
+        where: Record<string, unknown>;
+    }) => Promise<Record<string, unknown> | null>;
+    findFirst: (params: {
+        where: Record<string, unknown>;
+        orderBy?: Record<string, string>;
+    }) => Promise<Record<string, unknown> | null>;
+    findMany: (params: {
+        where: Record<string, unknown>;
+        orderBy?: Record<string, string>;
+        take?: number;
+    }) => Promise<Array<Record<string, unknown>>>;
+    update: (params: {
+        where: Record<string, unknown>;
+        data: Record<string, unknown>;
+    }) => Promise<Record<string, unknown>>;
+    delete: (params: {
+        where: Record<string, unknown>;
+    }) => Promise<Record<string, unknown>>;
+    deleteMany: (params: {
+        where: Record<string, unknown>;
+    }) => Promise<{
+        count: number;
+    }>;
+}
+/**
+ * Prisma client interface - matches the shape of a generated Prisma client
+ */
+export interface PrismaClient extends Record<string, unknown> {
+    $queryRaw?: <T = unknown>(query: TemplateStringsArray | string, ...values: unknown[]) => Promise<T>;
+    $executeRaw?: (query: TemplateStringsArray | string, ...values: unknown[]) => Promise<number>;
+    $disconnect?: () => Promise<void>;
+}
+/**
+ * Configuration for field mappings
+ */
+export interface FieldMappings {
+    sessions?: Partial<Record<keyof SessionData, string>>;
+    messages?: Partial<Record<keyof MessageData, string>>;
+}
+/**
+ * Options for creating a Prisma adapter
+ */
+export interface PrismaAdapterOptions {
+    /**
+     * Prisma client instance
+     */
+    prisma: PrismaClient;
+    /**
+     * Table/model names (defaults to 'agentSession' and 'agentMessage')
+     */
+    tables?: {
+        sessions?: string;
+        messages?: string;
+    };
+    /**
+     * Field mappings (optional, if your schema uses different field names)
+     */
+    fieldMappings?: FieldMappings;
+    /**
+     * Whether to auto-create tables if they don't exist (default: false)
+     * Note: Only works if your Prisma client has $executeRaw method
+     */
+    autoMigrate?: boolean;
+}
+/**
+ * Prisma Adapter - Provider-style API for Prisma persistence
+ *
+ * @example
+ * ```typescript
+ * import { PrismaClient } from '@prisma/client';
+ * import { Agent, PrismaAdapter } from '@falai/agent';
+ *
+ * const prisma = new PrismaClient();
+ *
+ * const agent = new Agent({
+ *   name: "My Agent",
+ *   ai: provider,
+ *   persistence: {
+ *     adapter: new PrismaAdapter({ prisma }),
+ *     userId: "user_123",
+ *   },
+ * });
+ * ```
+ */
+export declare class PrismaAdapter implements PersistenceAdapter {
+    readonly sessionRepository: SessionRepository;
+    readonly messageRepository: MessageRepository;
+    private prisma;
+    private options;
+    private initialized;
+    constructor(options: PrismaAdapterOptions);
+    /**
+     * Initialize the adapter (check/create tables)
+     * Called automatically if autoMigrate is enabled
+     */
+    initialize(): Promise<void>;
+    /**
+     * Disconnect from the database
+     */
+    disconnect(): Promise<void>;
+}
+//# sourceMappingURL=PrismaAdapter.d.ts.map

package/dist/adapters/PrismaAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrismaAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/PrismaAdapter.ts"],"names":[],"mappings":"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"}