@node-llm/orm 0.4.0 → 0.5.0

package/dist/adapters/prisma/index.d.ts

@@ -4,7 +4,7 @@
  * Prisma adapter for NodeLLM ORM.
  * Provides automatic persistence of chats, messages, tool calls, and API requests.
  *
- * @example
+ * @example Chat API (low-level)
  * ```typescript
  * import { PrismaClient } from '@prisma/client';
  * import { createLLM } from '@node-llm/core';
@@ -21,7 +21,30 @@
  * const response = await chat.ask('Hello!');
  * console.log(response.content);
  * ```
+ *
+ * @example AgentSession API (recommended for agents)
+ * ```typescript
+ * import { Agent } from '@node-llm/core';
+ * import { createAgentSession, loadAgentSession } from '@node-llm/orm/prisma';
+ *
+ * class SupportAgent extends Agent {
+ *   static model = 'gpt-4.1';
+ *   static instructions = 'You are a helpful support agent.';
+ * }
+ *
+ * // Create new session
+ * const session = await createAgentSession(prisma, llm, SupportAgent, {
+ *   metadata: { userId: 'user_123' }
+ * });
+ * await session.ask('Hello!');
+ *
+ * // Resume later (Code Wins - model/tools from class, history from DB)
+ * const session = await loadAgentSession(prisma, llm, SupportAgent, sessionId);
+ * await session.ask('Continue our conversation');
+ * ```
  */
 export { Chat, createChat, loadChat } from "./Chat.js";
-export type { ChatRecord, MessageRecord, ChatOptions, TableNames } from "./Chat.js";
+export type { ChatRecord, MessageRecord, ChatOptions } from "./Chat.js";
+export { AgentSession, createAgentSession, loadAgentSession } from "./AgentSession.js";
+export type { AgentSessionRecord, CreateAgentSessionOptions, LoadAgentSessionOptions, TableNames } from "./AgentSession.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/adapters/prisma/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/prisma/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACvD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/prisma/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAGH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACvD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAGxE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvF,YAAY,EACV,kBAAkB,EAClB,yBAAyB,EACzB,uBAAuB,EACvB,UAAU,EACX,MAAM,mBAAmB,CAAC"}

package/dist/adapters/prisma/index.js

@@ -4,7 +4,7 @@
  * Prisma adapter for NodeLLM ORM.
  * Provides automatic persistence of chats, messages, tool calls, and API requests.
  *
- * @example
+ * @example Chat API (low-level)
  * ```typescript
  * import { PrismaClient } from '@prisma/client';
  * import { createLLM } from '@node-llm/core';
@@ -21,5 +21,29 @@
  * const response = await chat.ask('Hello!');
  * console.log(response.content);
  * ```
+ *
+ * @example AgentSession API (recommended for agents)
+ * ```typescript
+ * import { Agent } from '@node-llm/core';
+ * import { createAgentSession, loadAgentSession } from '@node-llm/orm/prisma';
+ *
+ * class SupportAgent extends Agent {
+ *   static model = 'gpt-4.1';
+ *   static instructions = 'You are a helpful support agent.';
+ * }
+ *
+ * // Create new session
+ * const session = await createAgentSession(prisma, llm, SupportAgent, {
+ *   metadata: { userId: 'user_123' }
+ * });
+ * await session.ask('Hello!');
+ *
+ * // Resume later (Code Wins - model/tools from class, history from DB)
+ * const session = await loadAgentSession(prisma, llm, SupportAgent, sessionId);
+ * await session.ask('Continue our conversation');
+ * ```
  */
+// Chat API
 export { Chat, createChat, loadChat } from "./Chat.js";
+// AgentSession API
+export { AgentSession, createAgentSession, loadAgentSession } from "./AgentSession.js";

package/dist/index.d.ts

@@ -23,13 +23,33 @@
  * await chat.ask('Hello!');
  * ```
  *
+ * ## Agent Sessions (Recommended for Agents)
+ *
+ * ```typescript
+ * import { Agent } from '@node-llm/core';
+ * import { createAgentSession, loadAgentSession } from '@node-llm/orm/prisma';
+ *
+ * class SupportAgent extends Agent {
+ *   static model = 'gpt-4.1';
+ *   static instructions = 'You are a helpful support agent.';
+ * }
+ *
+ * // Create and persist
+ * const session = await createAgentSession(prisma, llm, SupportAgent);
+ * await session.ask('Hello!');
+ *
+ * // Resume later (Code Wins - model/tools from class, history from DB)
+ * const session = await loadAgentSession(prisma, llm, SupportAgent, sessionId);
+ * ```
+ *
  * ## Adapters
  *
  * - `@node-llm/orm/prisma` - Prisma adapter (recommended)
  *
  * ## Schema
  *
- * The ORM tracks four core entities:
+ * The ORM tracks five core entities:
+ * - **AgentSession** - Links Agent class to persistent Chat (v0.5.0+)
  * - **Chat** - Session container (model, provider, instructions)
  * - **Message** - User/Assistant conversation history
  * - **ToolCall** - Tool executions (name, arguments, results)

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAGH,cAAc,4BAA4B,CAAC"}

package/dist/index.js

@@ -23,13 +23,33 @@
  * await chat.ask('Hello!');
  * ```
  *
+ * ## Agent Sessions (Recommended for Agents)
+ *
+ * ```typescript
+ * import { Agent } from '@node-llm/core';
+ * import { createAgentSession, loadAgentSession } from '@node-llm/orm/prisma';
+ *
+ * class SupportAgent extends Agent {
+ *   static model = 'gpt-4.1';
+ *   static instructions = 'You are a helpful support agent.';
+ * }
+ *
+ * // Create and persist
+ * const session = await createAgentSession(prisma, llm, SupportAgent);
+ * await session.ask('Hello!');
+ *
+ * // Resume later (Code Wins - model/tools from class, history from DB)
+ * const session = await loadAgentSession(prisma, llm, SupportAgent, sessionId);
+ * ```
+ *
  * ## Adapters
  *
  * - `@node-llm/orm/prisma` - Prisma adapter (recommended)
  *
  * ## Schema
  *
- * The ORM tracks four core entities:
+ * The ORM tracks five core entities:
+ * - **AgentSession** - Links Agent class to persistent Chat (v0.5.0+)
  * - **Chat** - Session container (model, provider, instructions)
  * - **Message** - User/Assistant conversation history
  * - **ToolCall** - Tool executions (name, arguments, results)

package/migrations/README.md

@@ -0,0 +1,53 @@
+# @node-llm/orm Migrations
+
+Reference SQL migrations for upgrading your database schema.
+
+## Who Needs These?
+
+| User Type         | Action                                                             |
+| ----------------- | ------------------------------------------------------------------ |
+| **New user**      | ❌ Skip these. Run `npx @node-llm/orm init` → full schema included |
+| **Existing user** | ✅ Use these to upgrade without losing data                        |
+
+> **Note:** These migrations are **idempotent** — safe to run multiple times. They use `IF NOT EXISTS` and conditional checks, so running them on a fresh database won't cause errors.
+
+## Available Migrations
+
+| File                       | Version | Description                                         |
+| -------------------------- | ------- | --------------------------------------------------- |
+| `add_thinking_support.sql` | v0.2.0+ | Extended Thinking columns (Claude 3.7, DeepSeek R1) |
+| `add_agent_session.sql`    | v0.5.0+ | AgentSession for persistent agent conversations     |
+
+## How to Use
+
+### Option 1: Copy and Apply
+
+```bash
+# Create migration folder
+mkdir -p prisma/migrations/$(date +%Y%m%d%H%M%S)_add_agent_session
+
+# Copy the SQL
+cp node_modules/@node-llm/orm/migrations/add_agent_session.sql \
+   prisma/migrations/$(date +%Y%m%d%H%M%S)_add_agent_session/migration.sql
+
+# Mark as applied
+npx prisma migrate resolve --applied $(date +%Y%m%d%H%M%S)_add_agent_session
+```
+
+### Option 2: Let Prisma Generate
+
+1. Update your `schema.prisma` with the new models from `@node-llm/orm/schema.prisma`
+2. Run: `npx prisma migrate dev --name add_agent_session`
+
+## Custom Table Names
+
+If you're using custom table names (e.g., `AssistantMessage` instead of `LlmMessage`),
+edit the SQL file to match your table names before applying.
+
+## Documentation
+
+See the full [Migration Guide](https://node-llm.eshaiju.com/orm/migrations) for:
+
+- Baseline migrations
+- Production deployment
+- Renaming columns safely

package/migrations/add_agent_session.sql

@@ -0,0 +1,44 @@
+-- Migration: Add AgentSession support
+-- Version: @node-llm/orm v0.5.0+
+-- 
+-- This migration adds the LlmAgentSession table for persistent agent conversations.
+-- Run this if you're upgrading from a previous version of @node-llm/orm.
+--
+-- Usage:
+--   1. Copy this file to your prisma/migrations/<timestamp>_add_agent_session/ folder
+--   2. Run: npx prisma migrate resolve --applied <timestamp>_add_agent_session
+--   Or simply run: npx prisma migrate dev --name add_agent_session
+
+-- Create the AgentSession table
+CREATE TABLE IF NOT EXISTS "LlmAgentSession" (
+    "id" TEXT NOT NULL,
+    "agentClass" TEXT NOT NULL,
+    "chatId" TEXT NOT NULL,
+    "metadata" JSONB,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "LlmAgentSession_pkey" PRIMARY KEY ("id")
+);
+
+-- Create unique constraint on chatId (1:1 with LlmChat)
+CREATE UNIQUE INDEX IF NOT EXISTS "LlmAgentSession_chatId_key" ON "LlmAgentSession"("chatId");
+
+-- Create indexes for common queries
+CREATE INDEX IF NOT EXISTS "LlmAgentSession_agentClass_idx" ON "LlmAgentSession"("agentClass");
+CREATE INDEX IF NOT EXISTS "LlmAgentSession_createdAt_idx" ON "LlmAgentSession"("createdAt");
+
+-- Add foreign key constraint (idempotent - skips if already exists)
+DO $$ 
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'LlmAgentSession_chatId_fkey'
+    ) THEN
+        ALTER TABLE "LlmAgentSession" 
+            ADD CONSTRAINT "LlmAgentSession_chatId_fkey" 
+            FOREIGN KEY ("chatId") 
+            REFERENCES "LlmChat"("id") 
+            ON DELETE CASCADE 
+            ON UPDATE CASCADE;
+    END IF;
+END $$;

package/migrations/add_thinking_support.sql

@@ -0,0 +1,34 @@
+-- Migration: Add Extended Thinking support
+-- Version: @node-llm/orm v0.2.0+
+-- 
+-- This migration adds columns for Extended Thinking (Claude 3.7+, DeepSeek R1).
+-- Run this if you're upgrading from a previous version of @node-llm/orm.
+--
+-- Usage:
+--   1. Copy this file to your prisma/migrations/<timestamp>_add_thinking_support/ folder
+--   2. Run: npx prisma migrate resolve --applied <timestamp>_add_thinking_support
+--   Or simply run: npx prisma migrate dev --name add_thinking_support
+--
+-- Note: Adjust table names if using custom names (e.g., AssistantMessage instead of LlmMessage)
+-- Note: This migration is idempotent - safe to run multiple times.
+
+-- AlterTable: Convert metadata to native JSONB (idempotent - skips if already JSONB)
+DO $$ 
+BEGIN
+    IF EXISTS (
+        SELECT 1 FROM information_schema.columns 
+        WHERE table_name = 'LlmChat' AND column_name = 'metadata' AND data_type != 'jsonb'
+    ) THEN
+        ALTER TABLE "LlmChat" ALTER COLUMN "metadata" TYPE JSONB USING metadata::JSONB;
+    END IF;
+END $$;
+
+-- AlterTable: Add thinking columns to Message
+ALTER TABLE "LlmMessage" 
+ADD COLUMN IF NOT EXISTS "thinkingText" TEXT,
+ADD COLUMN IF NOT EXISTS "thinkingSignature" TEXT,
+ADD COLUMN IF NOT EXISTS "thinkingTokens" INTEGER;
+
+-- AlterTable: Add thought signature to ToolCall
+ALTER TABLE "LlmToolCall" 
+ADD COLUMN IF NOT EXISTS "thoughtSignature" TEXT;

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@node-llm/orm",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Database persistence layer for NodeLLM - Chat, Message, and ToolCall tracking with streaming support",
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -68,6 +71,7 @@
   "scripts": {
     "build": "prisma generate --schema=schema.prisma && tsc",
     "test": "vitest run",
+    "test:docs": "vitest run test/docs",
     "test:watch": "vitest"
   }
 }

package/schema.prisma

@@ -12,53 +12,70 @@ datasource db {
 
 // NodeLLM ORM Models (matches @node-llm/orm schema)
 model LlmChat {
-  id           String       @id @default(uuid())
+  id           String           @id @default(uuid())
   model        String?
   provider     String?
-  instructions String?      // System instructions
-  metadata     Json?         // JSON metadata
-  createdAt    DateTime      @default(now())
-  updatedAt    DateTime     @updatedAt
+  instructions String? // System instructions
+  metadata     Json? // JSON metadata
+  createdAt    DateTime         @default(now())
+  updatedAt    DateTime         @updatedAt
   messages     LlmMessage[]
   requests     LlmRequest[]
+  agentSession LlmAgentSession?
+}
+
+// Agent Session - Links Agent class to persistent Chat
+// "Code defines behavior, DB provides history"
+model LlmAgentSession {
+  id         String   @id @default(uuid())
+  agentClass String // Class name for validation (e.g., 'SupportAgent')
+  chatId     String   @unique
+  metadata   Json? // Session context (userId, ticketId, etc.)
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+
+  chat LlmChat @relation(fields: [chatId], references: [id], onDelete: Cascade)
+
+  @@index([agentClass])
+  @@index([createdAt])
 }
 
 model LlmMessage {
-  id                String        @id @default(uuid())
+  id                String   @id @default(uuid())
   chatId            String
-  role              String        // user, assistant, system, tool
+  role              String // user, assistant, system, tool
   content           String?
-  contentRaw        String?       // JSON raw payload
-  reasoning         String?       // Chain of thought (deprecated)
-  thinkingText      String?       // Extended thinking text
-  thinkingSignature String?       // Cryptographic signature
-  thinkingTokens    Int?          // Tokens spent on thinking
+  contentRaw        String? // JSON raw payload
+  reasoning         String? // Chain of thought (deprecated)
+  thinkingText      String? // Extended thinking text
+  thinkingSignature String? // Cryptographic signature
+  thinkingTokens    Int? // Tokens spent on thinking
   inputTokens       Int?
   outputTokens      Int?
   modelId           String?
   provider          String?
-  createdAt         DateTime      @default(now())
+  createdAt         DateTime @default(now())
 
-  chat         LlmChat       @relation(fields: [chatId], references: [id], onDelete: Cascade)
-  toolCalls    LlmToolCall[]
-  requests     LlmRequest[]
+  chat      LlmChat       @relation(fields: [chatId], references: [id], onDelete: Cascade)
+  toolCalls LlmToolCall[]
+  requests  LlmRequest[]
 
   @@index([chatId])
   @@index([createdAt])
 }
 
 model LlmToolCall {
-  id               String     @id @default(uuid())
+  id               String   @id @default(uuid())
   messageId        String
-  toolCallId       String     // ID from the provider
+  toolCallId       String // ID from the provider
   name             String
-  arguments        String     // JSON string
-  thought          String?    // The LLM's reasoning for this tool call
-  thoughtSignature String?    // Signature for the thought
-  result           String?    // Tool execution result
-  createdAt        DateTime   @default(now())
+  arguments        String // JSON string
+  thought          String? // The LLM's reasoning for this tool call
+  thoughtSignature String? // Signature for the thought
+  result           String? // Tool execution result
+  createdAt        DateTime @default(now())
 
-  message      LlmMessage @relation(fields: [messageId], references: [id], onDelete: Cascade)
+  message LlmMessage @relation(fields: [messageId], references: [id], onDelete: Cascade)
 
   @@unique([messageId, toolCallId])
   @@index([messageId])
@@ -66,22 +83,22 @@ model LlmToolCall {
 }
 
 model LlmRequest {
-  id           String      @id @default(uuid())
-  chatId       String
-  messageId    String?     // Optional because requests might fail before message creation
-  
+  id        String  @id @default(uuid())
+  chatId    String
+  messageId String? // Optional because requests might fail before message creation
+
   provider     String
   model        String
   statusCode   Int
-  duration     Int         // milliseconds
+  duration     Int // milliseconds
   inputTokens  Int
   outputTokens Int
   cost         Float?
-  
-  createdAt    DateTime    @default(now())
 
-  chat         LlmChat     @relation(fields: [chatId], references: [id], onDelete: Cascade)
-  message      LlmMessage? @relation(fields: [messageId], references: [id], onDelete: Cascade)
+  createdAt DateTime @default(now())
+
+  chat    LlmChat     @relation(fields: [chatId], references: [id], onDelete: Cascade)
+  message LlmMessage? @relation(fields: [messageId], references: [id], onDelete: Cascade)
 
   @@index([chatId])
   @@index([createdAt])