@falai/agent 0.3.12 → 0.3.21

package/docs/API_REFERENCE.md

@@ -672,6 +672,454 @@ const provider = new OpenRouterProvider({
 
 ---
 
+## Persistence Adapters
+
+Optional persistence for auto-saving sessions and messages. All adapters implement the `PersistenceAdapter` interface.
+
+### `PersistenceManager`
+
+Manages persistence operations for sessions and messages.
+
+#### Constructor
+
+```typescript
+new PersistenceManager(config: PersistenceConfig)
+
+interface PersistenceConfig {
+  adapter: PersistenceAdapter;
+  autoSave?: boolean;    // Default: true
+  userId?: string;       // Optional: associate with user
+}
+```
+
+#### Methods
+
+##### `createSession(data: Partial<SessionData>): Promise<SessionData>`
+
+Creates a new conversation session.
+
+```typescript
+const session = await persistence.createSession({
+  userId: "user_123",
+  agentName: "Support Bot",
+  initialData: { channel: "web" },
+});
+```
+
+##### `getSession(sessionId: string): Promise<SessionData | null>`
+
+Retrieves a session by ID.
+
+##### `findActiveSession(userId: string): Promise<SessionData | null>`
+
+Finds the active session for a user.
+
+##### `getUserSessions(userId: string, limit?: number): Promise<SessionData[]>`
+
+Gets all sessions for a user.
+
+##### `updateSessionStatus(sessionId: string, status: SessionStatus): Promise<SessionData | null>`
+
+Updates session status ("active" | "completed" | "abandoned").
+
+##### `saveMessage(data: Partial<MessageData>): Promise<MessageData>`
+
+Saves a message to the database.
+
+```typescript
+await persistence.saveMessage({
+  sessionId: session.id,
+  role: "user",
+  content: "Hello!",
+});
+```
+
+##### `getSessionMessages(sessionId: string, limit?: number): Promise<MessageData[]>`
+
+Gets all messages for a session.
+
+##### `loadSessionHistory(sessionId: string, limit?: number): Promise<Event[]>`
+
+Loads session history in Event format for agent.respond().
+
+```typescript
+const history = await persistence.loadSessionHistory(sessionId);
+const response = await agent.respond({ history });
+```
+
+##### `completeSession(sessionId: string): Promise<SessionData | null>`
+
+Marks a session as completed.
+
+##### `abandonSession(sessionId: string): Promise<SessionData | null>`
+
+Marks a session as abandoned.
+
+---
+
+### `PrismaAdapter`
+
+Type-safe ORM adapter with migrations support.
+
+#### Constructor
+
+```typescript
+new PrismaAdapter(options: PrismaAdapterOptions)
+
+interface PrismaAdapterOptions {
+  prisma: PrismaClient;
+  autoMigrate?: boolean;      // Default: false
+  tables?: {
+    sessions?: string;        // Default: "AgentSession"
+    messages?: string;        // Default: "AgentMessage"
+  };
+  fieldMappings?: FieldMappings;  // Custom field names
+}
+```
+
+#### Example
+
+```typescript
+import { PrismaAdapter } from "@falai/agent";
+import { PrismaClient } from "@prisma/client";
+
+const prisma = new PrismaClient();
+
+const agent = new Agent({
+  persistence: {
+    adapter: new PrismaAdapter({
+      prisma,
+      autoMigrate: true, // Auto-run migrations
+      tables: {
+        sessions: "CustomSessions",
+        messages: "CustomMessages",
+      },
+    }),
+    userId: "user_123",
+  },
+});
+```
+
+**Schema Example:** See [examples/prisma-schema.example.prisma](../examples/prisma-schema.example.prisma)
+
+**Full Example:** See [examples/prisma-persistence.ts](../examples/prisma-persistence.ts)
+
+---
+
+### `RedisAdapter`
+
+Fast, in-memory persistence for high-throughput applications.
+
+#### Constructor
+
+```typescript
+new RedisAdapter(options: RedisAdapterOptions)
+
+interface RedisAdapterOptions {
+  redis: RedisClient;         // ioredis or redis client
+  keyPrefix?: string;         // Default: "agent:"
+  sessionTTL?: number;        // Default: 7 days (in seconds)
+  messageTTL?: number;        // Default: 30 days (in seconds)
+}
+```
+
+#### Example
+
+```typescript
+import { RedisAdapter } from "@falai/agent";
+import Redis from "ioredis";
+
+const redis = new Redis();
+
+const agent = new Agent({
+  persistence: {
+    adapter: new RedisAdapter({
+      redis,
+      keyPrefix: "chat:",
+      sessionTTL: 24 * 60 * 60, // 24 hours
+      messageTTL: 7 * 24 * 60 * 60, // 7 days
+    }),
+  },
+});
+```
+
+**Install:** `npm install ioredis` or `npm install redis`
+
+**Full Example:** See [examples/redis-persistence.ts](../examples/redis-persistence.ts)
+
+---
+
+### `MongoAdapter`
+
+Document-based storage with flexible schema.
+
+#### Constructor
+
+```typescript
+new MongoAdapter(options: MongoAdapterOptions)
+
+interface MongoAdapterOptions {
+  client: MongoClient;
+  databaseName: string;
+  collections?: {
+    sessions?: string;        // Default: "agent_sessions"
+    messages?: string;        // Default: "agent_messages"
+  };
+}
+```
+
+#### Example
+
+```typescript
+import { MongoAdapter } from "@falai/agent";
+import { MongoClient } from "mongodb";
+
+const client = new MongoClient("mongodb://localhost:27017");
+await client.connect();
+
+const agent = new Agent({
+  persistence: {
+    adapter: new MongoAdapter({
+      client,
+      databaseName: "myapp",
+      collections: {
+        sessions: "chat_sessions",
+        messages: "chat_messages",
+      },
+    }),
+  },
+});
+```
+
+**Install:** `npm install mongodb`
+
+---
+
+### `PostgreSQLAdapter`
+
+Raw SQL adapter with auto table/index creation.
+
+#### Constructor
+
+```typescript
+new PostgreSQLAdapter(options: PostgreSQLAdapterOptions)
+
+interface PostgreSQLAdapterOptions {
+  client: PgClient;           // pg client
+  tables?: {
+    sessions?: string;        // Default: "agent_sessions"
+    messages?: string;        // Default: "agent_messages"
+  };
+}
+```
+
+#### Methods
+
+##### `initialize(): Promise<void>`
+
+Creates tables and indexes if they don't exist.
+
+#### Example
+
+```typescript
+import { PostgreSQLAdapter } from "@falai/agent";
+import { Client } from "pg";
+
+const client = new Client({
+  host: "localhost",
+  database: "myapp",
+  user: "postgres",
+  password: "password",
+});
+await client.connect();
+
+const adapter = new PostgreSQLAdapter({ client });
+
+// Auto-create tables
+await adapter.initialize();
+
+const agent = new Agent({
+  persistence: { adapter },
+});
+```
+
+**Install:** `npm install pg`
+
+---
+
+### `SQLiteAdapter`
+
+Lightweight, file-based database for local development.
+
+#### Constructor
+
+```typescript
+new SQLiteAdapter(options: SQLiteAdapterOptions)
+
+interface SQLiteAdapterOptions {
+  db: SqliteDatabase;           // better-sqlite3 database
+  tables?: {
+    sessions?: string;          // Default: "agent_sessions"
+    messages?: string;          // Default: "agent_messages"
+  };
+}
+```
+
+#### Methods
+
+##### `initialize(): Promise<void>`
+
+Creates tables and indexes if they don't exist.
+
+#### Example
+
+```typescript
+import { SQLiteAdapter } from "@falai/agent";
+import Database from "better-sqlite3";
+
+const db = new Database("agent.db");
+const adapter = new SQLiteAdapter({ db });
+
+// Auto-create tables
+await adapter.initialize();
+
+const agent = new Agent({
+  persistence: { adapter },
+});
+```
+
+**Install:** `npm install better-sqlite3`
+
+**Perfect for:** Local development, testing, desktop apps, single-user applications
+
+---
+
+### `MemoryAdapter`
+
+Zero-dependency in-memory storage for testing and development.
+
+#### Constructor
+
+```typescript
+new MemoryAdapter();
+```
+
+No options needed - it's ready to go! ✨
+
+#### Methods
+
+##### `clear(): void`
+
+Clears all stored data (useful for testing).
+
+##### `getSnapshot(): { sessions: SessionData[]; messages: MessageData[] }`
+
+Returns a snapshot of all data (useful for debugging/testing).
+
+#### Example
+
+```typescript
+import { MemoryAdapter } from "@falai/agent";
+
+const adapter = new MemoryAdapter();
+
+const agent = new Agent({
+  persistence: { adapter },
+});
+
+// Perfect for unit tests!
+```
+
+**Testing Example:**
+
+```typescript
+describe("Agent", () => {
+  const adapter = new MemoryAdapter();
+
+  afterEach(() => {
+    adapter.clear(); // Reset between tests
+  });
+
+  it("should persist messages", async () => {
+    const agent = new Agent({
+      persistence: { adapter },
+    });
+
+    // ... test logic ...
+
+    const { sessions, messages } = adapter.getSnapshot();
+    expect(sessions).toHaveLength(1);
+    expect(messages).toHaveLength(2);
+  });
+});
+```
+
+**No installation required** - built into the framework!
+
+---
+
+### Persistence Types
+
+#### `SessionData`
+
+```typescript
+interface SessionData {
+  id: string;
+  userId?: string;
+  agentName?: string;
+  status: SessionStatus; // "active" | "completed" | "abandoned"
+  currentRoute?: string;
+  currentState?: string;
+  collectedData?: Record<string, unknown>;
+  messageCount: number;
+  lastMessageAt?: Date;
+  completedAt?: Date;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+#### `MessageData`
+
+```typescript
+interface MessageData {
+  id: string;
+  sessionId: string;
+  userId?: string;
+  role: MessageRole; // "user" | "agent" | "system"
+  content: string;
+  route?: string;
+  state?: string;
+  toolCalls?: Array<{
+    toolName: string;
+    arguments: Record<string, unknown>;
+    result?: unknown;
+  }>;
+  event?: Event;
+  createdAt: Date;
+}
+```
+
+#### `PersistenceAdapter`
+
+Interface for creating custom adapters:
+
+```typescript
+interface PersistenceAdapter {
+  sessionRepository: SessionRepository;
+  messageRepository: MessageRepository;
+  initialize?(): Promise<void>; // Optional: setup tables/indexes
+  disconnect?(): Promise<void>; // Optional: cleanup
+}
+```
+
+**See Also:**
+
+- [docs/PERSISTENCE.md](./PERSISTENCE.md) - Complete persistence guide
+- [docs/ADAPTERS.md](./ADAPTERS.md) - Adapter comparison and details
+
+---
+
 ### `PromptBuilder`
 
 Constructs prompts for AI generation.

package/docs/PERSISTENCE.md

@@ -408,12 +408,182 @@ Check your field mappings match your actual database schema.
 
 ## Other Databases
 
-The adapter pattern works with any database. Examples:
+The adapter pattern works with any database. Built-in adapters:
 
-- **MongoDB**: Create `MongoAdapter`
-- **PostgreSQL (raw)**: Create `PostgresAdapter`
-- **MySQL**: Create `MySQLAdapter`
-- **Redis**: Create `RedisAdapter`
-- **Elasticsearch**: Create `ElasticsearchAdapter`
+### Redis
+
+Perfect for high-throughput, real-time applications:
+
+```typescript
+import { RedisAdapter } from "@falai/agent";
+import Redis from "ioredis";
+
+const redis = new Redis();
+
+const agent = new Agent({
+  persistence: {
+    adapter: new RedisAdapter({
+      redis,
+      keyPrefix: "agent:", // Optional: custom prefix
+      sessionTTL: 24 * 60 * 60, // Optional: 24 hours
+      messageTTL: 7 * 24 * 60 * 60, // Optional: 7 days
+    }),
+  },
+});
+```
+
+**Install:** `npm install ioredis` or `npm install redis`
+
+### Coming Soon
+
+Create your own adapter for:
+
+- **MongoDB**: Document-based storage ✅ **Available!**
+- **PostgreSQL**: Raw SQL for custom schemas ✅ **Available!**
+- **MySQL**: Traditional relational database (coming soon)
+- **Elasticsearch**: Full-text search integration (coming soon)
 
 Just implement the `PersistenceAdapter` interface!
+
+### MongoDB
+
+Document-based storage with flexible schema:
+
+```typescript
+import { MongoAdapter } from "@falai/agent";
+import { MongoClient } from "mongodb";
+
+const client = new MongoClient("mongodb://localhost:27017");
+await client.connect();
+
+const agent = new Agent({
+  persistence: {
+    adapter: new MongoAdapter({
+      client,
+      databaseName: "myapp",
+      collections: {
+        // Optional: custom names
+        sessions: "agent_sessions",
+        messages: "agent_messages",
+      },
+    }),
+  },
+});
+```
+
+**Install:** `npm install mongodb`
+
+### PostgreSQL
+
+Raw SQL adapter with auto-table creation:
+
+```typescript
+import { PostgreSQLAdapter } from "@falai/agent";
+import { Client } from "pg";
+
+const client = new Client({
+  host: "localhost",
+  database: "myapp",
+  user: "postgres",
+  password: "password",
+});
+await client.connect();
+
+const adapter = new PostgreSQLAdapter({
+  client,
+  tables: {
+    // Optional: custom names
+    sessions: "agent_sessions",
+    messages: "agent_messages",
+  },
+});
+
+// Auto-create tables with indexes
+await adapter.initialize();
+
+const agent = new Agent({
+  persistence: {
+    adapter,
+  },
+});
+```
+
+**Install:** `npm install pg`
+
+**Note:** PostgreSQL adapter includes `initialize()` method to auto-create tables with proper indexes and foreign keys.
+
+### SQLite
+
+Lightweight, file-based database for local development:
+
+```typescript
+import { SQLiteAdapter } from "@falai/agent";
+import Database from "better-sqlite3";
+
+const db = new Database("agent.db");
+
+const adapter = new SQLiteAdapter({ db });
+
+// Auto-create tables
+await adapter.initialize();
+
+const agent = new Agent({
+  persistence: { adapter },
+});
+```
+
+**Install:** `npm install better-sqlite3`
+
+**Perfect for:**
+
+- Local development
+- Testing
+- Desktop applications
+- Single-user apps
+
+### Memory (Built-in)
+
+Zero-dependency in-memory storage for testing:
+
+```typescript
+import { MemoryAdapter } from "@falai/agent";
+
+const agent = new Agent({
+  persistence: {
+    adapter: new MemoryAdapter(),
+    userId: "test_user",
+  },
+});
+
+// Perfect for unit tests - no database setup required!
+```
+
+**Features:**
+
+- No installation required ✨
+- Perfect for testing
+- Data snapshot for debugging
+- Clear method for test cleanup
+
+**Example test:**
+
+```typescript
+describe("Agent persistence", () => {
+  const adapter = new MemoryAdapter();
+
+  afterEach(() => {
+    adapter.clear(); // Clean state between tests
+  });
+
+  it("should save session", async () => {
+    const agent = new Agent({
+      persistence: { adapter },
+    });
+
+    // Test your logic...
+
+    const snapshot = adapter.getSnapshot();
+    expect(snapshot.sessions).toHaveLength(1);
+  });
+});
+```

package/examples/redis-persistence.ts

@@ -0,0 +1,89 @@
+/**
+ * Example: Using Redis for Persistence
+ *
+ * Fast, in-memory persistence perfect for:
+ * - High-throughput applications
+ * - Session caching
+ * - Real-time chat applications
+ * - Temporary conversation storage
+ */
+
+import { Agent, GeminiProvider, RedisAdapter } from "../src/index";
+// @ts-ignore
+import Redis from "ioredis";
+
+/**
+ * Setup Steps:
+ *
+ * 1. Install Redis and client:
+ *    brew install redis (macOS) or apt-get install redis (Linux)
+ *    npm install ioredis
+ *
+ * 2. Start Redis:
+ *    redis-server
+ *
+ * 3. Run this example
+ */
+
+async function example() {
+  // Initialize Redis client
+  const redis = new Redis();
+
+  // Create agent with Redis persistence
+  const agent = new Agent({
+    name: "Chat Assistant",
+    description: "Fast, real-time chat assistant",
+    ai: new GeminiProvider({
+      apiKey: process.env.GEMINI_API_KEY!,
+      model: "models/gemini-2.0-flash-exp",
+    }),
+    // ✨ Redis adapter with custom options
+    persistence: {
+      adapter: new RedisAdapter({
+        redis,
+        keyPrefix: "chat:", // Custom prefix
+        sessionTTL: 24 * 60 * 60, // 24 hours
+        messageTTL: 7 * 24 * 60 * 60, // 7 days
+      }),
+      autoSave: true,
+      userId: "user_123",
+    },
+  });
+
+  const persistence = agent.getPersistenceManager();
+  if (!persistence) return;
+
+  // Create session
+  const session = await persistence.createSession({
+    userId: "user_123",
+    agentName: "Chat Assistant",
+    initialData: { chatType: "support" },
+  });
+
+  console.log("✨ Session created in Redis:", session.id);
+
+  // Save a message
+  await persistence.saveMessage({
+    sessionId: session.id,
+    role: "user",
+    content: "Hello! I need help",
+  });
+
+  // Load messages
+  const messages = await persistence.getSessionMessages(session.id);
+  console.log(`💬 ${messages.length} messages in session`);
+
+  // Complete session
+  await persistence.completeSession(session.id);
+  console.log("✅ Session completed");
+
+  // Cleanup
+  await redis.quit();
+}
+
+// Run the example
+if (require.main === module) {
+  example().catch(console.error);
+}
+
+export { example };