@falai/agent 0.3.11 → 0.3.12

package/dist/types/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/types/persistence.ts"],"names":[],"mappings":"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"}

package/dist/types/persistence.js

@@ -0,0 +1,6 @@
+/**
+ * Persistence-related type definitions
+ * Support for optional database persistence (Prisma, etc.)
+ */
+export {};
+//# sourceMappingURL=persistence.js.map

package/dist/types/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/types/persistence.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

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!