@hazeljs/agent 0.2.0-alpha.1

package/PERSISTENCE.md

@@ -0,0 +1,201 @@
+# Agent State Persistence
+
+> **Note**: This document covers **Agent State Persistence** (execution flow, steps, state transitions).  
+> For information about **Memory Persistence** (conversation history, entities, facts), see `@hazeljs/rag` documentation.  
+> For understanding the difference between State and Memory, see [STATE_VS_MEMORY.md](./STATE_VS_MEMORY.md).
+
+The `@hazeljs/agent` package supports multiple persistence backends for agent execution state. Choose the right backend based on your needs:
+
+## Available Backends
+
+### 1. In-Memory (Default)
+- **Best for**: Development, testing, single-instance deployments
+- **Pros**: Fast, no setup required
+- **Cons**: Data lost on restart, not suitable for distributed systems
+
+### 2. Redis
+- **Best for**: Production, distributed systems, high-performance scenarios
+- **Pros**: Fast, distributed, TTL support, pub/sub capabilities
+- **Cons**: Requires Redis infrastructure
+
+### 3. Database (Prisma)
+- **Best for**: Long-term persistence, audit trails, analytics
+- **Pros**: Durable, queryable, full audit trail
+- **Cons**: Slower than Redis, requires database setup
+
+## Usage
+
+### In-Memory (Default)
+
+No configuration needed - this is the default:
+
+```typescript
+import { AgentRuntime } from '@hazeljs/agent';
+
+const runtime = new AgentRuntime({
+  // Uses in-memory state manager by default
+});
+```
+
+### Redis Backend
+
+1. Install Redis client:
+```bash
+npm install redis
+```
+
+2. Configure Redis state manager:
+
+```typescript
+import { AgentRuntime, RedisStateManager } from '@hazeljs/agent';
+import { createClient } from 'redis';
+
+// Create Redis client
+const redisClient = createClient({
+  url: process.env.REDIS_URL || 'redis://localhost:6379',
+});
+
+await redisClient.connect();
+
+// Create Redis state manager
+const stateManager = new RedisStateManager({
+  client: redisClient,
+  keyPrefix: 'agent:state:', // Optional
+  defaultTTL: 3600, // 1 hour for active contexts
+  completedTTL: 86400, // 24 hours for completed contexts
+  failedTTL: 604800, // 7 days for failed contexts
+});
+
+// Use with runtime
+const runtime = new AgentRuntime({
+  stateManager,
+});
+```
+
+### Database Backend (Prisma)
+
+1. Install Prisma:
+```bash
+npm install @prisma/client
+```
+
+2. Add schema to your Prisma schema:
+   - Copy models from `prisma-schema.example.prisma` to your `prisma/schema.prisma`
+   - See [PRISMA_INTEGRATION.md](./PRISMA_INTEGRATION.md) for detailed instructions
+
+3. Run migrations:
+```bash
+npx prisma migrate dev --name add_agent_state_models
+npx prisma generate
+```
+
+4. Configure database state manager:
+
+```typescript
+import { AgentRuntime, DatabaseStateManager } from '@hazeljs/agent';
+import { PrismaClient } from '@prisma/client';
+
+// Create Prisma client
+const prisma = new PrismaClient();
+
+// Create database state manager
+const stateManager = new DatabaseStateManager({
+  client: prisma,
+  softDelete: true, // Keep deleted contexts for audit
+  autoArchive: false, // Optional: auto-archive old contexts
+  archiveThresholdDays: 30,
+});
+
+// Use with runtime
+const runtime = new AgentRuntime({
+  stateManager,
+});
+```
+
+## Hybrid Approach (Recommended for Production)
+
+Use Redis for hot data and Database for cold/archived data:
+
+```typescript
+import { AgentRuntime, RedisStateManager, DatabaseStateManager } from '@hazeljs/agent';
+
+// Redis for active executions
+const redisStateManager = new RedisStateManager({
+  client: redisClient,
+  defaultTTL: 3600,
+});
+
+// Database for persistence and audit
+const dbStateManager = new DatabaseStateManager({
+  client: prisma,
+});
+
+// Use Redis for runtime
+const runtime = new AgentRuntime({
+  stateManager: redisStateManager,
+});
+
+// Optionally sync to database periodically
+setInterval(async () => {
+  const activeContexts = await redisStateManager.getSessionContexts(sessionId);
+  for (const context of activeContexts) {
+    if (context.state === 'completed' || context.state === 'failed') {
+      // Archive to database
+      await dbStateManager.createContext(
+        context.agentId,
+        context.sessionId,
+        context.input,
+        context.userId,
+        context.metadata
+      );
+    }
+  }
+}, 60000); // Every minute
+```
+
+## RAG Memory Persistence
+
+RAG memory (conversation history, entities, facts) uses the `@hazeljs/rag` package's `MemoryManager`, which supports:
+
+- **BufferMemory**: In-memory (default)
+- **VectorMemory**: Vector stores (Pinecone, Weaviate, Qdrant, ChromaDB)
+- **HybridMemory**: Combination of both
+
+See `@hazeljs/rag` documentation for RAG memory configuration.
+
+## Performance Considerations
+
+- **Redis**: Best for high-frequency reads/writes, distributed systems
+- **Database**: Best for long-term storage, complex queries, analytics
+- **In-Memory**: Best for development, single-instance deployments
+
+## Migration Guide
+
+### From In-Memory to Redis
+
+1. Install Redis and client
+2. Create RedisStateManager
+3. Pass to AgentRuntime config
+4. No code changes needed - interface is compatible
+
+### From In-Memory to Database
+
+1. Install Prisma
+2. Add schema and run migrations
+3. Create DatabaseStateManager
+4. Pass to AgentRuntime config
+5. No code changes needed - interface is compatible
+
+## Best Practices
+
+1. **Development**: Use in-memory (default)
+2. **Staging**: Use Redis for testing distributed scenarios
+3. **Production**: Use Redis for active state, Database for audit/analytics
+4. **High Volume**: Use Redis with appropriate TTL settings
+5. **Compliance**: Use Database for full audit trails
+
+## Related Documentation
+
+- **[PRISMA_INTEGRATION.md](./PRISMA_INTEGRATION.md)** - Step-by-step guide for integrating Prisma schema
+- **[STATE_VS_MEMORY.md](./STATE_VS_MEMORY.md)** - Understanding the difference between Agent State and Memory
+- **[prisma-schema.example.prisma](./prisma-schema.example.prisma)** - Example Prisma schema file

package/PRISMA_INTEGRATION.md

@@ -0,0 +1,499 @@
+# Prisma Integration Guide
+
+This guide shows you how to integrate the Agent State Persistence models into your existing Prisma schema.
+
+## Quick Start
+
+### Step 1: Add Models to Your Schema
+
+Copy the models from `prisma-schema.example.prisma` into your existing `prisma/schema.prisma` file:
+
+```prisma
+// Your existing schema.prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql" // or "mysql", "sqlite", etc.
+  url      = env("DATABASE_URL")
+}
+
+// Your existing models...
+model User {
+  id    Int     @id @default(autoincrement())
+  name  String
+  email String  @unique
+}
+
+// Add these Agent State models:
+model AgentContext {
+  id                String   @id @default(uuid())
+  executionId      String   @unique
+  agentId          String
+  sessionId        String
+  userId           String?
+  input            String
+  state            String   // AgentState enum as string
+  steps            Json     // AgentStep[]
+  conversationHistory Json   // ConversationMessage[]
+  workingMemory    Json     // Record<string, unknown>
+  facts            Json     // string[]
+  entities         Json     // Entity[]
+  ragContext       Json?    // string[]
+  metadata         Json     // Record<string, unknown>
+  createdAt        DateTime @default(now())
+  updatedAt        DateTime @updatedAt
+  deletedAt        DateTime? // For soft deletes
+  agentSteps       AgentStep[] // Relation to steps table (optional)
+
+  @@index([sessionId])
+  @@index([userId])
+  @@index([agentId])
+  @@index([state])
+  @@index([createdAt])
+  @@index([deletedAt])
+  @@map("agent_contexts")
+}
+
+// Optional: Separate table for execution steps (for better querying)
+model AgentStep {
+  id            String   @id @default(uuid())
+  executionId   String
+  stepNumber    Int
+  state         String
+  action        Json?
+  result        Json?
+  error         String?
+  timestamp     DateTime @default(now())
+  duration      Int?
+
+  context       AgentContext @relation(fields: [executionId], references: [executionId], onDelete: Cascade)
+
+  @@index([executionId])
+  @@index([timestamp])
+  @@map("agent_steps")
+}
+
+// Optional: Session tracking
+model AgentSession {
+  id            String   @id @default(uuid())
+  sessionId     String   @unique
+  userId        String?
+  agentId       String
+  createdAt     DateTime @default(now())
+  updatedAt     DateTime @updatedAt
+  completedAt   DateTime?
+
+  @@index([userId])
+  @@index([agentId])
+  @@index([createdAt])
+  @@map("agent_sessions")
+}
+```
+
+### Step 2: Create Migration
+
+```bash
+# Create a new migration
+npx prisma migrate dev --name add_agent_state_models
+
+# Or if using migrate manually
+npx prisma migrate dev
+```
+
+### Step 3: Generate Prisma Client
+
+```bash
+npx prisma generate
+```
+
+### Step 4: Use in Your Code
+
+```typescript
+import { AgentRuntime, DatabaseStateManager } from '@hazeljs/agent';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+const stateManager = new DatabaseStateManager({
+  client: prisma,
+  softDelete: true,
+});
+
+const runtime = new AgentRuntime({
+  stateManager,
+});
+```
+
+## Integration Options
+
+### Option 1: Minimal (Recommended)
+
+Add only the `AgentContext` model. Steps are stored as JSON in the context:
+
+```prisma
+model AgentContext {
+  id                String   @id @default(uuid())
+  executionId      String   @unique
+  agentId          String
+  sessionId        String
+  userId           String?
+  input            String
+  state            String
+  steps            Json     // All steps stored here
+  conversationHistory Json
+  workingMemory    Json
+  facts            Json
+  entities         Json
+  ragContext       Json?
+  metadata         Json
+  createdAt        DateTime @default(now())
+  updatedAt        DateTime @updatedAt
+  deletedAt        DateTime?
+
+  @@index([sessionId])
+  @@index([userId])
+  @@index([agentId])
+  @@index([state])
+  @@map("agent_contexts")
+}
+```
+
+**Pros**: Simple, single table, fast writes  
+**Cons**: Can't query steps independently
+
+### Option 2: Full (For Analytics)
+
+Add all three models (`AgentContext`, `AgentStep`, `AgentSession`) for better querying:
+
+```prisma
+model AgentContext {
+  // ... fields ...
+  agentSteps       AgentStep[] // Relation
+}
+
+model AgentStep {
+  // ... fields ...
+  context       AgentContext @relation(...)
+}
+
+model AgentSession {
+  // ... fields ...
+}
+```
+
+**Pros**: Can query steps independently, better for analytics  
+**Cons**: More complex, requires joins
+
+### Option 3: Custom Schema
+
+Adapt the schema to your needs:
+
+```prisma
+// Example: Add relation to your User model
+model User {
+  id            Int     @id @default(autoincrement())
+  name          String
+  email         String  @unique
+  agentContexts AgentContext[] // Add this
+}
+
+model AgentContext {
+  // ... fields ...
+  userId        String?
+  user          User?   @relation(fields: [userId], references: [id]) // Add this
+}
+```
+
+## Database Compatibility
+
+### PostgreSQL (Recommended)
+
+```prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+```
+
+✅ Full support for JSON fields  
+✅ Excellent indexing  
+✅ Best performance
+
+### MySQL
+
+```prisma
+datasource db {
+  provider = "mysql"
+  url      = env("DATABASE_URL")
+}
+```
+
+✅ JSON support (MySQL 5.7+)  
+✅ Good performance  
+⚠️ Use `Json` type for JSON fields
+
+### SQLite
+
+```prisma
+datasource db {
+  provider = "sqlite"
+  url      = env("DATABASE_URL")
+}
+```
+
+✅ Works for development  
+⚠️ JSON stored as TEXT (slower queries)  
+⚠️ Not recommended for production
+
+### SQL Server
+
+```prisma
+datasource db {
+  provider = "sqlserver"
+  url      = env("DATABASE_URL")
+}
+```
+
+✅ JSON support (SQL Server 2016+)  
+✅ Good for enterprise
+
+## Migration Examples
+
+### Initial Migration
+
+```bash
+# Create migration
+npx prisma migrate dev --name add_agent_state_models
+
+# This will create:
+# - agent_contexts table
+# - agent_steps table (if included)
+# - agent_sessions table (if included)
+# - All indexes
+```
+
+### Adding to Existing Database
+
+If you already have a database with other tables:
+
+```bash
+# Prisma will detect the new models
+npx prisma migrate dev --name add_agent_state
+
+# Review the migration SQL before applying
+npx prisma migrate dev --create-only
+# Edit the migration file if needed
+npx prisma migrate dev
+```
+
+## Schema Customization
+
+### Customize Field Types
+
+```prisma
+model AgentContext {
+  // Use your own ID format
+  id          String   @id @default(cuid()) // or @default(uuid())
+  
+  // Add custom fields
+  priority    Int      @default(0)
+  tags        String[]
+  
+  // Customize JSON fields
+  metadata    Json     @default("{}")
+}
+```
+
+### Add Relations
+
+```prisma
+model User {
+  id            Int     @id @default(autoincrement())
+  agentContexts AgentContext[]
+}
+
+model AgentContext {
+  userId        String?
+  user          User?   @relation(fields: [userId], references: [id])
+}
+```
+
+### Custom Indexes
+
+```prisma
+model AgentContext {
+  // ... fields ...
+  
+  // Add composite indexes
+  @@index([agentId, state])
+  @@index([sessionId, createdAt])
+  
+  // Add full-text search (PostgreSQL)
+  @@index([input(ops: Raw("gin_trgm_ops"))])
+}
+```
+
+## Using with HazelJS Prisma Module
+
+If you're using `@hazeljs/prisma`:
+
+```typescript
+import { HazelModule } from '@hazeljs/core';
+import { PrismaModule } from '@hazeljs/prisma';
+import { AgentModule } from '@hazeljs/agent';
+import { PrismaClient } from '@prisma/client';
+import { DatabaseStateManager } from '@hazeljs/agent';
+
+@HazelModule({
+  imports: [
+    PrismaModule.forRoot({
+      // Your Prisma config
+    }),
+    AgentModule.forRoot({
+      // Agent config
+    }),
+  ],
+})
+export class AppModule {
+  constructor(private prisma: PrismaClient) {
+    // Create state manager
+    const stateManager = new DatabaseStateManager({
+      client: this.prisma,
+    });
+    
+    // Use with AgentRuntime
+    // (configure in your agent service)
+  }
+}
+```
+
+## Troubleshooting
+
+### Error: "Model AgentContext not found"
+
+**Solution**: Make sure you've:
+1. Added the model to your schema
+2. Run `npx prisma generate`
+3. Restarted your application
+
+### Error: "Column does not exist"
+
+**Solution**: Run migrations:
+```bash
+npx prisma migrate dev
+```
+
+### JSON Field Issues
+
+**PostgreSQL**: Use `Json` type (works out of the box)  
+**MySQL**: Use `Json` type (MySQL 5.7+)  
+**SQLite**: Use `String` type and parse manually, or use `Json` (stored as TEXT)
+
+### Performance Issues
+
+1. **Add indexes** on frequently queried fields:
+   ```prisma
+   @@index([sessionId])
+   @@index([userId])
+   @@index([state])
+   ```
+
+2. **Use soft deletes** to avoid expensive DELETE operations:
+   ```prisma
+   deletedAt DateTime?
+   @@index([deletedAt])
+   ```
+
+3. **Partition large tables** (PostgreSQL):
+   ```sql
+   -- Partition by date for very large tables
+   CREATE TABLE agent_contexts_2024_12 PARTITION OF agent_contexts
+   FOR VALUES FROM ('2024-12-01') TO ('2025-01-01');
+   ```
+
+## Example: Complete Integration
+
+```prisma
+// prisma/schema.prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+// Your existing models
+model User {
+  id            Int     @id @default(autoincrement())
+  email         String  @unique
+  name          String
+  agentContexts AgentContext[] // Relation
+}
+
+// Agent State models
+model AgentContext {
+  id                String   @id @default(uuid())
+  executionId      String   @unique
+  agentId          String
+  sessionId        String
+  userId           String?
+  user             User?    @relation(fields: [userId], references: [id])
+  input            String
+  state            String
+  steps            Json
+  conversationHistory Json
+  workingMemory    Json
+  facts            Json
+  entities         Json
+  ragContext       Json?
+  metadata         Json
+  createdAt        DateTime @default(now())
+  updatedAt        DateTime @updatedAt
+  deletedAt        DateTime?
+
+  @@index([sessionId])
+  @@index([userId])
+  @@index([agentId])
+  @@index([state])
+  @@index([createdAt])
+  @@map("agent_contexts")
+}
+```
+
+```typescript
+// app.module.ts
+import { HazelModule } from '@hazeljs/core';
+import { PrismaModule } from '@hazeljs/prisma';
+import { AgentModule } from '@hazeljs/agent';
+import { DatabaseStateManager } from '@hazeljs/agent';
+
+@HazelModule({
+  imports: [
+    PrismaModule.forRoot({}),
+    AgentModule.forRoot({
+      stateManager: new DatabaseStateManager({
+        client: prismaClient, // From PrismaModule
+        softDelete: true,
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Next Steps
+
+1. ✅ Add models to your schema
+2. ✅ Run migrations
+3. ✅ Generate Prisma client
+4. ✅ Configure DatabaseStateManager
+5. ✅ Test with your agents
+
+For more details, see:
+- [PERSISTENCE.md](./PERSISTENCE.md) - Configuration guide
+- [STATE_VS_MEMORY.md](./STATE_VS_MEMORY.md) - Understanding State vs Memory
+- [prisma-schema.example.prisma](./prisma-schema.example.prisma) - Full schema example