@falai/agent 0.1.0-alpha2

package/package.json

@@ -0,0 +1,125 @@
+{
+  "name": "@falai/agent",
+  "version": "0.1.0-alpha2",
+  "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/falai-dev/agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/falai-dev/agent/issues"
+  },
+  "homepage": "https://github.com/falai-dev/agent#readme",
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run fix:cjs",
+    "build:esm": "tsc",
+    "build:cjs": "tsc --project tsconfig.cjs.json",
+    "fix:cjs": "echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run build && bun run test",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish",
+    "release:major": "npm version major && npm publish",
+    "release:alpha": "npm publish --tag alpha",
+    "release": "npm publish",
+    "test": "bun run tests/*.test.ts"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "typescript",
+    "conversational-ai",
+    "gemini",
+    "llm",
+    "chatbot",
+    "framework",
+    "routes",
+    "dsl"
+  ],
+  "author": "Gustavo Salomé <gusnips>",
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/bun": "^1.3.0",
+    "@types/node": "^20.19.22",
+    "eslint": "^9.17.0",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.18.2",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.65.0",
+    "@google/genai": "^0.3.0",
+    "@types/pg": "^8.15.5",
+    "@types/redis": "^4.0.11",
+    "loglevel": "^1.9.2",
+    "openai": "^6.3.0"
+  },
+  "peerDependencies": {
+    "@opensearch-project/opensearch": "^2.0.0",
+    "@prisma/client": "^6.0.0",
+    "better-sqlite3": "^11.0.0 || ^12.0.0",
+    "ioredis": "",
+    "mongodb": "",
+    "mysql2": "^3.2.0",
+    "pg": ""
+  },
+  "peerDependenciesMeta": {
+    "@prisma/client": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    },
+    "redis": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    },
+    "@opensearch-project/opensearch": {
+      "optional": true
+    }
+  }
+}

package/src/adapters/MemoryAdapter.ts

@@ -0,0 +1,273 @@
+/**
+ * Memory adapter for persistence
+ * In-memory storage for testing and development (no database required)
+ */
+
+import type {
+  CollectedStateData,
+  MessageData,
+  MessageRepository,
+  PersistenceAdapter,
+  SessionData,
+  SessionRepository,
+  SessionStatus,
+  CreateSessionData,
+} from "../types";
+import { cloneDeep } from "../utils/clone";
+
+/**
+ * Memory Adapter - Provider-style API for in-memory persistence
+ *
+ * Perfect for:
+ * - Testing
+ * - Development
+ * - Prototyping
+ * - No database setup required
+ *
+ * @example
+ * ```typescript
+ * import { Agent, MemoryAdapter } from '@falai/agent';
+ *
+ * const agent = new Agent({
+ *   name: "My Agent",
+ *   provider: provider,
+ *   persistence: {
+ *     adapter: new MemoryAdapter(),
+ *     userId: "user_123",
+ *   },
+ * });
+ * ```
+ */
+export class MemoryAdapter<TData = Record<string, unknown>>
+  implements PersistenceAdapter<TData>
+{
+  public readonly sessionRepository: SessionRepository<TData>;
+  public readonly messageRepository: MessageRepository;
+  private sessions: Map<string, SessionData<TData>>;
+  private messages: Map<string, MessageData>;
+
+  constructor() {
+    this.sessions = new Map();
+    this.messages = new Map();
+
+    this.sessionRepository = new MemorySessionRepository<TData>(this.sessions);
+    this.messageRepository = new MemoryMessageRepository(this.messages);
+  }
+
+  /**
+   * Clear all data (useful for testing)
+   */
+  clear(): void {
+    this.sessions.clear();
+    this.messages.clear();
+  }
+
+  /**
+   * Get data snapshot (useful for debugging)
+   */
+  getSnapshot(): {
+    sessions: SessionData<TData>[];
+    messages: MessageData[];
+  } {
+    return {
+      sessions: Array.from(this.sessions.values()),
+      messages: Array.from(this.messages.values()),
+    };
+  }
+}
+
+/**
+ * Memory Session Repository
+ */
+class MemorySessionRepository<TData = Record<string, unknown>>
+  implements SessionRepository<TData>
+{
+  constructor(private sessions: Map<string, SessionData<TData>>) {}
+
+  create(data: CreateSessionData<TData>): Promise<SessionData<TData>> {
+    const id =
+      data.id || `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    const now = new Date();
+
+    const session: SessionData<TData> = {
+      ...data,
+      id,
+      status: data.status || "active",
+      messageCount: data.messageCount || 0,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    this.sessions.set(id, cloneDeep(session));
+    return Promise.resolve(cloneDeep(session));
+  }
+
+  findById(id: string): Promise<SessionData<TData> | null> {
+    const session = this.sessions.get(id);
+    return Promise.resolve(session ? cloneDeep(session) : null);
+  }
+
+  async findActiveByUserId(userId: string): Promise<SessionData<TData> | null> {
+    const sessions = Array.from(this.sessions.values())
+      .filter((s) => s.userId === userId && s.status === "active")
+      .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+
+    return Promise.resolve(sessions[0] || null);
+  }
+
+  async findByUserId(
+    userId: string,
+    limit = 100
+  ): Promise<SessionData<TData>[]> {
+    const sessions = Array.from(this.sessions.values())
+      .filter((s) => s.userId === userId)
+      .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
+      .slice(0, limit);
+    return Promise.resolve(sessions);
+  }
+
+  async update(
+    id: string,
+    data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>
+  ): Promise<SessionData<TData> | null> {
+    const existing = this.sessions.get(id);
+    if (!existing) return null;
+
+    const updated: SessionData<TData> = {
+      ...existing,
+      ...data,
+      updatedAt: new Date(),
+    };
+
+    this.sessions.set(id, cloneDeep(updated));
+    return Promise.resolve(cloneDeep(updated));
+  }
+
+  async updateStatus(
+    id: string,
+    status: SessionStatus,
+    completedAt?: Date
+  ): Promise<SessionData<TData> | null> {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.status = status;
+      if (completedAt) {
+        session.completedAt = completedAt;
+      }
+      this.sessions.set(id, cloneDeep(session));
+      return Promise.resolve(cloneDeep(session));
+    }
+    return Promise.resolve(null);
+  }
+
+  async updateCollectedData(
+    id: string,
+    collectedData: CollectedStateData<TData>
+  ): Promise<SessionData<TData> | null> {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.collectedData = collectedData;
+      this.sessions.set(id, cloneDeep(session));
+      return Promise.resolve(cloneDeep(session));
+    }
+    return Promise.resolve(null);
+  }
+
+  async updateRouteStep(
+    id: string,
+    route?: string,
+    step?: string
+  ): Promise<SessionData<TData> | null> {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.currentRoute = route;
+      session.currentStep = step;
+      this.sessions.set(id, cloneDeep(session));
+      return Promise.resolve(cloneDeep(session));
+    }
+    return Promise.resolve(null);
+  }
+
+  async incrementMessageCount(id: string): Promise<SessionData<TData> | null> {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.messageCount = (session.messageCount || 0) + 1;
+      this.sessions.set(id, cloneDeep(session));
+      return Promise.resolve(cloneDeep(session));
+    }
+    return Promise.resolve(null);
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const result = this.sessions.delete(id);
+    return Promise.resolve(result);
+  }
+}
+
+/**
+ * Memory Message Repository
+ */
+class MemoryMessageRepository implements MessageRepository {
+  constructor(private messages: Map<string, MessageData>) {}
+
+  async create(
+    data: Omit<MessageData, "id" | "createdAt">
+  ): Promise<MessageData> {
+    const id = `msg_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    const message: MessageData = {
+      ...data,
+      id,
+      createdAt: new Date(),
+    };
+
+    this.messages.set(id, message);
+    return Promise.resolve(message);
+  }
+
+  async findById(id: string): Promise<MessageData | null> {
+    const message = this.messages.get(id) || null;
+    return Promise.resolve(message);
+  }
+
+  async findBySessionId(
+    sessionId: string,
+    limit = 1000
+  ): Promise<MessageData[]> {
+    const messages = Array.from(this.messages.values())
+      .filter((m) => m.sessionId === sessionId)
+      .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+      .slice(0, limit);
+    return Promise.resolve(messages);
+  }
+
+  async findByUserId(userId: string, limit = 100): Promise<MessageData[]> {
+    const messages = Array.from(this.messages.values())
+      .filter((m) => m.userId === userId)
+      .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
+      .slice(0, limit);
+    return Promise.resolve(messages);
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const result = this.messages.delete(id);
+    return Promise.resolve(result);
+  }
+
+  async deleteBySessionId(sessionId: string): Promise<number> {
+    const toDelete = Array.from(this.messages.values()).filter(
+      (m) => m.sessionId === sessionId
+    );
+
+    toDelete.forEach((m) => this.messages.delete(m.id));
+    return Promise.resolve(toDelete.length);
+  }
+
+  async deleteByUserId(userId: string): Promise<number> {
+    const toDelete = Array.from(this.messages.values()).filter(
+      (m) => m.userId === userId
+    );
+
+    toDelete.forEach((m) => this.messages.delete(m.id));
+    return Promise.resolve(toDelete.length);
+  }
+}

package/src/adapters/MongoAdapter.ts

@@ -0,0 +1,304 @@
+/**
+ * MongoDB adapter for persistence
+ * Document-based storage with flexible schema
+ */
+
+import type {
+  MessageData,
+  MessageRepository,
+  PersistenceAdapter,
+  SessionData,
+  SessionRepository,
+  SessionStatus,
+  CollectedStateData,
+  CreateSessionData,
+} from "../types";
+
+/**
+ * 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",
+ *   provider: provider,
+ *   persistence: {
+ *     adapter: new MongoAdapter({
+ *       client,
+ *       databaseName: 'myapp',
+ *     }),
+ *     userId: "user_123",
+ *   },
+ * });
+ * ```
+ */
+export class MongoAdapter<TData = Record<string, unknown>>
+  implements PersistenceAdapter<TData>
+{
+  public readonly sessionRepository: SessionRepository<TData>;
+  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<TData>(
+      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<TData = Record<string, unknown>>
+  implements SessionRepository<TData>
+{
+  constructor(private collection: MongoCollection<SessionData<TData>>) {}
+
+  async create(data: CreateSessionData<TData>): Promise<SessionData<TData>> {
+    const now = new Date();
+    const session: SessionData<TData> = {
+      ...data,
+      id:
+        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<TData> | null> {
+    return await this.collection.findOne({ id });
+  }
+
+  async findActiveByUserId(userId: string): Promise<SessionData<TData> | null> {
+    return await this.collection.findOne({ userId, status: "active" });
+  }
+
+  async findByUserId(
+    userId: string,
+    limit = 100
+  ): Promise<SessionData<TData>[]> {
+    return await this.collection
+      .find({ userId })
+      .sort({ createdAt: -1 })
+      .limit(limit)
+      .toArray();
+  }
+
+  async update(
+    id: string,
+    data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>
+  ): Promise<SessionData<TData> | 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<TData> | 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: CollectedStateData<TData>
+  ): Promise<SessionData<TData> | null> {
+    return await this.update(id, { collectedData });
+  }
+
+  async updateRouteStep(
+    id: string,
+    route?: string,
+    step?: string
+  ): Promise<SessionData<TData> | null> {
+    return await this.update(id, {
+      currentRoute: route,
+      currentStep: step,
+    });
+  }
+
+  async incrementMessageCount(id: string): Promise<SessionData<TData> | 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;
+  }
+}