@falai/agent 0.3.12 → 0.3.20

package/docs/PERSISTENCE.md

@@ -408,12 +408,106 @@ 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.

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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.3.12",
+  "version": "0.3.20",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -82,11 +82,31 @@
     "openai": "^6.3.0"
   },
   "peerDependencies": {
-    "@prisma/client": "^5.0.0 || ^6.0.0"
+    "@prisma/client": "^6.0.0",
+    "ioredis": "^5.7.0",
+    "redis": "^4.6.0 || ^5.0.0",
+    "mongodb": "^6.0.0 || ^7.0.0",
+    "pg": "^8.11.0",
+    "mysql2": "^3.2.0"
   },
   "peerDependenciesMeta": {
     "@prisma/client": {
       "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    },
+    "redis": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
     }
   }
 }

package/src/adapters/MongoAdapter.ts

@@ -0,0 +1,295 @@
+/**
+ * MongoDB adapter for persistence
+ * Document-based storage with flexible schema
+ */
+
+import type {
+  SessionRepository,
+  MessageRepository,
+  SessionData,
+  MessageData,
+  SessionStatus,
+  PersistenceAdapter,
+} from "../types/persistence";
+
+/**
+ * MongoDB collection interface - matches mongodb driver
+ */
+export interface MongoCollection<T = Record<string, unknown>> {
+  insertOne(doc: T): Promise<{ insertedId: unknown }>;
+  findOne(filter: Record<string, unknown>): Promise<T | null>;
+  find(filter: Record<string, unknown>): {
+    sort(sort: Record<string, number>): {
+      limit(limit: number): {
+        toArray(): Promise<T[]>;
+      };
+    };
+    toArray(): Promise<T[]>;
+  };
+  updateOne(
+    filter: Record<string, unknown>,
+    update: Record<string, unknown>
+  ): Promise<{ matchedCount: number }>;
+  deleteOne(filter: Record<string, unknown>): Promise<{ deletedCount: number }>;
+  deleteMany(
+    filter: Record<string, unknown>
+  ): Promise<{ deletedCount: number }>;
+}
+
+/**
+ * MongoDB database interface
+ */
+export interface MongoDatabase {
+  collection<T = Record<string, unknown>>(name: string): MongoCollection<T>;
+}
+
+/**
+ * MongoDB client interface
+ */
+export interface MongoClient {
+  db(name?: string): MongoDatabase;
+  close(): Promise<void>;
+}
+
+/**
+ * Options for MongoDB adapter
+ */
+export interface MongoAdapterOptions {
+  /**
+   * MongoDB client instance
+   */
+  client: MongoClient;
+
+  /**
+   * Database name
+   */
+  databaseName: string;
+
+  /**
+   * Collection names (default: "agent_sessions" and "agent_messages")
+   */
+  collections?: {
+    sessions?: string;
+    messages?: string;
+  };
+}
+
+/**
+ * MongoDB Adapter - Provider-style API for MongoDB persistence
+ *
+ * @example
+ * ```typescript
+ * import { MongoClient } from 'mongodb';
+ * import { Agent, MongoAdapter } from '@falai/agent';
+ *
+ * const client = new MongoClient('mongodb://localhost:27017');
+ * await client.connect();
+ *
+ * const agent = new Agent({
+ *   name: "My Agent",
+ *   ai: provider,
+ *   persistence: {
+ *     adapter: new MongoAdapter({
+ *       client,
+ *       databaseName: 'myapp',
+ *     }),
+ *     userId: "user_123",
+ *   },
+ * });
+ * ```
+ */
+export class MongoAdapter implements PersistenceAdapter {
+  public readonly sessionRepository: SessionRepository;
+  public readonly messageRepository: MessageRepository;
+  private client: MongoClient;
+  private db: MongoDatabase;
+
+  constructor(options: MongoAdapterOptions) {
+    this.client = options.client;
+    this.db = options.client.db(options.databaseName);
+
+    const sessionCollection = options.collections?.sessions || "agent_sessions";
+    const messageCollection = options.collections?.messages || "agent_messages";
+
+    this.sessionRepository = new MongoSessionRepository(
+      this.db.collection(sessionCollection)
+    );
+
+    this.messageRepository = new MongoMessageRepository(
+      this.db.collection(messageCollection)
+    );
+  }
+
+  async disconnect(): Promise<void> {
+    await this.client.close();
+  }
+}
+
+/**
+ * MongoDB Session Repository
+ */
+class MongoSessionRepository implements SessionRepository {
+  constructor(private collection: MongoCollection<SessionData>) {}
+
+  async create(
+    data: Omit<SessionData, "id" | "createdAt" | "updatedAt">
+  ): Promise<SessionData> {
+    const now = new Date();
+    const session: SessionData = {
+      ...data,
+      id: `session_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+      status: data.status || "active",
+      messageCount: data.messageCount || 0,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    await this.collection.insertOne(session);
+    return session;
+  }
+
+  async findById(id: string): Promise<SessionData | null> {
+    return await this.collection.findOne({ id });
+  }
+
+  async findActiveByUserId(userId: string): Promise<SessionData | null> {
+    return await this.collection.findOne({ userId, status: "active" });
+  }
+
+  async findByUserId(userId: string, limit = 100): Promise<SessionData[]> {
+    return await this.collection
+      .find({ userId })
+      .sort({ createdAt: -1 })
+      .limit(limit)
+      .toArray();
+  }
+
+  async update(
+    id: string,
+    data: Partial<Omit<SessionData, "id" | "createdAt">>
+  ): Promise<SessionData | null> {
+    const result = await this.collection.updateOne(
+      { id },
+      { $set: { ...data, updatedAt: new Date() } }
+    );
+
+    if (result.matchedCount === 0) return null;
+    return await this.findById(id);
+  }
+
+  async updateStatus(
+    id: string,
+    status: SessionStatus,
+    completedAt?: Date
+  ): Promise<SessionData | null> {
+    const updateData: Record<string, unknown> = {
+      status,
+      updatedAt: new Date(),
+    };
+    if (completedAt) {
+      updateData.completedAt = completedAt;
+    }
+
+    const result = await this.collection.updateOne(
+      { id },
+      { $set: updateData }
+    );
+
+    if (result.matchedCount === 0) return null;
+    return await this.findById(id);
+  }
+
+  async updateCollectedData(
+    id: string,
+    collectedData: Record<string, unknown>
+  ): Promise<SessionData | null> {
+    return await this.update(id, { collectedData });
+  }
+
+  async updateRouteState(
+    id: string,
+    route?: string,
+    state?: string
+  ): Promise<SessionData | null> {
+    return await this.update(id, {
+      currentRoute: route,
+      currentState: state,
+    });
+  }
+
+  async incrementMessageCount(id: string): Promise<SessionData | null> {
+    const result = await this.collection.updateOne(
+      { id },
+      {
+        $inc: { messageCount: 1 },
+        $set: { lastMessageAt: new Date(), updatedAt: new Date() },
+      }
+    );
+
+    if (result.matchedCount === 0) return null;
+    return await this.findById(id);
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const result = await this.collection.deleteOne({ id });
+    return result.deletedCount > 0;
+  }
+}
+
+/**
+ * MongoDB Message Repository
+ */
+class MongoMessageRepository implements MessageRepository {
+  constructor(private collection: MongoCollection<MessageData>) {}
+
+  async create(
+    data: Omit<MessageData, "id" | "createdAt">
+  ): Promise<MessageData> {
+    const message: MessageData = {
+      ...data,
+      id: `msg_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+      createdAt: new Date(),
+    };
+
+    await this.collection.insertOne(message);
+    return message;
+  }
+
+  async findById(id: string): Promise<MessageData | null> {
+    return await this.collection.findOne({ id });
+  }
+
+  async findBySessionId(
+    sessionId: string,
+    limit = 1000
+  ): Promise<MessageData[]> {
+    return await this.collection
+      .find({ sessionId })
+      .sort({ createdAt: 1 })
+      .limit(limit)
+      .toArray();
+  }
+
+  async findByUserId(userId: string, limit = 100): Promise<MessageData[]> {
+    return await this.collection
+      .find({ userId })
+      .sort({ createdAt: -1 })
+      .limit(limit)
+      .toArray();
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const result = await this.collection.deleteOne({ id });
+    return result.deletedCount > 0;
+  }
+
+  async deleteBySessionId(sessionId: string): Promise<number> {
+    const result = await this.collection.deleteMany({ sessionId });
+    return result.deletedCount;
+  }
+
+  async deleteByUserId(userId: string): Promise<number> {
+    const result = await this.collection.deleteMany({ userId });
+    return result.deletedCount;
+  }
+}