@mtkn/mega-agent 0.4.0 → 0.5.0

package/README.md

@@ -14,7 +14,7 @@ AI-powered agent infrastructure for Express + Prisma backends. Drop-in chat API
 - **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
+- **MCP support** — Model Context Protocol for external data sources _(not managed by `createMegaAgent`; must be initialized and disposed separately — see [MCP section](#mcp))_
 - **Prisma persistence** — 12 models, fully typed
 
 ## Quick Start
@@ -55,7 +55,6 @@ app.use('/api/chat', agent.createChatRouter(authMiddleware));
 |---|---|
 | Qdrant | Vector database for semantic search |
 | OpenAI API | Embedding model (`text-embedding-3-small`) |
-| Redis + BullMQ | Job queue (for workflows) |
 
 ## Installation
 
@@ -69,7 +68,7 @@ npm install -D prisma @types/express typescript
 
 ## Prisma Schema Setup
 
-The package requires 16 enums and 12 models in your Prisma schema.
+The package requires 15 enums and 12 models in your Prisma schema.
 
 ### Option A: Automatic Sync (Recommended)
 
@@ -181,8 +180,8 @@ npx prisma generate
 
 ```typescript
 interface MegaAgentConfig {
-  /** Prisma client instance */
-  prisma: PrismaClient;
+  /** Prisma client instance (also accepts TransactionClient) */
+  prisma: PrismaClient | Prisma.TransactionClient;
 
   /** Logger with info/error/warn/debug methods */
   logger: LoggerLike;
@@ -208,6 +207,7 @@ interface MegaAgentConfig {
       host: string;                  // default: 'localhost'
       port: number;                  // default: 6333
       apiKey?: string;
+      userIdType?: 'string' | 'number'; // default: 'number'
     };
   };
 
@@ -411,6 +411,43 @@ if (getWorkflowServiceDeps()) {
 }
 ```
 
+You can also mount the chat router directly using `createChatRoutes` — the same low-level function that `agent.createChatRouter()` uses internally:
+
+```typescript
+import { createChatRoutes, ChatController } from '@mtkn/mega-agent';
+
+// Requires services to be initialized (via createMegaAgent or manually)
+const controller = new ChatController();
+const router = createChatRoutes(controller, authMiddleware);
+app.use('/api/chat', router);
+```
+
+### MCP
+
+MCP services (`McpService`, `SourceService`) are **not** managed by `createMegaAgent()`. They must be initialized and disposed separately:
+
+```typescript
+import {
+  initMcpService,
+  McpService,
+  disposeMcpService,
+  initSourceService,
+  SourceService,
+  disposeSourceService,
+} from '@mtkn/mega-agent';
+
+// Initialize
+initMcpService({ prisma, logger });
+initSourceService({ prisma, logger });
+
+const mcp = new McpService();
+const sources = new SourceService();
+
+// Dispose (async — must be awaited)
+await disposeMcpService();
+await disposeSourceService();
+```
+
 ## API Endpoints
 
 The chat router creates the following endpoints:
@@ -447,9 +484,15 @@ Content-Type: application/json
   "data": {
     "userMessage": { "id": "...", "role": "USER", "content": "..." },
     "assistantMessage": { "id": "...", "role": "ASSISTANT", "content": "..." },
-    "memories": [],
+    "usedMemories": [],
     "tokens": { "prompt": 1200, "completion": 350, "total": 1550 },
-    "latencyMs": 2340
+    "latencyMs": 2340,
+    "structured": {
+      "type": "answer",
+      "content": "Here are today's production stats...",
+      "quality": { "signal": "strong", "confidence": 0.92 },
+      "toolsUsed": [{ "name": "get_dashboard", "description": "Get dashboard data", "executionTimeMs": 120 }]
+    }
   }
 }
 ```
@@ -462,6 +505,7 @@ Content-Type: application/json
   "data": {
     "userMessage": { "id": "...", "role": "USER", "content": "..." },
     "assistantMessage": { "id": "...", "role": "ASSISTANT", "content": "I want to execute **create_order**..." },
+    "usedMemories": [],
     "pendingApproval": {
       "id": "a1b2c3d4-...",
       "chatId": "chat-id",
@@ -477,6 +521,32 @@ Content-Type: application/json
 
 Use the `pendingApproval.id` value as the `approvalId` when calling the approve or reject endpoints.
 
+### Structured Response
+
+The `structured` field is a parsed representation of the LLM output, designed for rich frontend rendering. It is present on both regular and approve responses.
+
+```typescript
+interface StructuredResponse {
+  type: 'answer' | 'table' | 'chart' | 'agent_created' | 'report' | 'error';
+  content: string;                    // Markdown content (always present)
+  data?: TableData | ChartData | AgentData | Record<string, unknown>;
+  quality?: { signal: 'strong' | 'moderate' | 'weak'; confidence: number; reasoning?: string };
+  sources?: { name: string; type: 'memory' | 'database' | 'api' | 'tool' | 'document'; relevance: number }[];
+  toolsUsed?: { name: string; description: string; executionTimeMs?: number }[];
+  memory?: { saved?: boolean; savedContent?: string; referencedIds?: string[] };
+  artifact?: { suggestedTitle: string; type: 'TABLE' | 'CHART' | 'REPORT' | 'CODE' | 'DATASET'; data: unknown };
+}
+```
+
+| Type | When |
+|------|------|
+| `answer` | Default — plain text or markdown response |
+| `table` | Response contains tabular data (`data` is `TableData`) |
+| `chart` | Response contains chart data (`data` is `ChartData`) |
+| `report` | Response is a generated report |
+| `agent_created` | A workflow agent was created (`data` is `AgentData`) |
+| `error` | An error occurred during processing |
+
 **SSE Streaming:**
 
 When `stream: true`, the response uses Server-Sent Events:
@@ -484,10 +554,10 @@ 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}}
+data: {"type":"content","content":"Here are"}
+data: {"type":"content","content":" today's stats..."}
+data: {"type":"tool_status","toolName":"get_dashboard","content":"Executing get_dashboard..."}
+data: {"type":"done"}
 ```
 
 ### Approve Tool Call
@@ -511,7 +581,13 @@ The server executes the tool using the original `toolName` and `arguments` store
   "data": {
     "assistantMessage": { "id": "...", "role": "ASSISTANT", "content": "Order created successfully..." },
     "tokens": { "prompt": 2100, "completion": 220, "total": 2320 },
-    "latencyMs": 3100
+    "latencyMs": 3100,
+    "structured": {
+      "type": "answer",
+      "content": "Order created successfully...",
+      "quality": { "signal": "strong", "confidence": 0.95 },
+      "toolsUsed": [{ "name": "create_order", "description": "Create a new order. Requires approval.", "executionTimeMs": 85 }]
+    }
   }
 }
 ```
@@ -575,14 +651,14 @@ Agent processes with LLM
             │
             ├── POST /:id/approve { approvalId } → executes tool → agent continues
             │
-            └── POST /:id/reject { approvalId } → approval cancelled → agent informed
+            └── POST /:id/reject { approvalId } → approval cancelled
 ```
 
 Conversation state (LLM message history) is stored **server-side** in an in-memory store with a 10-minute TTL. The client only receives an opaque `approvalId` — never the raw conversation state.
 
 ## Prisma Models
 
-The package uses 12 models and 16 enums:
+The package uses 12 models and 15 enums:
 
 | Model | Purpose |
 |-------|---------|
@@ -599,6 +675,20 @@ The package uses 12 models and 16 enums:
 | `AiTimelineEvent` | Event log for audit trail |
 | `AiUserPreferences` | Per-user AI settings |
 
+### MemoryType Enum
+
+The `create_memory` tool and `MemoryService` use the `MemoryType` enum to categorize stored memories:
+
+| Value | Description |
+|-------|-------------|
+| `FACT` | Concrete, verifiable piece of information |
+| `INSIGHT` | Analytical observation or inference derived from data |
+| `DECISION` | A choice or resolution made by the user or system |
+| `PATTERN` | Recurring trend or behavior detected over time |
+| `INCIDENT` | Anomaly or notable event captured by the incident service |
+| `REPORT_SUMMARY` | Condensed summary of a generated report |
+| `USER_PREFERENCE` | User-specific setting or preference |
+
 ## Environment Variables
 
 | Variable | Required | Description | Default |
@@ -697,6 +787,20 @@ All service methods accept `UserId` for the `userId` parameter, so your app work
 
 ## Changelog
 
+### v0.5.0
+
+- **Breaking: `bullmq` dependency removed** — Redis + BullMQ is no longer a dependency. Workflow job queue must be provided externally if needed.
+- **Breaking: `MemoryType` enum changed** — `PROCEDURE` removed; `INCIDENT`, `REPORT_SUMMARY`, `USER_PREFERENCE` added.
+- **Breaking: SSE event types renamed** — `chunk` → `content`, `tool_call` → `tool_status`. `done` event no longer includes token data.
+- **Breaking: Response field renamed** — `memories` → `usedMemories` in chat and approve responses.
+- **Structured response** — New `structured` field in chat and approve responses with typed output (`answer`, `table`, `chart`, `report`, `agent_created`, `error`), quality signal, sources, and tools used.
+- **TransactionClient support** — `MegaAgentConfig.prisma` now accepts `PrismaClient | Prisma.TransactionClient`.
+- **`createChatRoutes` export** — Low-level chat router factory is now documented and available for manual mounting.
+- **MCP lifecycle docs** — `McpService` and `SourceService` are not managed by `createMegaAgent`; init/dispose documented separately.
+- **`userIdType` config option** — Qdrant config now accepts `userIdType: 'string' | 'number'`.
+- **Package rename refs** — Internal comments updated from `@7style/mega-agent` to `@mtkn/mega-agent`.
+- **Enum count fix** — Documentation corrected from 16 enums to 15.
+
 ### v0.4.0
 
 - **Breaking: Zero LLM providers now throws** — `createMegaAgent()` throws `ConfigValidationError` if `llm.providers` is empty. Previously it only logged a warning, causing all chat operations to fail at runtime.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @7style/mega-agent
+ * @mtkn/mega-agent
  *
  * AI-powered agent services for memory, chat, LLM, embeddings,
  * vector search, MCP, incidents, workflows, and artifacts.

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
- * @7style/mega-agent
+ * @mtkn/mega-agent
  *
  * AI-powered agent services for memory, chat, LLM, embeddings,
  * vector search, MCP, incidents, workflows, and artifacts.

package/dist/tools/core-tools.js

@@ -29,7 +29,7 @@ export const CORE_TOOLS = [
             properties: {
                 title: { type: 'string', description: 'Memory title' },
                 content: { type: 'string', description: 'Content' },
-                type: { type: 'string', description: 'Type', enum: ['FACT', 'INSIGHT', 'DECISION', 'PATTERN', 'PROCEDURE'] },
+                type: { type: 'string', description: 'Type', enum: ['FACT', 'INSIGHT', 'DECISION', 'PATTERN', 'INCIDENT', 'REPORT_SUMMARY', 'USER_PREFERENCE'] },
             },
             required: ['title', 'content'],
         },

package/dist/tools/core-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"core-tools.js","sourceRoot":"","sources":["../../src/tools/core-tools.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,UAAU,GAAqB;IAC1C;QACE,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,4CAA4C;QACzD,QAAQ,EAAE,MAAM;QAChB,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE;gBACtD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE;aAC9C;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;YAC9B,MAAM,EAAE,oBAAoB,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;YACnF,IAAI,CAAC,oBAAoB,EAAE;gBAAE,OAAO,EAAE,CAAC;YACvC,MAAM,CAAC,GAAG,IAAI,aAAa,EAAE,CAAC;YAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAe,EAAE,KAAK,EAAG,IAAI,CAAC,KAAgB,IAAI,CAAC,EAAE,CAAC,CAAC;YAC9G,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACjH,CAAC;KACF;IACD;QACE,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,2DAA2D;QACxE,QAAQ,EAAE,OAAO;QACjB,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE;gBACtD,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE;gBACnD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE;aAC7G;YACD,QAAQ,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC;SAC/B;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;YAC9B,MAAM,EAAE,oBAAoB,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;YACnF,IAAI,CAAC,oBAAoB,EAAE;gBAAE,OAAO,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC;YACtE,MAAM,GAAG,GAAG,IAAI,aAAa,EAAE,CAAC;YAChC,OAAO,GAAG,CAAC,YAAY,CAAC;gBACtB,MAAM;gBACN,KAAK,EAAE,IAAI,CAAC,KAAe;gBAC3B,OAAO,EAAE,IAAI,CAAC,OAAiB;gBAC/B,IAAI,EAAG,IAAI,CAAC,IAAe,IAAI,SAAS;gBACxC,UAAU,EAAE,MAAM;gBAClB,UAAU,EAAE,GAAG;aAChB,CAAC,CAAC;QACL,CAAC;KACF;CACF,CAAC"}
+{"version":3,"file":"core-tools.js","sourceRoot":"","sources":["../../src/tools/core-tools.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,UAAU,GAAqB;IAC1C;QACE,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,4CAA4C;QACzD,QAAQ,EAAE,MAAM;QAChB,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE;gBACtD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE;aAC9C;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;YAC9B,MAAM,EAAE,oBAAoB,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;YACnF,IAAI,CAAC,oBAAoB,EAAE;gBAAE,OAAO,EAAE,CAAC;YACvC,MAAM,CAAC,GAAG,IAAI,aAAa,EAAE,CAAC;YAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAe,EAAE,KAAK,EAAG,IAAI,CAAC,KAAgB,IAAI,CAAC,EAAE,CAAC,CAAC;YAC9G,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACjH,CAAC;KACF;IACD;QACE,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,2DAA2D;QACxE,QAAQ,EAAE,OAAO;QACjB,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE;gBACtD,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE;gBACnD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,gBAAgB,EAAE,iBAAiB,CAAC,EAAE;aACjJ;YACD,QAAQ,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC;SAC/B;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;YAC9B,MAAM,EAAE,oBAAoB,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;YACnF,IAAI,CAAC,oBAAoB,EAAE;gBAAE,OAAO,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC;YACtE,MAAM,GAAG,GAAG,IAAI,aAAa,EAAE,CAAC;YAChC,OAAO,GAAG,CAAC,YAAY,CAAC;gBACtB,MAAM;gBACN,KAAK,EAAE,IAAI,CAAC,KAAe;gBAC3B,OAAO,EAAE,IAAI,CAAC,OAAiB;gBAC/B,IAAI,EAAG,IAAI,CAAC,IAAe,IAAI,SAAS;gBACxC,UAAU,EAAE,MAAM;gBAClB,UAAU,EAAE,GAAG;aAChB,CAAC,CAAC;QACL,CAAC;KACF;CACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mtkn/mega-agent",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "AI-powered agent infrastructure for Express + Prisma backends",
   "type": "module",
   "main": "./dist/index.js",
@@ -52,7 +52,6 @@
     "@google/generative-ai": "^0.24.1",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@qdrant/js-client-rest": "^1.16.2",
-    "bullmq": "^5.67.2",
     "openai": "^6.18.0",
     "winston": "^3.12.0",
     "zod": "^3.22.4"

package/prisma/schema.prisma

@@ -1,8 +1,8 @@
 // ============================================================
-// @7style/mega-agent — Reference Prisma Schema
+// @mtkn/mega-agent — Reference Prisma Schema
 // ============================================================
 //
-// Bu dosya @7style/mega-agent paketinin ihtiyaç duyduğu veritabanı
+// Bu dosya @mtkn/mega-agent paketinin ihtiyaç duyduğu veritabanı
 // modellerini ve enum'larını dokümante eder.
 //
 // Host entegrasyonu için: npx mega-agent-prisma-sync --target prisma/schema.prisma