@falai/agent 0.3.20 → 0.3.22

package/docs/API_REFERENCE.md

@@ -947,6 +947,185 @@ const agent = new Agent({
 
 ---
 
+### `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
+
+---
+
+### `OpenSearchAdapter`
+
+Full-text search and analytics-powered persistence. Compatible with OpenSearch and Elasticsearch 7.x.
+
+#### Constructor
+
+```typescript
+new OpenSearchAdapter(client: OpenSearchClient, options?: OpenSearchAdapterOptions)
+
+interface OpenSearchAdapterOptions {
+  indices?: {
+    sessions?: string;        // Default: "agent_sessions"
+    messages?: string;        // Default: "agent_messages"
+  };
+  autoCreateIndices?: boolean; // Default: true
+  refresh?: boolean | "wait_for"; // Default: false
+}
+```
+
+#### Methods
+
+##### `initialize(): Promise<void>`
+
+Creates indices with proper mappings if they don't exist.
+
+##### `disconnect(): Promise<void>`
+
+Gracefully disconnect (no-op for OpenSearch - connection pooling is automatic).
+
+#### Example
+
+```typescript
+import { OpenSearchAdapter } from "@falai/agent";
+import { Client } from "@opensearch-project/opensearch";
+
+const client = new Client({
+  node: "https://localhost:9200",
+  auth: {
+    username: "admin",
+    password: "admin",
+  },
+});
+
+const adapter = new OpenSearchAdapter(client, {
+  indices: {
+    sessions: "agent_sessions",
+    messages: "agent_messages",
+  },
+  autoCreateIndices: true,
+  refresh: "wait_for", // Wait for documents to be searchable
+});
+
+// Auto-create indices with mappings
+await adapter.initialize();
+
+const agent = new Agent({
+  persistence: { adapter },
+});
+```
+
+**Install:** `npm install @opensearch-project/opensearch`
+
+**Perfect for:** Full-text search, analytics, time-series analysis, AWS OpenSearch Service, Elasticsearch 7.x users
+
+**Full Example:** See [examples/opensearch-persistence.ts](../examples/opensearch-persistence.ts)
+
+---
+
+### `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`

package/docs/PERSISTENCE.md

@@ -434,16 +434,17 @@ const agent = new Agent({
 
 **Install:** `npm install ioredis` or `npm install redis`
 
-### Coming Soon
+### More Adapters
 
-Create your own adapter for:
+All adapters are production-ready and available now:
 
-- **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)
+- **MongoDB**: Document-based storage ✅
+- **PostgreSQL**: Raw SQL for custom schemas ✅
+- **SQLite**: Lightweight file-based database ✅
+- **OpenSearch**: Full-text search & analytics ✅
+- **Memory**: Built-in for testing ✅
 
-Just implement the `PersistenceAdapter` interface!
+Create your own adapter by implementing the `PersistenceAdapter` interface!
 
 ### MongoDB
 
@@ -511,3 +512,149 @@ const agent = new Agent({
 **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
+
+### OpenSearch
+
+Full-text search and analytics-powered persistence. Also compatible with Elasticsearch 7.x:
+
+```typescript
+import { OpenSearchAdapter } from "@falai/agent";
+import { Client } from "@opensearch-project/opensearch";
+
+const client = new Client({
+  node: "https://localhost:9200",
+  auth: {
+    username: "admin",
+    password: "admin",
+  },
+});
+
+const adapter = new OpenSearchAdapter(client, {
+  indices: {
+    sessions: "agent_sessions",
+    messages: "agent_messages",
+  },
+  autoCreateIndices: true, // Auto-create indices with mappings
+  refresh: "wait_for", // Ensure documents are searchable immediately
+});
+
+// Auto-create indices with mappings
+await adapter.initialize();
+
+const agent = new Agent({
+  persistence: { adapter },
+});
+```
+
+**Install:** `npm install @opensearch-project/opensearch`
+
+**Perfect for:**
+
+- Full-text search across conversations
+- Analytics and aggregations
+- Time-series analysis
+- AWS OpenSearch Service
+- Elasticsearch 7.x users
+
+**Advanced features:**
+
+```typescript
+// Get OpenSearch client for custom queries
+const pm = agent.getPersistenceManager();
+if (pm) {
+  const messages = await pm.getSessionMessages(sessionId);
+
+  // Now use the client directly for advanced queries
+  const results = await client.search({
+    index: "agent_messages",
+    body: {
+      query: {
+        match: {
+          content: "flight booking",
+        },
+      },
+      aggregations: {
+        by_route: {
+          terms: { field: "route" },
+        },
+      },
+    },
+  });
+}
+```
+
+### 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/docs/README.md

@@ -16,7 +16,9 @@ Welcome to the `@falai/agent` documentation!
 ### Reference
 
 - **[API Reference](./API_REFERENCE.md)** - Complete API documentation for all classes, methods, and types
-- **[AI Providers Guide](./PROVIDERS.md)** - Gemini, OpenAI, and custom providers
+- **[AI Providers Guide](./PROVIDERS.md)** - Gemini, OpenAI, Anthropic, and custom providers
+- **[Persistence Guide](./PERSISTENCE.md)** - Auto-save sessions and messages to any database
+- **[Database Adapters](./ADAPTERS.md)** - Adapter comparison and configuration examples
 - **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute to the project
 - **[Publishing Guide](./PUBLISHING.md)** - How to publish updates to npm
 
@@ -36,21 +38,44 @@ Welcome to the `@falai/agent` documentation!
 **Understanding the codebase?**
 → Read [Package Structure](./STRUCTURE.md)
 
+**Need persistence?**
+→ See [Persistence Guide](./PERSISTENCE.md)
+
 ### By Topic
 
 - **Agent Configuration**: [Constructor Options](./CONSTRUCTOR_OPTIONS.md)
 - **Conversation Flows**: [API Reference - Routes](./API_REFERENCE.md#route)
 - **Tools & Functions**: [API Reference - Tools](./API_REFERENCE.md#definetool)
 - **Disambiguation**: [API Reference - Observations](./API_REFERENCE.md#observation)
-- **AI Providers**: [API Reference - GeminiProvider](./API_REFERENCE.md#geminiprovider)
+- **AI Providers**: [Providers Guide](./PROVIDERS.md) | [API Reference](./API_REFERENCE.md#geminiprovider)
+- **Database Persistence**: [Persistence Guide](./PERSISTENCE.md) | [Adapters](./ADAPTERS.md)
 
 ## 💡 Examples
 
 Check out the [`examples/`](../examples/) directory for complete, runnable examples:
 
+### Core Examples
+
 - **[Declarative Agent](../examples/declarative-agent.ts)** - Full constructor-based configuration
 - **[Travel Agent](../examples/travel-agent.ts)** - Complex multi-route travel booking system
 - **[Healthcare Agent](../examples/healthcare-agent.ts)** - Disambiguation with observations
+- **[Streaming Agent](../examples/streaming-agent.ts)** - Real-time streaming responses
+
+### Persistence Examples
+
+- **[Prisma Persistence](../examples/prisma-persistence.ts)** - Auto-save with Prisma ORM
+- **[Redis Persistence](../examples/redis-persistence.ts)** - Fast in-memory persistence
+
+### Provider Examples
+
+- **[OpenAI Agent](../examples/openai-agent.ts)** - GPT-5 integration
+- **[Gemini Agent](../examples/gemini-agent.ts)** - Google Gemini integration
+- **[Anthropic Agent](../examples/healthcare-agent.ts)** - Claude 3.5 Sonnet
+
+### Advanced Examples
+
+- **[Domain Scoping](../examples/domain-scoping.ts)** - Control tool access per route
+- **[Rules & Prohibitions](../examples/rules-prohibitions.ts)** - Fine-grained behavior control
 
 ## 🤝 Contributing
 

package/examples/opensearch-persistence.ts

@@ -0,0 +1,175 @@
+/**
+ * OpenSearch Persistence Example
+ *
+ * This example demonstrates how to use the OpenSearchAdapter for persistent storage.
+ * Also compatible with Elasticsearch 7.x.
+ *
+ * Setup:
+ * 1. Install the OpenSearch client: npm install @opensearch-project/opensearch
+ * 2. Run OpenSearch locally:
+ *    docker run -d -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" opensearchproject/opensearch:latest
+ * 3. Run this example: bun run examples/opensearch-persistence.ts
+ */
+
+// @ts-ignore - OpenSearch is a peer dependency
+import { Client } from "@opensearch-project/opensearch";
+import {
+  Agent,
+  GeminiProvider,
+  OpenSearchAdapter,
+  defineTool,
+  createMessageEvent,
+  EventSource,
+} from "../src/index.js";
+
+// Initialize OpenSearch client
+const client = new Client({
+  node: process.env.OPENSEARCH_URL || "https://localhost:9200",
+  auth: {
+    username: process.env.OPENSEARCH_USERNAME || "admin",
+    password: process.env.OPENSEARCH_PASSWORD || "admin",
+  },
+  ssl: {
+    rejectUnauthorized: false, // For development only!
+  },
+});
+
+// Create adapter with custom index names
+const adapter = new OpenSearchAdapter(client, {
+  indices: {
+    sessions: "my_agent_sessions",
+    messages: "my_agent_messages",
+  },
+  autoCreateIndices: true, // Automatically create indices with mappings
+  refresh: "wait_for", // Wait for documents to be searchable (slower but consistent)
+});
+
+// Define context type
+interface TravelContext {
+  userId: string;
+  userName: string;
+}
+
+// Define a simple tool
+const bookFlight = defineTool<
+  TravelContext,
+  [destination: string, date: string],
+  { success: boolean; confirmation: string }
+>(
+  "book_flight",
+  async ({ context }, destination, date) => {
+    console.log(`📝 Booking flight for ${context.userName}...`);
+    return {
+      data: {
+        success: true,
+        confirmation: `Flight to ${destination} booked for ${date}`,
+      },
+    };
+  },
+  {
+    description: "Book a flight for the user",
+    parameters: {
+      type: "object",
+      properties: {
+        destination: { type: "string", description: "Destination city" },
+        date: { type: "string", description: "Travel date" },
+      },
+      required: ["destination", "date"],
+    },
+  }
+);
+
+// Create agent with OpenSearch persistence
+const agent = new Agent<TravelContext>({
+  name: "Travel Assistant",
+  description: "A helpful travel booking assistant",
+  ai: new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY || "",
+    model: "gemini-2.0-flash-exp",
+  }),
+  context: {
+    userId: "user_123",
+    userName: "Alex",
+  },
+  persistence: {
+    adapter,
+    autoSave: true,
+    userId: "user_123",
+  },
+  capabilities: [
+    {
+      title: "Flight Booking",
+      description: "Book flights for travel",
+      tools: [bookFlight],
+    },
+  ],
+});
+
+async function main() {
+  try {
+    console.log("🚀 Starting OpenSearch persistence example...\n");
+
+    // First conversation
+    console.log("💬 User: I need to book a flight to Tokyo");
+    const history1 = [
+      createMessageEvent(
+        EventSource.CUSTOMER,
+        "Alex",
+        "I need to book a flight to Tokyo"
+      ),
+    ];
+    let response = await agent.respond({ history: history1 });
+    console.log("🤖 Agent:", response.message);
+    console.log();
+
+    // Continue conversation (uses same session)
+    console.log("💬 User: Make it for next Monday");
+    const history2 = [
+      ...history1,
+      createMessageEvent(
+        EventSource.AI_AGENT,
+        "Travel Assistant",
+        response.message
+      ),
+      createMessageEvent(
+        EventSource.CUSTOMER,
+        "Alex",
+        "Make it for next Monday"
+      ),
+    ];
+    response = await agent.respond({ history: history2 });
+    console.log("🤖 Agent:", response.message);
+    console.log();
+
+    // Get persistence manager
+    const pm = agent.getPersistenceManager();
+    if (pm) {
+      // Query sessions
+      const sessions = await pm.getUserSessions("user_123");
+      console.log(`📊 Found ${sessions.length} session(s) for user_123`);
+
+      if (sessions.length > 0) {
+        const session = sessions[0];
+        console.log(`   Session ID: ${session.id}`);
+        console.log(`   Status: ${session.status}`);
+        console.log(`   Messages: ${session.messageCount || 0}`);
+        console.log();
+
+        // Query messages
+        const messages = await pm.getSessionMessages(session.id);
+        console.log(`📝 Session has ${messages.length} message(s):`);
+        messages.forEach((msg, idx) => {
+          console.log(
+            `   ${idx + 1}. [${msg.role}] ${msg.content.substring(0, 50)}...`
+          );
+        });
+      }
+    }
+
+    console.log("\n✅ OpenSearch persistence example completed!");
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.3.20",
+  "version": "0.3.22",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -87,7 +87,9 @@
     "redis": "^4.6.0 || ^5.0.0",
     "mongodb": "^6.0.0 || ^7.0.0",
     "pg": "^8.11.0",
-    "mysql2": "^3.2.0"
+    "mysql2": "^3.2.0",
+    "better-sqlite3": "^11.0.0 || ^12.0.0",
+    "@opensearch-project/opensearch": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "@prisma/client": {
@@ -107,6 +109,12 @@
     },
     "mysql2": {
       "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    },
+    "@opensearch-project/opensearch": {
+      "optional": true
     }
   }
 }