@falai/agent 0.3.10 → 0.3.12

package/docs/API_REFERENCE.md

@@ -109,6 +109,107 @@ if (response.route?.title === END_ROUTE) {
 }
 ```
 
+##### `respondStream(input: RespondInput<TContext>): AsyncGenerator<StreamChunk>`
+
+Generates an AI response as a real-time stream for better user experience. Provides the same structured output as `respond()` but delivers it incrementally.
+
+```typescript
+interface StreamChunk {
+  /** The incremental text delta */
+  delta: string;
+  /** Full accumulated text so far */
+  accumulated: string;
+  /** Whether this is the final chunk */
+  done: boolean;
+  /** Route chosen by the agent (only in final chunk) */
+  route?: { id: string; title: string };
+  /** Current state within the route (only in final chunk) */
+  state?: { id: string; description?: string };
+  /** Tool calls requested by the agent (only in final chunk) */
+  toolCalls?: Array<{
+    toolName: string;
+    arguments: Record<string, unknown>;
+  }>;
+}
+```
+
+**Key Features:**
+
+- 🌊 Real-time streaming for better perceived performance
+- 📊 Access to route, state, and tool information in final chunk
+- 🛑 Cancellable with AbortSignal
+- ✅ Supported by all providers (Anthropic, OpenAI, Gemini, OpenRouter)
+
+**Example:**
+
+```typescript
+// Basic streaming
+for await (const chunk of agent.respondStream({ history })) {
+  if (chunk.delta) {
+    // Display incremental text to user
+    process.stdout.write(chunk.delta);
+  }
+
+  if (chunk.done) {
+    console.log("\n✅ Complete!");
+    // Access final metadata
+    if (chunk.route) {
+      console.log("Route:", chunk.route.title);
+    }
+    if (chunk.toolCalls) {
+      console.log("Tool calls:", chunk.toolCalls.length);
+    }
+  }
+}
+```
+
+**With Cancellation:**
+
+```typescript
+const abortController = new AbortController();
+
+// Cancel after 5 seconds
+setTimeout(() => abortController.abort(), 5000);
+
+try {
+  for await (const chunk of agent.respondStream({
+    history,
+    signal: abortController.signal,
+  })) {
+    console.log(chunk.delta);
+  }
+} catch (error) {
+  if (error.name === "AbortError") {
+    console.log("Stream cancelled");
+  }
+}
+```
+
+**Collecting Full Response:**
+
+```typescript
+let fullMessage = "";
+let finalChunk;
+
+for await (const chunk of agent.respondStream({ history })) {
+  fullMessage += chunk.delta;
+  if (chunk.done) {
+    finalChunk = chunk;
+  }
+}
+
+// Save to database
+await db.agentMessages.create({
+  sessionId: session.id,
+  role: "agent",
+  content: fullMessage,
+  route: finalChunk.route?.title,
+  toolCalls: finalChunk.toolCalls || [],
+});
+```
+
+**See Also:** [streaming-agent.ts](../examples/streaming-agent.ts) for comprehensive examples.
+
 #### Properties
 
 ##### `name: string`
@@ -366,11 +467,15 @@ Returns filtered domains by names. If `allowedNames` is `undefined`, returns all
 const registry = new DomainRegistry();
 
 registry.register("payment", {
-  processPayment: async (amount: number) => { /* ... */ },
+  processPayment: async (amount: number) => {
+    /* ... */
+  },
 });
 
 registry.register("shipping", {
-  calculateShipping: (zipCode: string) => { /* ... */ },
+  calculateShipping: (zipCode: string) => {
+    /* ... */
+  },
 });
 
 // Get specific domains
@@ -386,6 +491,61 @@ Returns list of all registered domain names.
 
 ---
 
+### `AnthropicProvider`
+
+AI provider implementation for Anthropic (Claude models).
+
+#### Constructor
+
+```typescript
+new AnthropicProvider(options: AnthropicProviderOptions)
+
+interface AnthropicProviderOptions {
+  apiKey: string;
+  model: string;               // Required: e.g., "claude-sonnet-4-5"
+  backupModels?: string[];     // Fallback models
+  config?: Partial<Omit<MessageCreateParamsNonStreaming, "model" | "messages" | "max_tokens">>;
+  retryConfig?: {
+    timeout?: number;          // Default: 60000ms
+    retries?: number;          // Default: 3
+  };
+}
+```
+
+**Note:** `model` is required for AnthropicProvider. Available models include:
+
+- `claude-sonnet-4-5` - Latest Claude Sonnet 4.5 (most capable)
+- `claude-opus-4-1` - Claude Opus 4.1 (powerful for complex tasks)
+- `claude-sonnet-4-0` - Claude Sonnet 4.0 (stable, production-ready)
+
+#### Methods
+
+##### `generateMessage<TContext>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>`
+
+Generates a message with retry logic and backup models using Anthropic's API.
+
+**Example:**
+
+```typescript
+import { AnthropicProvider } from "@falai/agent";
+
+const provider = new AnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: "claude-sonnet-4-5",
+  backupModels: ["claude-opus-4-1", "claude-sonnet-4-0"],
+  config: {
+    temperature: 0.7,
+    top_p: 0.9,
+  },
+  retryConfig: {
+    timeout: 60000,
+    retries: 3,
+  },
+});
+```
+
+---
+
 ### `GeminiProvider`
 
 AI provider implementation for Google Gemini.
@@ -414,6 +574,104 @@ Generates a message with retry logic and backup models.
 
 ---
 
+### `OpenAIProvider`
+
+AI provider implementation for OpenAI (GPT models).
+
+#### Constructor
+
+```typescript
+new OpenAIProvider(options: OpenAIProviderOptions)
+
+interface OpenAIProviderOptions {
+  apiKey: string;
+  model: string;               // Required: e.g., "gpt-4o", "gpt-5"
+  backupModels?: string[];     // Fallback models
+  retryConfig?: {
+    timeout?: number;          // Default: 60000ms
+    retries?: number;          // Default: 3
+  };
+}
+```
+
+**Note:** Unlike GeminiProvider, `model` is required for OpenAIProvider. Choose from available OpenAI models like "gpt-4o", "gpt-5", "gpt-4-turbo", etc.
+
+#### Methods
+
+##### `generateMessage<TContext>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>`
+
+Generates a message with retry logic and backup models using OpenAI's API.
+
+**Example:**
+
+```typescript
+import { OpenAIProvider } from "@falai/agent";
+
+const provider = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5",
+  backupModels: ["gpt-4o", "gpt-4-turbo"],
+  retryConfig: {
+    timeout: 60000,
+    retries: 3,
+  },
+});
+```
+
+---
+
+### `OpenRouterProvider`
+
+AI provider implementation for OpenRouter (access to 200+ models).
+
+#### Constructor
+
+```typescript
+new OpenRouterProvider(options: OpenRouterProviderOptions)
+
+interface OpenRouterProviderOptions {
+  apiKey: string;
+  model: string;               // Required: e.g., "openai/gpt-5", "anthropic/claude-sonnet-4-5"
+  backupModels?: string[];     // Fallback models
+  siteUrl?: string;            // Optional: your app URL for OpenRouter rankings
+  siteName?: string;           // Optional: your app name for OpenRouter rankings
+  retryConfig?: {
+    timeout?: number;          // Default: 60000ms
+    retries?: number;          // Default: 3
+  };
+}
+```
+
+**Note:** OpenRouter provides access to models from multiple providers. Model names follow the format `provider/model-name` (e.g., "openai/gpt-5", "anthropic/claude-sonnet-4-5", "google/gemini-pro").
+
+#### Methods
+
+##### `generateMessage<TContext>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>`
+
+Generates a message with retry logic and backup models using OpenRouter's API.
+
+**Example:**
+
+```typescript
+import { OpenRouterProvider } from "@falai/agent";
+
+const provider = new OpenRouterProvider({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "openai/gpt-5",
+  backupModels: ["anthropic/claude-sonnet-4-5", "google/gemini-pro"],
+  siteUrl: "https://yourapp.com",
+  siteName: "Your App Name",
+  retryConfig: {
+    timeout: 60000,
+    retries: 3,
+  },
+});
+```
+
+**See Also:** [Providers Guide](./PROVIDERS.md) for detailed provider comparison and configuration examples.
+
+---
+
 ### `PromptBuilder`
 
 Constructs prompts for AI generation.

package/docs/PERSISTENCE.md

@@ -0,0 +1,419 @@
+# Persistence with @falai/agent
+
+The `@falai/agent` framework provides optional, flexible persistence for automatically saving conversation sessions and messages to your database.
+
+## Features
+
+- ✅ **Optional** - Persistence is completely optional
+- ✅ **Provider Pattern** - Simple API like AI providers (`new PrismaAdapter({ prisma })`)
+- ✅ **Type-safe** - Full TypeScript support
+- ✅ **Prisma Ready** - Built-in Prisma ORM adapter
+- ✅ **Extensible** - Create adapters for any database
+- ✅ **Auto-save** - Automatic message persistence
+
+## Quick Start with Prisma
+
+### 1. Install Dependencies
+
+```bash
+npm install @prisma/client prisma
+npx prisma init
+```
+
+### 2. Set Up Schema
+
+Copy this schema to `prisma/schema.prisma`:
+
+```prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+model AgentSession {
+  id              String    @id @default(cuid())
+  userId          String?   @map("user_id")
+  agentName       String?   @map("agent_name")
+  status          String    @default("active")
+  currentRoute    String?   @map("current_route")
+  currentState    String?   @map("current_state")
+  collectedData   Json?     @map("collected_data")
+  messageCount    Int       @default(0) @map("message_count")
+  lastMessageAt   DateTime? @map("last_message_at")
+  completedAt     DateTime? @map("completed_at")
+  createdAt       DateTime  @default(now()) @map("created_at")
+  updatedAt       DateTime  @updatedAt @map("updated_at")
+
+  messages AgentMessage[]
+
+  @@index([userId, status])
+  @@map("agent_sessions")
+}
+
+model AgentMessage {
+  id        String   @id @default(cuid())
+  sessionId String   @map("session_id")
+  userId    String?  @map("user_id")
+  role      String
+  content   String   @db.Text
+  route     String?
+  state     String?
+  toolCalls Json?    @map("tool_calls")
+  event     Json?
+  createdAt DateTime @default(now()) @map("created_at")
+
+  session AgentSession @relation(fields: [sessionId], references: [id], onDelete: Cascade)
+
+  @@index([sessionId])
+  @@map("agent_messages")
+}
+```
+
+### 3. Generate and Migrate
+
+```bash
+npx prisma generate
+npx prisma migrate dev --name init
+```
+
+### 4. Use in Your Agent (That's it!)
+
+```typescript
+import { Agent, PrismaAdapter, GeminiProvider } from "@falai/agent";
+import { PrismaClient } from "@prisma/client";
+
+const prisma = new PrismaClient();
+
+const agent = new Agent({
+  name: "My Agent",
+  ai: new GeminiProvider({ apiKey: "..." }),
+  // ✨ Just add this!
+  persistence: {
+    adapter: new PrismaAdapter({ prisma }),
+    userId: "user_123",
+  },
+});
+
+// Access persistence methods
+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 });
+
+// Save message (auto-saved if configured)
+await persistence.saveMessage({
+  sessionId: session.id,
+  role: "agent",
+  content: response.message,
+});
+```
+
+## Configuration Options
+
+### Basic Configuration
+
+```typescript
+new PrismaAdapter({
+  prisma: prismaClient, // Required: Your Prisma client
+});
+```
+
+### Custom Table Names
+
+```typescript
+new PrismaAdapter({
+  prisma,
+  tables: {
+    sessions: "myCustomSessions",
+    messages: "myCustomMessages",
+  },
+});
+```
+
+### Custom Field Mappings
+
+If your database uses different field names:
+
+```typescript
+new PrismaAdapter({
+  prisma,
+  fieldMappings: {
+    sessions: {
+      userId: "user_id",
+      createdAt: "created_at",
+      updatedAt: "updated_at",
+    },
+    messages: {
+      sessionId: "session_id",
+      createdAt: "created_at",
+    },
+  },
+});
+```
+
+## Auto-Save Messages
+
+Enable automatic message persistence:
+
+```typescript
+const agent = new Agent({
+  name: "My Agent",
+  ai: provider,
+  persistence: {
+    adapter: new PrismaAdapter({ prisma }),
+    autoSave: true, // Default: true
+    userId: "user_123",
+  },
+});
+```
+
+## Using with Lifecycle Hooks
+
+The most powerful pattern - auto-sync context with database:
+
+```typescript
+const agent = new Agent({
+  name: "Smart Assistant",
+  ai: provider,
+  context: {
+    userId: "user_123",
+    sessionId: session.id,
+    preferences: { theme: "light" },
+  },
+  hooks: {
+    // Load fresh context before each response
+    beforeRespond: async (ctx) => {
+      const persistence = agent.getPersistenceManager();
+      const session = await persistence?.getSession(ctx.sessionId);
+      return {
+        ...ctx,
+        preferences: session?.collectedData?.preferences || ctx.preferences,
+      };
+    },
+    // Auto-save context updates
+    onContextUpdate: async (ctx) => {
+      const persistence = agent.getPersistenceManager();
+      await persistence?.updateCollectedData(ctx.sessionId, {
+        preferences: ctx.preferences,
+      });
+    },
+  },
+  persistence: {
+    adapter: new PrismaAdapter({ prisma }),
+  },
+});
+
+// Now context updates are automatically persisted!
+await agent.updateContext({ preferences: { theme: "dark" } });
+```
+
+## PersistenceManager API
+
+Access via `agent.getPersistenceManager()`:
+
+### Session Methods
+
+```typescript
+// Create session
+await persistence.createSession({
+  userId: "user_123",
+  agentName: "My Agent",
+  initialData: { key: "value" },
+});
+
+// Get session
+await persistence.getSession(sessionId);
+
+// Find active session for user
+await persistence.findActiveSession(userId);
+
+// Get all user sessions
+await persistence.getUserSessions(userId);
+
+// Update session
+await persistence.updateSessionStatus(sessionId, "completed");
+await persistence.updateCollectedData(sessionId, { key: "value" });
+await persistence.updateRouteState(sessionId, routeId, stateId);
+
+// Complete/abandon session
+await persistence.completeSession(sessionId);
+await persistence.abandonSession(sessionId);
+
+// Delete session
+await persistence.deleteSession(sessionId);
+```
+
+### Message Methods
+
+```typescript
+// Save message
+await persistence.saveMessage({
+  sessionId: session.id,
+  userId: "user_123",
+  role: "user" | "agent" | "system",
+  content: "Hello!",
+  route: "route_id",
+  state: "state_id",
+  toolCalls: [...],
+});
+
+// Get messages
+await persistence.getSessionMessages(sessionId);
+await persistence.getUserMessages(userId);
+
+// Load as Event history
+await persistence.loadSessionHistory(sessionId);
+```
+
+## Creating Custom Adapters
+
+Create adapters for any database:
+
+```typescript
+import { PersistenceAdapter, SessionRepository, MessageRepository } from "@falai/agent";
+
+class MyDatabaseAdapter implements PersistenceAdapter {
+  public readonly sessionRepository: SessionRepository;
+  public readonly messageRepository: MessageRepository;
+
+  constructor(config: MyConfig) {
+    this.sessionRepository = new MySessionRepository(config);
+    this.messageRepository = new MyMessageRepository(config);
+  }
+
+  async initialize?(): Promise<void> {
+    // Optional: Setup tables/indexes
+  }
+
+  async disconnect?(): Promise<void> {
+    // Optional: Cleanup
+  }
+}
+
+// Use it
+const agent = new Agent({
+  persistence: {
+    adapter: new MyDatabaseAdapter({ ... }),
+  },
+});
+```
+
+## Examples
+
+### Complete Example
+
+See `examples/prisma-persistence.ts` for a full working example.
+
+### Minimal Example
+
+```typescript
+import { Agent, PrismaAdapter } from "@falai/agent";
+import { PrismaClient } from "@prisma/client";
+
+const prisma = new PrismaClient();
+const agent = new Agent({
+  name: "Assistant",
+  ai: provider,
+  persistence: {
+    adapter: new PrismaAdapter({ prisma }),
+  },
+});
+
+const persistence = agent.getPersistenceManager();
+const session = await persistence.createSession({ userId: "user_123" });
+const history = await persistence.loadSessionHistory(session.id);
+const response = await agent.respond({ history });
+await persistence.saveMessage({
+  sessionId: session.id,
+  role: "agent",
+  content: response.message,
+});
+```
+
+## Database Schema Details
+
+### SessionData Fields
+
+- `id`: Unique session identifier
+- `userId`: Optional user identifier
+- `agentName`: Name of the agent
+- `status`: `"active" | "completed" | "abandoned"`
+- `currentRoute`: Current route ID
+- `currentState`: Current state ID
+- `collectedData`: JSON object for custom data
+- `messageCount`: Number of messages in session
+- `lastMessageAt`: Timestamp of last message
+- `completedAt`: When session was completed
+- `createdAt`: Session creation time
+- `updatedAt`: Last update time
+
+### MessageData Fields
+
+- `id`: Unique message identifier
+- `sessionId`: Reference to session
+- `userId`: Optional user identifier
+- `role`: `"user" | "agent" | "system"`
+- `content`: Message text
+- `route`: Route ID when message was sent
+- `state`: State ID when message was sent
+- `toolCalls`: Array of tool calls (if any)
+- `event`: Full event data (optional)
+- `createdAt`: Message creation time
+
+## Best Practices
+
+1. ✅ Use lifecycle hooks for automatic context persistence
+2. ✅ Enable `autoSave` to track message counts automatically
+3. ✅ Store minimal data in `collectedData`
+4. ✅ Index frequently queried fields
+5. ✅ Use cascading deletes for cleanup
+6. ✅ Handle errors gracefully
+7. ✅ Complete or abandon sessions when done
+
+## Troubleshooting
+
+### "Cannot find module '@prisma/client'"
+
+Install Prisma:
+
+```bash
+npm install @prisma/client prisma
+npx prisma generate
+```
+
+### "Table not found"
+
+Run migrations:
+
+```bash
+npx prisma migrate dev
+```
+
+### Custom schema not working
+
+Check your field mappings match your actual database schema.
+
+## Other Databases
+
+The adapter pattern works with any database. Examples:
+
+- **MongoDB**: Create `MongoAdapter`
+- **PostgreSQL (raw)**: Create `PostgresAdapter`
+- **MySQL**: Create `MySQLAdapter`
+- **Redis**: Create `RedisAdapter`
+- **Elasticsearch**: Create `ElasticsearchAdapter`
+
+Just implement the `PersistenceAdapter` interface!