@node-llm/orm 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to `@node-llm/orm` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-18
+
+### Added
+
+- **Chat Persistence**: Automatic tracking of chat sessions, messages, and conversation history
+- **Streaming Support**: Full support for `chat.askStream()` with automatic message persistence as tokens arrive
+- **Custom Fields Support**: Pass additional fields (e.g., `userId`, `projectId`) directly to `createChat()` - they're automatically spread into the Prisma create call
+- **Native JSON Metadata**: Metadata passed as-is to support native `Json`/`JSONB` database types for efficient querying
+- **Optional Persistence Configuration**: New `persistence` option allows selective disabling of tool call and request tracking
+  - `persistence.toolCalls`: Enable/disable tool call persistence (default: `true`)
+  - `persistence.requests`: Enable/disable API request metrics (default: `true`)
+- **Tool Call Tracking**: Audit log of every tool execution with arguments and results
+- **API Request Metrics**: Track latency, tokens, and cost for every API call
+- **Custom Table Names**: Support for custom Prisma table names
+- **Comprehensive Tests**: 24 unit tests covering all features
+- **Example Application**: Complete HR Chatbot RAG example demonstrating all ORM features
+- **TypeScript Support**: Full type safety with Prisma and TypeScript
+- **Prisma Adapter**: Production-ready adapter for Prisma ORM
+
+### Example Usage
+
+```typescript
+// Custom fields
+const chat = await createChat(prisma, llm, {
+  model: "gpt-4",
+  userId: "user_123",
+  projectId: "proj_456",
+  metadata: { source: "web-ui", tags: ["support"] }
+});
+
+// Optional persistence
+const chat = await createChat(prisma, llm, {
+  model: "gpt-4",
+  persistence: {
+    toolCalls: false, // Skip tool call tracking
+    requests: true // Keep request metrics
+  }
+});
+
+// Streaming with persistence
+for await (const token of chat.askStream("Hello")) {
+  process.stdout.write(token);
+}
+// Messages automatically persisted after stream completes
+```
+
+## [Unreleased]
+
+### Planned
+
+- Support for custom message types
+- Batch operations for message history
+- Advanced query helpers
+
+---
+
+[0.1.0]: https://github.com/node-llm/node-llm/releases/tag/orm-v0.1.0

package/README.md

@@ -0,0 +1,353 @@
+# @node-llm/orm
+
+[![npm version](https://img.shields.io/npm/v/@node-llm/orm.svg)](https://www.npmjs.com/package/@node-llm/orm)
+[![npm downloads](https://img.shields.io/npm/dm/@node-llm/orm.svg)](https://www.npmjs.com/package/@node-llm/orm)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+> Database persistence layer for NodeLLM. Automatically tracks chats, messages, tool calls, and API requests.
+
+**[Read the Full Documentation](https://node-llm.github.io/orm/prisma.html)** | **[View Example App](../../examples/hr-chatbot-rag/)**
+
+## Features
+
+- ✅ **Automatic Persistence** - Messages, tool calls, and API metrics saved automatically
+- ✅ **Streaming Support** - Real-time token delivery with `askStream()`
+- ✅ **Provider Agnostic** - Works with any NodeLLM provider (OpenAI, Anthropic, Gemini, OpenRouter, etc.)
+- ✅ **Type Safe** - Full TypeScript support with Prisma
+- ✅ **Audit Trail** - Complete history of tool executions and API calls
+- ✅ **Flexible** - Prisma adapter included, other ORMs can be added
+
+## Installation
+
+```bash
+npm install @node-llm/orm @node-llm/core @prisma/client
+npm install -D prisma
+```
+
+## Quick Start
+
+### Option 1: Using the CLI (Recommended)
+
+```bash
+# Generate schema.prisma automatically
+npx node-llm-orm init
+
+# Create and apply migration
+npx prisma migrate dev --name init
+npx prisma generate
+```
+
+### Option 2: Manual Setup
+
+Copy the reference schema into your project:
+
+```bash
+cp node_modules/@node-llm/orm/schema.prisma prisma/schema.prisma
+```
+
+Or manually add the models to your existing `prisma/schema.prisma`:
+
+```prisma
+model LlmChat {
+  id           String       @id @default(uuid())
+  model        String?
+  provider     String?
+  instructions String?      @db.Text
+  metadata     String?      @db.Text
+  createdAt    DateTime     @default(now())
+  updatedAt    DateTime     @updatedAt
+
+  messages     LlmMessage[]
+  requests     LlmRequest[]
+}
+
+model LlmMessage {
+  id           String        @id @default(uuid())
+  chatId       String
+  role         String
+  content      String?       @db.Text
+  // ... see schema.prisma for full definition
+}
+
+model LlmToolCall {
+  id         String   @id @default(uuid())
+  messageId  String
+  toolCallId String
+  name       String
+  arguments  String   @db.Text
+  // ... see schema.prisma for full definition
+}
+
+model LlmRequest {
+  id           String   @id @default(uuid())
+  chatId       String
+  messageId    String?
+  provider     String
+  model        String
+  // ... see schema.prisma for full definition
+}
+```
+
+### 2. Run Migration
+
+```bash
+npx prisma migrate dev --name init
+npx prisma generate
+```
+
+### 3. Use the ORM
+
+```typescript
+import { PrismaClient } from "@prisma/client";
+import { createLLM } from "@node-llm/core";
+import { createChat } from "@node-llm/orm/prisma";
+
+const prisma = new PrismaClient();
+const llm = createLLM({ provider: "openai" });
+
+// Create a new chat
+const chat = await createChat(prisma, llm, {
+  model: "gpt-4",
+  instructions: "You are a helpful assistant."
+});
+
+// Ask a question (automatically persisted)
+const response = await chat.ask("What is the capital of France?");
+console.log(response.content); // "The capital of France is Paris."
+
+// View conversation history
+const messages = await chat.messages();
+console.log(messages); // [{ role: 'user', content: '...' }, { role: 'assistant', content: '...' }]
+```
+
+## Architecture
+
+The ORM tracks four core entities:
+
+| Model           | Purpose              | Example                                    |
+| --------------- | -------------------- | ------------------------------------------ |
+| **LlmChat**     | Session container    | Holds model, provider, system instructions |
+| **LlmMessage**  | Conversation history | User queries and assistant responses       |
+| **LlmToolCall** | Tool executions      | Function calls made by the assistant       |
+| **LlmRequest**  | API metrics          | Token usage, latency, cost per API call    |
+
+### Data Flow
+
+```
+User Input
+    ↓
+Chat.ask()
+    ↓
+┌─────────────────────────────────────┐
+│ 1. Create User Message (DB)        │
+│ 2. Create Assistant Message (DB)   │
+│ 3. Fetch History (DB)              │
+│ 4. Call LLM API                     │
+│    ├─ onToolCallEnd → ToolCall (DB)│
+│    └─ afterResponse → Request (DB) │
+│ 5. Update Assistant Message (DB)   │
+└─────────────────────────────────────┘
+    ↓
+Return Response
+```
+
+## Advanced Usage
+
+### Streaming Responses
+
+For real-time UX, use `askStream()` to yield tokens as they arrive:
+
+```typescript
+import { createChat } from "@node-llm/orm/prisma";
+
+const chat = await createChat(prisma, llm, {
+  model: "gpt-4"
+});
+
+// Stream tokens in real-time
+for await (const token of chat.askStream("Tell me a story")) {
+  process.stdout.write(token); // Print each token immediately
+}
+
+// Message is automatically persisted after streaming completes
+const messages = await chat.messages();
+console.log(messages[messages.length - 1].content); // Full story
+```
+
+### React/Next.js Streaming Example
+
+```typescript
+// app/api/chat/route.ts
+import { createChat } from "@node-llm/orm/prisma";
+
+export async function POST(req: Request) {
+  const { message, chatId } = await req.json();
+
+  const chat = chatId
+    ? await loadChat(prisma, llm, chatId)
+    : await createChat(prisma, llm, { model: "gpt-4" });
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      for await (const token of chat.askStream(message)) {
+        controller.enqueue(new TextEncoder().encode(token));
+      }
+      controller.close();
+    }
+  });
+
+  return new Response(stream);
+}
+```
+
+### Custom Table Names
+
+If you have existing tables with different names (e.g., `AssistantChat` instead of `Chat`), you can specify custom table names:
+
+```typescript
+import { createChat } from "@node-llm/orm/prisma";
+
+const tableNames = {
+  chat: "assistantChat",
+  message: "assistantMessage",
+  toolCall: "assistantToolCall",
+  request: "assistantRequest"
+};
+
+// Create chat with custom table names
+const chat = await createChat(prisma, llm, { model: "gpt-4" }, tableNames);
+
+// Load chat (must use same table names)
+const loaded = await loadChat(prisma, llm, chatId, tableNames);
+```
+
+**Note**: Your Prisma schema model names must match the table names you specify. For example:
+
+```prisma
+model AssistantChat {
+  // ... fields
+  @@map("assistantChat") // Optional: map to different database table name
+}
+```
+
+### With Tools
+
+```typescript
+import { createChat } from "@node-llm/orm/prisma";
+import { searchTool } from "./tools/search";
+
+const chat = await createChat(prisma, llm, {
+  model: "gpt-4",
+  tools: [searchTool]
+});
+
+await chat.ask("Search for NodeLLM documentation");
+// Tool calls are automatically persisted to ToolCall table
+```
+
+### Loading Existing Chats
+
+```typescript
+import { loadChat } from "@node-llm/orm/prisma";
+
+const chat = await loadChat(prisma, llm, "chat-id-123");
+if (chat) {
+  await chat.ask("Continue our conversation");
+}
+```
+
+### Querying Metrics
+
+```typescript
+// Get all API requests for a chat
+const requests = await prisma.request.findMany({
+  where: { chatId: chat.id },
+  orderBy: { createdAt: "desc" }
+});
+
+console.log(
+  `Total tokens: ${requests.reduce((sum, r) => sum + r.inputTokens + r.outputTokens, 0)}`
+);
+console.log(`Total cost: $${requests.reduce((sum, r) => sum + (r.cost || 0), 0)}`);
+```
+
+### Custom Fields & Metadata
+
+You can add custom fields (like `userId`, `projectId`, `tenantId`) to your Prisma schema and pass them directly to `createChat`. The library will pass these fields through to the generic Prisma create call.
+
+**1. Update your Prisma Schema:**
+
+```prisma
+model LlmChat {
+  // ... standard fields
+  metadata     Json?      // Use Json type for flexible storage
+  userId       String?    // Custom field
+  projectId    String?    // Custom field
+}
+```
+
+**2. Pass fields to createChat:**
+
+```typescript
+const chat = await createChat(prisma, llm, {
+  model: "gpt-4",
+  instructions: "You are consistent.",
+  // Custom fields passed directly
+  userId: "user_123",
+  projectId: "proj_abc",
+  // Metadata is passed as-is (native JSON support)
+  metadata: {
+    source: "web-client",
+    tags: ["experiment-a"]
+  }
+});
+```
+
+### Persistence Configuration
+
+By default, the ORM persists everything: messages, tool calls, and API requests. If you don't need certain tables (e.g., you're building a minimal app without tool tracking), you can disable specific persistence features:
+
+```typescript
+const chat = await createChat(prisma, llm, {
+  model: "gpt-4",
+  persistence: {
+    toolCalls: false, // Skip LlmToolCall table
+    requests: false // Skip LlmRequest table
+  }
+});
+```
+
+**Use Cases:**
+
+- **Minimal Schema**: Only create `LlmChat` and `LlmMessage` tables
+- **Privacy**: Disable request logging for sensitive applications
+- **Performance**: Reduce database writes for high-throughput scenarios
+
+**Note**: Message persistence is always enabled (required for conversation history).
+
+## Environment Variables
+
+The ORM respects NodeLLM's provider configuration:
+
+```bash
+# Chat Provider
+NODELLM_PROVIDER="openrouter"
+NODELLM_MODEL="google/gemini-2.0-flash-001"
+
+# Embedding Provider (optional, for RAG apps)
+NODELLM_EMBEDDING_PROVIDER="openai"
+NODELLM_EMBEDDING_MODEL="text-embedding-3-small"
+```
+
+## Roadmap
+
+- [ ] TypeORM adapter
+- [ ] Drizzle adapter
+- [ ] Migration utilities
+- [ ] Analytics dashboard
+- [ ] Export/import conversations
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * @node-llm/orm migration generator
+ *
+ * Usage:
+ *   npx @node-llm/orm init          # Generate schema.prisma
+ *   npx @node-llm/orm migrate       # Create and apply migration
+ */
+
+import { writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+
+const SCHEMA_TEMPLATE = `// This is your Prisma schema file
+// Generated by @node-llm/orm
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+// NodeLLM ORM Models
+model LlmLlmChat {
+  id           String    @id @default(uuid())
+  model        String?
+  provider     String?
+  instructions String?   @db.Text
+  metadata     String?   @db.Text
+  createdAt    DateTime  @default(now())
+  updatedAt    DateTime  @updatedAt
+  
+  messages     LlmMessage[]
+  requests     LlmRequest[]
+
+  @@index([createdAt])
+}
+
+model LlmLlmMessage {
+  id           String      @id @default(uuid())
+  chatId       String
+  role         String
+  content      String?     @db.Text
+  contentRaw   String?     @db.Text
+  reasoning    String?     @db.Text
+  inputTokens  Int?
+  outputTokens Int?
+  modelId      String?
+  provider     String?
+  createdAt    DateTime    @default(now())
+
+  chat         LlmChat        @relation(fields: [chatId], references: [id], onDelete: Cascade)
+  toolCalls    LlmToolCall[]
+  requests     LlmRequest[]
+
+  @@index([chatId])
+  @@index([createdAt])
+}
+
+model LlmToolCall {
+  id           String   @id @default(uuid())
+  messageId    String
+  toolCallId   String
+  name         String
+  arguments    String   @db.Text
+  result       String?  @db.Text
+  createdAt    DateTime @default(now())
+
+  message      LlmMessage  @relation(fields: [messageId], references: [id], onDelete: Cascade)
+
+  @@index([messageId])
+  @@index([createdAt])
+}
+
+model LlmRequest {
+  id           String   @id @default(uuid())
+  chatId       String
+  messageId    String?
+  
+  provider     String
+  model        String
+  statusCode   Int
+  duration     Int
+  inputTokens  Int
+  outputTokens Int
+  cost         Float?
+  
+  createdAt    DateTime @default(now())
+
+  chat         LlmChat     @relation(fields: [chatId], references: [id], onDelete: Cascade)
+  message      Message? @relation(fields: [messageId], references: [id], onDelete: Cascade)
+
+  @@index([chatId])
+  @@index([createdAt])
+}
+`;
+
+function init() {
+  const cwd = process.cwd();
+  const prismaDir = join(cwd, "prisma");
+  const schemaPath = join(prismaDir, "schema.prisma");
+
+  // Create prisma directory if it doesn't exist
+  if (!existsSync(prismaDir)) {
+    mkdirSync(prismaDir, { recursive: true });
+    console.log("✓ Created prisma/ directory");
+  }
+
+  // Check if schema already exists
+  if (existsSync(schemaPath)) {
+    console.log("⚠️  schema.prisma already exists");
+    console.log("   To add NodeLLM models, manually copy from:");
+    console.log("   node_modules/@node-llm/orm/schema.prisma");
+    return;
+  }
+
+  // Write schema
+  writeFileSync(schemaPath, SCHEMA_TEMPLATE);
+  console.log("✓ Generated prisma/schema.prisma");
+  console.log("\nNext steps:");
+  console.log("  1. Update DATABASE_URL in .env");
+  console.log("  2. Run: npx prisma migrate dev --name init");
+  console.log("  3. Run: npx prisma generate");
+}
+
+function migrate() {
+  console.log("Running Prisma migration...");
+  console.log("\nPlease run:");
+  console.log("  npx prisma migrate dev --name add_nodellm_orm");
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  switch (command) {
+    case "init":
+      init();
+      break;
+    case "migrate":
+      migrate();
+      break;
+    default:
+      console.log("@node-llm/orm - Database migration tool\n");
+      console.log("Usage:");
+      console.log("  npx @node-llm/orm init     # Generate schema.prisma");
+      console.log("  npx @node-llm/orm migrate  # Create migration");
+      console.log("\nFor custom table names, see:");
+      console.log(
+        "  https://github.com/node-llm/node-llm/tree/main/packages/orm#custom-table-names"
+      );
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@node-llm/orm",
+  "version": "0.1.0",
+  "description": "Database persistence layer for NodeLLM - Chat, Message, and ToolCall tracking with streaming support",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "node-llm-orm": "./bin/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./prisma": {
+      "import": "./dist/adapters/prisma/index.js",
+      "types": "./dist/adapters/prisma/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "llm",
+    "orm",
+    "prisma",
+    "chat",
+    "chatbot",
+    "persistence",
+    "database",
+    "nodejs",
+    "typescript",
+    "openai",
+    "anthropic",
+    "gemini",
+    "streaming",
+    "rag",
+    "retrieval-augmented-generation",
+    "conversation",
+    "message-history",
+    "tool-calling",
+    "ai",
+    "artificial-intelligence",
+    "nextjs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/node-llm/node-llm.git",
+    "directory": "packages/orm"
+  },
+  "homepage": "https://github.com/node-llm/node-llm/tree/main/packages/orm",
+  "bugs": {
+    "url": "https://github.com/node-llm/node-llm/issues"
+  },
+  "author": "NodeLLM Contributors",
+  "license": "MIT",
+  "peerDependencies": {
+    "@node-llm/core": "^1.0.0",
+    "@prisma/client": "^5.0.0"
+  },
+  "devDependencies": {
+    "@node-llm/core": "file:../core",
+    "@prisma/client": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "dependencies": {}
+}