@mtkn/mega-agent 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,564 @@
+# @mtkn/mega-agent
+
+[![npm version](https://img.shields.io/npm/v/@mtkn/mega-agent.svg)](https://www.npmjs.com/package/@mtkn/mega-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+AI-powered agent infrastructure for Express + Prisma backends. Drop-in chat API with tool calling, long-term memory, incident detection, workflow automation, and more.
+
+## Features
+
+- **Multi-provider LLM** — Anthropic, OpenAI, Gemini, or custom endpoints
+- **Tool calling** with read/write approval workflow
+- **Long-term memory** — embedding + Qdrant vector search (optional)
+- **Chat API** with SSE streaming and 4 chat modes
+- **Incident detection** — anomaly detection with severity levels
+- **Workflow automation** — schedule, event, threshold, and manual triggers
+- **Artifact storage** — reports, tables, charts, code, images, datasets
+- **MCP support** — Model Context Protocol for external data sources
+- **Prisma persistence** — 12 models, fully typed
+
+## Quick Start
+
+```bash
+npm install @mtkn/mega-agent
+```
+
+```typescript
+import { createMegaAgent } from '@mtkn/mega-agent';
+
+const agent = await createMegaAgent({
+  prisma,
+  logger,
+  llm: {
+    providers: [
+      { provider: 'anthropic', apiKey: 'sk-ant-...', defaultModel: 'claude-sonnet-4-20250514' },
+    ],
+  },
+});
+
+app.use('/api/chat', agent.createChatRouter(authMiddleware));
+```
+
+## Requirements
+
+| Requirement | Version |
+|---|---|
+| Node.js | >= 18.17 |
+| TypeScript | 5.x |
+| Express | 4.x |
+| Prisma | 6.x |
+| PostgreSQL | 14+ |
+
+**Optional services (for memory system):**
+
+| Service | Purpose |
+|---|---|
+| Qdrant | Vector database for semantic search |
+| OpenAI API | Embedding model (`text-embedding-3-small`) |
+| Redis + BullMQ | Job queue (for workflows) |
+
+## Installation
+
+```bash
+npm install @mtkn/mega-agent
+
+# Peer dependencies (should already be in your project)
+npm install @prisma/client express
+npm install -D prisma @types/express typescript
+```
+
+## Prisma Schema Setup
+
+The package requires 16 enums and 12 models in your Prisma schema.
+
+### Option A: Automatic Sync (Recommended)
+
+```bash
+npx mega-agent-prisma-sync --target prisma/schema.prisma
+```
+
+This copies all mega-agent enums and models into your schema between marker comments. Running it again updates only the marked section.
+
+### Option B: Manual Copy
+
+Copy all enums and models from the reference schema:
+
+```bash
+# View the reference schema
+cat node_modules/@mtkn/mega-agent/prisma/schema.prisma
+```
+
+### Add User Relations
+
+Each AI model has a `userId` field. Add relations in your `User` model:
+
+```prisma
+model User {
+  // ... your existing fields ...
+
+  // AI Agent relations
+  aiMemories           AiMemory[]
+  aiMemorySuggestions   AiMemorySuggestion[]
+  aiChats              AiChat[]
+  aiArtifacts          AiArtifact[]
+  aiMcpSources         AiMcpSource[]
+  aiWorkflows          AiWorkflow[]
+  aiIncidents          AiIncident[]
+  aiTimelineEvents     AiTimelineEvent[]
+  aiReports            AiReport[]
+  aiPreferences        AiUserPreferences?
+}
+```
+
+And add the reverse relation in each AI model:
+
+```prisma
+user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+```
+
+### Add Notification Model
+
+The workflow service uses `prisma.notification.create()`. Your schema needs:
+
+```prisma
+model Notification {
+  id        Int      @id @default(autoincrement())
+  userId    Int      @map("user_id")
+  type      String
+  title     String
+  message   String
+  isRead    Boolean  @default(false) @map("is_read")
+  createdAt DateTime @default(now()) @map("created_at")
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  @@map("notifications")
+}
+```
+
+### Run Migration
+
+```bash
+npx prisma migrate dev --name add_mega_agent_models
+npx prisma generate
+```
+
+## Configuration
+
+```typescript
+interface MegaAgentConfig {
+  /** Prisma client instance */
+  prisma: PrismaClient;
+
+  /** Logger with info/error/warn/debug methods */
+  logger: LoggerLike;
+
+  /** LLM provider configs (at least 1 required) */
+  llm: {
+    providers: Array<{
+      provider: 'anthropic' | 'openai' | 'gemini' | 'custom';
+      apiKey: string;
+      defaultModel?: string;
+      baseUrl?: string;     // only for 'custom'
+    }>;
+  };
+
+  /** Memory system — omit to disable */
+  memory?: {
+    embedding: {
+      apiKey: string;
+      provider?: 'openai';           // default: 'openai'
+      defaultModel?: string;         // default: 'text-embedding-3-small'
+    };
+    qdrant: {
+      host: string;                  // default: 'localhost'
+      port: number;                  // default: 6333
+      apiKey?: string;
+    };
+  };
+
+  /** Agent identity (for system prompt customization) */
+  agent?: {
+    agentName?: string;
+    agentDescription?: string;
+    customPrompt?: string;
+  };
+}
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import type { Express } from 'express';
+import { createMegaAgent } from '@mtkn/mega-agent';
+import { prisma } from './lib/prisma-client.js';
+import { logger } from './lib/logger.js';
+import { authMiddleware } from './middleware/auth.js';
+
+export async function initChatModule(app: Express): Promise<void> {
+  const providers = [];
+
+  if (process.env.ANTHROPIC_API_KEY) {
+    providers.push({
+      provider: 'anthropic' as const,
+      apiKey: process.env.ANTHROPIC_API_KEY,
+      defaultModel: process.env.ANTHROPIC_DEFAULT_MODEL || 'claude-sonnet-4-20250514',
+    });
+  }
+
+  if (process.env.OPENAI_API_KEY) {
+    providers.push({
+      provider: 'openai' as const,
+      apiKey: process.env.OPENAI_API_KEY,
+      defaultModel: process.env.OPENAI_DEFAULT_MODEL || 'gpt-4o',
+    });
+  }
+
+  // Memory config (optional — requires OpenAI key + Qdrant)
+  const memory = process.env.OPENAI_API_KEY
+    ? {
+        embedding: {
+          apiKey: process.env.OPENAI_API_KEY,
+          provider: 'openai' as const,
+          defaultModel: process.env.EMBEDDING_MODEL || 'text-embedding-3-small',
+        },
+        qdrant: {
+          host: process.env.QDRANT_HOST || 'localhost',
+          port: parseInt(process.env.QDRANT_PORT || '6333', 10),
+          apiKey: process.env.QDRANT_API_KEY || undefined,
+        },
+      }
+    : undefined;
+
+  const agent = await createMegaAgent({
+    prisma,
+    logger,
+    llm: { providers },
+    memory,
+    agent: {
+      agentName: 'ProductionAssistant',
+      agentDescription: 'Manufacturing management AI assistant',
+    },
+  });
+
+  // Register domain-specific tools (see below)
+  registerMyTools();
+
+  // Mount chat routes
+  app.use('/api/chat', agent.createChatRouter(authMiddleware));
+}
+```
+
+### Auth Middleware
+
+The chat router requires an auth middleware that sets `req.user` with at least an `id` field:
+
+```typescript
+type AuthMiddleware = (req: Request, res: Response, next: NextFunction) => void;
+
+// Your middleware must set:
+// req.user = { id: number, ... }
+```
+
+### Registering Domain Tools
+
+Tools give the AI agent access to your application's data and actions. The package comes with 2 built-in tools (`search_memory`, `create_memory`) when memory is enabled. Register your own domain tools after calling `createMegaAgent()`:
+
+```typescript
+import { registerTools } from '@mtkn/mega-agent';
+import type { ToolDefinition } from '@mtkn/mega-agent';
+
+const tools: ToolDefinition[] = [
+  // Read tools — auto-executed, no user approval needed
+  {
+    name: 'list_products',
+    description: 'List products with optional status filter',
+    category: 'read',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: { type: 'string', description: 'Filter by status', enum: ['ACTIVE', 'ARCHIVED'] },
+        limit:  { type: 'number', description: 'Max results (default 20)' },
+      },
+    },
+    handler: async (args, userId) => {
+      return prisma.product.findMany({
+        where: args.status ? { status: args.status as string } : undefined,
+        take: (args.limit as number) || 20,
+      });
+    },
+  },
+
+  // Write tools — require user approval before execution
+  {
+    name: 'create_order',
+    description: 'Create a new order. Requires approval.',
+    category: 'write',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        productId: { type: 'number', description: 'Product ID' },
+        quantity:  { type: 'number', description: 'Order quantity' },
+      },
+      required: ['productId', 'quantity'],
+    },
+    handler: async (args, userId) => {
+      return prisma.order.create({
+        data: {
+          productId: args.productId as number,
+          quantity: args.quantity as number,
+          userId,
+        },
+      });
+    },
+  },
+];
+
+export function registerMyTools(): void {
+  registerTools(tools);
+}
+```
+
+**Tool Categories:**
+- `read` — Auto-executed by the agent, no approval needed
+- `write` — Agent pauses and waits for user approval via `POST /:id/approve`
+
+### Using Services Independently
+
+You can use individual services without the full chat stack:
+
+```typescript
+import { initLLMService, LLMService } from '@mtkn/mega-agent';
+import type { LLMProviderConfig } from '@mtkn/mega-agent';
+
+// Initialize the LLM service once
+const providers: LLMProviderConfig[] = [
+  { provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY!, defaultModel: 'claude-sonnet-4-20250514' },
+];
+initLLMService({ config: providers, logger });
+
+// Use it anywhere
+const llm = new LLMService();
+const response = await llm.complete({
+  messages: [
+    { role: 'system', content: 'You are a risk analyst.' },
+    { role: 'user', content: 'Analyze this production data...' },
+  ],
+  temperature: 0.3,
+});
+```
+
+Other services (after `createMegaAgent()` has been called):
+
+```typescript
+import {
+  IncidentService, getIncidentServiceDeps,
+  WorkflowService, getWorkflowServiceDeps,
+  ArtifactService, getArtifactServiceDeps,
+} from '@mtkn/mega-agent';
+
+// Check if dependencies are initialized
+if (getIncidentServiceDeps()) {
+  const incidents = new IncidentService();
+  // Use incident detection...
+}
+
+if (getWorkflowServiceDeps()) {
+  const workflows = new WorkflowService();
+  // Use workflow automation...
+}
+```
+
+## API Endpoints
+
+The chat router creates the following endpoints:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/` | Create a new chat session |
+| `GET` | `/` | List user's chats (paginated) |
+| `GET` | `/:id` | Get chat with full message history |
+| `PATCH` | `/:id` | Update chat (title, mode, model, etc.) |
+| `DELETE` | `/:id` | Delete chat and all messages |
+| `POST` | `/:id/messages` | Send message (agent responds) |
+| `POST` | `/:id/approve` | Approve a pending write tool call |
+| `POST` | `/:id/reject` | Reject a pending write tool call |
+
+### Send Message
+
+```bash
+POST /api/chat/:id/messages
+Content-Type: application/json
+
+{
+  "content": "Show me today's production stats",
+  "model": "claude-sonnet-4-20250514",   // optional override
+  "stream": true                          // optional SSE streaming
+}
+```
+
+**Response (non-streaming):**
+
+```json
+{
+  "success": true,
+  "data": {
+    "userMessage": { "id": "...", "role": "USER", "content": "..." },
+    "assistantMessage": { "id": "...", "role": "ASSISTANT", "content": "..." },
+    "memories": [],
+    "tokens": { "prompt": 1200, "completion": 350, "total": 1550 },
+    "latencyMs": 2340
+  }
+}
+```
+
+**SSE Streaming:**
+
+When `stream: true`, the response uses Server-Sent Events:
+
+```
+Content-Type: text/event-stream
+
+data: {"type":"chunk","content":"Here are"}
+data: {"type":"chunk","content":" today's stats..."}
+data: {"type":"tool_call","name":"get_dashboard","args":{}}
+data: {"type":"done","tokens":{"prompt":1200,"completion":350}}
+```
+
+## Chat Modes
+
+Each chat session has a mode that shapes the agent's behavior:
+
+| Mode | Description |
+|------|-------------|
+| `EXPLORE` | Analysis, insights, data exploration. Agent focuses on understanding and explaining. |
+| `GENERATE` | Content creation. Agent produces structured output (reports, tables, code). |
+| `EXECUTE` | Action-oriented. Agent actively uses tools to perform tasks. |
+| `AUTOMATE` | Workflow setup. Agent helps create triggers, conditions, and automated actions. |
+
+Set the mode when creating or updating a chat:
+
+```bash
+POST /api/chat
+{ "mode": "EXECUTE", "title": "Production Management" }
+```
+
+## Tool Approval Flow
+
+```
+User sends message
+    │
+    ▼
+Agent processes with LLM
+    │
+    ├── Uses read tool → auto-executes → continues
+    │
+    └── Uses write tool → pauses
+            │
+            ▼
+        Returns pending tool call to client
+            │
+            ├── POST /:id/approve → executes tool → agent continues
+            │
+            └── POST /:id/reject  → agent informed → responds accordingly
+```
+
+## Prisma Models
+
+The package uses 12 models and 16 enums:
+
+| Model | Purpose |
+|-------|---------|
+| `AiMemory` | Long-term memory with vector embeddings |
+| `AiMemorySuggestion` | AI-suggested memories for user review |
+| `AiChat` | Chat sessions with mode and settings |
+| `AiChatMessage` | Individual messages with token tracking |
+| `AiArtifact` | Generated content (reports, charts, code, etc.) |
+| `AiIncident` | Detected anomalies with severity and status |
+| `AiMcpSource` | Model Context Protocol data sources |
+| `AiWorkflow` | Automated workflows with triggers and actions |
+| `AiWorkflowExecution` | Workflow execution history |
+| `AiReport` | Generated reports (daily, weekly, monthly) |
+| `AiTimelineEvent` | Event log for audit trail |
+| `AiUserPreferences` | Per-user AI settings |
+
+## Environment Variables
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `ANTHROPIC_API_KEY` | At least 1 LLM key | Anthropic API key | — |
+| `ANTHROPIC_DEFAULT_MODEL` | No | Default Anthropic model | `claude-sonnet-4-20250514` |
+| `OPENAI_API_KEY` | At least 1 LLM key | OpenAI API key | — |
+| `OPENAI_DEFAULT_MODEL` | No | Default OpenAI model | `gpt-4o` |
+| `EMBEDDING_MODEL` | No | OpenAI embedding model | `text-embedding-3-small` |
+| `QDRANT_HOST` | No | Qdrant server host | `localhost` |
+| `QDRANT_PORT` | No | Qdrant server port | `6333` |
+| `QDRANT_API_KEY` | No | Qdrant auth key | — |
+
+## MegaAgent Return Type
+
+```typescript
+interface MegaAgent {
+  /** Access to service instances */
+  services: {
+    chat: ChatService;
+    llm: LLMService;
+    memory: MemoryService | null;     // null if memory not configured
+    embedding: EmbeddingService | null;
+    qdrant: QdrantService | null;
+  };
+
+  /** Prompt settings */
+  promptOptions: {
+    agentName?: string;
+    agentDescription?: string;
+    customPrompt?: string;
+  };
+
+  /** Create Express router with all chat endpoints */
+  createChatRouter(authMiddleware: AuthMiddleware): Router;
+}
+```
+
+## Troubleshooting
+
+### `Module '@prisma/client' has no exported member 'AiChat'`
+
+Prisma client needs to be regenerated:
+
+```bash
+npx prisma generate
+```
+
+If using a monorepo with linked packages, ensure there's only one `@prisma/client` instance. Add a postinstall script to deduplicate:
+
+```json
+{
+  "scripts": {
+    "postinstall": "rm -rf node_modules/@mtkn/mega-agent/node_modules/@prisma node_modules/@mtkn/mega-agent/node_modules/.prisma 2>/dev/null || true"
+  }
+}
+```
+
+### Memory system not starting
+
+- Verify `OPENAI_API_KEY` is set and valid
+- Check Qdrant is running: `curl http://localhost:6333/collections`
+- Memory is optional — chat works without it
+
+### Tools not being used by the agent
+
+- Call `registerTools()` **after** `createMegaAgent()`
+- Ensure `inputSchema` is valid JSON Schema (`type: 'object'` at root)
+- Tool `handler` must return a `Promise`
+- Check tool `description` — the LLM uses it to decide when to call the tool
+
+### Agent not responding or timing out
+
+- The agent loop has a max of 10 iterations per message
+- Up to 20 context messages are sent to the LLM
+- Check LLM API key validity and rate limits
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mtkn/mega-agent",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AI-powered agent infrastructure for Express + Prisma backends",
   "type": "module",
   "main": "./dist/index.js",

package/prisma/schema.prisma

@@ -363,7 +363,7 @@ model AiArtifact {
 // ── INCIDENT SYSTEM ─────────────────────────────────────────
 
 model AiIncident {
-  id              String           @id @default(uuid())
+  id              String           @id @default(cuid())
   userId          Int              @map("user_id")
   fingerprint     String
   title           String           @db.VarChar(255)
@@ -475,7 +475,7 @@ model AiWorkflowExecution {
 // ── REPORT SYSTEM ───────────────────────────────────────────
 
 model AiReport {
-  id          String     @id @default(uuid())
+  id          String     @id @default(cuid())
   userId      Int        @map("user_id")
   type        ReportType
   title       String     @db.VarChar(255)
@@ -501,7 +501,7 @@ model AiReport {
 // ── TIMELINE SYSTEM ─────────────────────────────────────────
 
 model AiTimelineEvent {
-  id         String        @id @default(uuid())
+  id         String        @id @default(cuid())
   userId     Int           @map("user_id")
   type       EventType
   title      String        @db.VarChar(255)
@@ -526,7 +526,7 @@ model AiTimelineEvent {
 // ── USER PREFERENCES ────────────────────────────────────────
 
 model AiUserPreferences {
-  id     String @id @default(uuid())
+  id     String @id @default(cuid())
   userId Int    @unique @map("user_id")
 
   // AI Settings