@node-llm/orm 0.1.0

package/schema.prisma

@@ -0,0 +1,84 @@
+// This is the reference Prisma schema for @node-llm/orm
+// Users should copy this into their own prisma/schema.prisma
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+// NodeLLM ORM Models (matches @node-llm/orm schema)
+model LlmChat {
+  id           String       @id @default(uuid())
+  model        String?
+  provider     String?
+  instructions String?      // System instructions
+  metadata     Json?         // JSON metadata
+  createdAt    DateTime      @default(now())
+  updatedAt    DateTime     @updatedAt
+  messages     LlmMessage[]
+  requests     LlmRequest[]
+}
+
+model LlmMessage {
+  id           String        @id @default(uuid())
+  chatId       String
+  role         String        // user, assistant, system, tool
+  content      String?
+  contentRaw   String?       // JSON raw payload
+  reasoning    String?       // Chain of thought
+  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     // ID from the provider
+  name         String
+  arguments    String     // JSON string
+  thought      String?    // The LLM's reasoning for this tool call
+  result       String?    // Tool execution result
+  createdAt    DateTime   @default(now())
+
+  message      LlmMessage @relation(fields: [messageId], references: [id], onDelete: Cascade)
+
+  @@unique([messageId, toolCallId])
+  @@index([messageId])
+  @@index([createdAt])
+}
+
+model LlmRequest {
+  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
+  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)
+
+  @@index([chatId])
+  @@index([createdAt])
+}

package/src/BaseChat.ts

@@ -0,0 +1,168 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+export interface ChatRecord {
+  id: string;
+  model?: string | null;
+  provider?: string | null;
+  instructions?: string | null;
+  metadata?: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface ChatOptions {
+  model?: string;
+  provider?: string;
+  instructions?: string;
+  metadata?: Record<string, any>;
+  debug?: boolean;
+  persistence?: {
+    toolCalls?: boolean; // Default: true
+    requests?: boolean; // Default: true
+  };
+}
+
+export interface UserHooks {
+  onToolCallStart: ((call: any) => void | Promise<void>)[];
+  onToolCallEnd: ((call: any, result: any) => void | Promise<void>)[];
+  afterResponse: ((resp: any) => any | Promise<any>)[];
+  onNewMessage: (() => void | Promise<void>)[];
+  onEndMessage: ((message: any) => void | Promise<void>)[];
+  onToolCallError: ((call: any, error: Error) => any | Promise<any>)[];
+  onConfirmToolCall: ((call: any) => boolean | Promise<boolean>)[];
+  onBeforeRequest: ((messages: any[]) => any | Promise<any>)[];
+}
+
+/**
+ * BaseChat - A generic base class for ORM chat implementations.
+ */
+export abstract class BaseChat<
+  R extends ChatRecord = ChatRecord,
+  O extends ChatOptions = ChatOptions
+> {
+  public id: string;
+  protected localOptions: any = {};
+  protected customTools: any[] = [];
+  protected userHooks: UserHooks = {
+    onToolCallStart: [],
+    onToolCallEnd: [],
+    afterResponse: [],
+    onNewMessage: [],
+    onEndMessage: [],
+    onToolCallError: [],
+    onConfirmToolCall: [],
+    onBeforeRequest: []
+  };
+
+  constructor(
+    public record: R,
+    public options: O = {} as O
+  ) {
+    this.id = record.id;
+
+    // Initialize local options from record/options
+    this.localOptions.instructions = options.instructions || record.instructions;
+    this.localOptions.model = options.model || record.model;
+    this.localOptions.provider = options.provider || record.provider;
+  }
+
+  protected log(...args: any[]) {
+    if (this.options?.debug) {
+      console.log(`[@node-llm/orm]`, ...args);
+    }
+  }
+
+  // --- Fluent Configuration Methods ---
+
+  withInstructions(instruction: string, options?: { replace?: boolean }): this {
+    if (options?.replace) {
+      this.localOptions.instructions = instruction;
+    } else {
+      this.localOptions.instructions = (this.localOptions.instructions || "") + "\n" + instruction;
+    }
+    return this;
+  }
+
+  system(instruction: string, options?: { replace?: boolean }): this {
+    return this.withInstructions(instruction, options);
+  }
+
+  withTemperature(temp: number): this {
+    this.localOptions.temperature = temp;
+    return this;
+  }
+
+  withModel(model: string): this {
+    this.localOptions.model = model;
+    return this;
+  }
+
+  withProvider(provider: string): this {
+    this.localOptions.provider = provider;
+    return this;
+  }
+
+  withTools(tools: any[]): this {
+    this.customTools.push(...tools);
+    return this;
+  }
+
+  withTool(tool: any): this {
+    this.customTools.push(tool);
+    return this;
+  }
+
+  use(tool: any): this {
+    return this.withTool(tool);
+  }
+
+  withSchema(schema: any): this {
+    this.localOptions.schema = schema;
+    return this;
+  }
+
+  withParams(params: Record<string, any>): this {
+    this.localOptions.params = { ...(this.localOptions.params || {}), ...params };
+    return this;
+  }
+
+  // --- Hook Registration ---
+
+  onToolCallStart(callback: (call: any) => void | Promise<void>): this {
+    this.userHooks.onToolCallStart.push(callback);
+    return this;
+  }
+
+  onToolCall(callback: (call: any) => void | Promise<void>): this {
+    return this.onToolCallStart(callback);
+  }
+
+  onToolCallEnd(callback: (call: any, result: any) => void | Promise<void>): this {
+    this.userHooks.onToolCallEnd.push(callback);
+    return this;
+  }
+
+  onToolResult(callback: (result: any) => void | Promise<void>): this {
+    return this.onToolCallEnd((_call, result) => callback(result));
+  }
+
+  afterResponse(callback: (resp: any) => any | Promise<any>): this {
+    this.userHooks.afterResponse.push(callback);
+    return this;
+  }
+
+  onBeforeRequest(callback: (messages: any[]) => any | Promise<any>): this {
+    this.userHooks.onBeforeRequest.push(callback);
+    return this;
+  }
+
+  onNewMessage(callback: () => void | Promise<void>): this {
+    this.userHooks.onNewMessage.push(callback);
+    return this;
+  }
+
+  onEndMessage(callback: (message: any) => void | Promise<void>): this {
+    this.userHooks.onEndMessage.push(callback);
+    return this;
+  }
+}

package/src/adapters/prisma/Chat.ts

@@ -0,0 +1,333 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { PrismaClient } from "@prisma/client";
+import type { NodeLLMCore } from "@node-llm/core";
+import { BaseChat, type ChatRecord, type ChatOptions } from "../../BaseChat.js";
+
+export { type ChatRecord, type ChatOptions };
+
+export interface MessageRecord {
+  id: string;
+  chatId: string;
+  role: string;
+  content: string | null;
+  contentRaw: string | null;
+  reasoning: string | null;
+  inputTokens: number | null;
+  outputTokens: number | null;
+  modelId: string | null;
+  provider: string | null;
+  createdAt: Date;
+}
+
+export interface TableNames {
+  chat?: string;
+  message?: string;
+  toolCall?: string;
+  request?: string;
+}
+
+/**
+ * Prisma-based Chat Implementation.
+ */
+export class Chat extends BaseChat {
+  private tables: Required<TableNames>;
+  private persistenceConfig: Required<NonNullable<ChatOptions["persistence"]>>;
+
+  constructor(
+    private prisma: PrismaClient,
+    private llm: NodeLLMCore,
+    record: ChatRecord,
+    options: ChatOptions = {},
+    tableNames: TableNames = {}
+  ) {
+    super(record, options);
+    this.tables = {
+      chat: tableNames.chat || "chat",
+      message: tableNames.message || "message",
+      toolCall: tableNames.toolCall || "toolCall",
+      request: tableNames.request || "assistantRequest"
+    };
+
+    this.persistenceConfig = {
+      toolCalls: options.persistence?.toolCalls ?? true,
+      requests: options.persistence?.requests ?? true
+    };
+  }
+
+  /**
+   * Internal prep for core Chat instance with persistence hooks.
+   */
+  private async prepareCoreChat(history: any[] = [], assistantMessageId: string) {
+    const provider = this.localOptions.provider || this.record.provider;
+    const model = this.localOptions.model || this.record.model;
+
+    const llmInstance = provider ? this.llm.withProvider(provider as string) : this.llm;
+
+    const coreChat = llmInstance.chat(model || undefined, {
+      messages: history,
+      ...this.localOptions
+    }) as any;
+
+    // Register tools
+    if (this.customTools.length > 0) {
+      coreChat.withTools(this.customTools);
+    }
+
+    // --- Persistence Hooks ---
+
+    coreChat.onToolCallStart(async (call: any) => {
+      // Only persist if toolCalls persistence is enabled
+      if (this.persistenceConfig.toolCalls) {
+        const toolCallModel = this.tables.toolCall;
+        await (this.prisma as any)[toolCallModel].create({
+          data: {
+            messageId: assistantMessageId,
+            toolCallId: call.id,
+            name: call.function?.name || "unknown",
+            arguments: JSON.stringify(call.function?.arguments || {}),
+            thought: (call as any).thought || null
+          }
+        });
+      }
+
+      // User hooks
+      for (const h of this.userHooks.onToolCallStart) await h(call);
+    });
+
+    coreChat.onToolCallEnd(async (call: any, result: any) => {
+      // Only persist if toolCalls persistence is enabled
+      if (this.persistenceConfig.toolCalls) {
+        const toolCallModel = this.tables.toolCall;
+        const resString = typeof result === "string" ? result : JSON.stringify(result);
+
+        await (this.prisma as any)[toolCallModel].update({
+          where: { messageId_toolCallId: { messageId: assistantMessageId, toolCallId: call.id } },
+          data: {
+            result: resString,
+            thought: (call as any).thought || null
+          }
+        });
+      }
+
+      // User hooks
+      for (const h of this.userHooks.onToolCallEnd) await h(call, result);
+    });
+
+    coreChat.afterResponse(async (finalResp: any) => {
+      this.log(
+        `Internal afterResponse triggered. Calling ${this.userHooks.afterResponse.length} user hooks.`
+      );
+
+      // User hooks
+      for (const h of this.userHooks.afterResponse) {
+        const modified = await h(finalResp);
+        if (modified) finalResp = modified;
+      }
+
+      // Only persist if requests persistence is enabled
+      if (this.persistenceConfig.requests) {
+        const modelName = this.tables.request;
+        await (this.prisma as any)[modelName].create({
+          data: {
+            chatId: this.id,
+            messageId: assistantMessageId,
+            provider: finalResp.provider || provider || "unknown",
+            model: finalResp.model || model || "unknown",
+            statusCode: 200,
+            duration: finalResp.latency || 0,
+            inputTokens: finalResp.usage?.input_tokens || 0,
+            outputTokens: finalResp.usage?.output_tokens || 0,
+            cost: finalResp.usage?.cost || 0
+          }
+        });
+      }
+
+      return finalResp;
+    });
+
+    // Other core hooks
+    if (this.userHooks.onNewMessage.length > 0) {
+      coreChat.onNewMessage(async () => {
+        for (const h of this.userHooks.onNewMessage) await h();
+      });
+    }
+
+    if (this.userHooks.onEndMessage.length > 0) {
+      coreChat.onEndMessage(async (msg: any) => {
+        for (const h of this.userHooks.onEndMessage) await h(msg);
+      });
+    }
+
+    if (this.userHooks.onBeforeRequest.length > 0) {
+      coreChat.beforeRequest(async (msgs: any) => {
+        let current = msgs;
+        for (const h of this.userHooks.onBeforeRequest) {
+          const mod = await h(current);
+          if (mod) current = mod;
+        }
+        return current;
+      });
+    }
+
+    return coreChat;
+  }
+
+  /**
+   * Send a message and persist the conversation.
+   */
+  async ask(input: string): Promise<MessageRecord> {
+    const messageModel = this.tables.message;
+    const userMessage = await (this.prisma as any)[messageModel].create({
+      data: { chatId: this.id, role: "user", content: input }
+    });
+
+    const assistantMessage = await (this.prisma as any)[messageModel].create({
+      data: { chatId: this.id, role: "assistant", content: null }
+    });
+
+    try {
+      const historyRecords = await (this.prisma as any)[messageModel].findMany({
+        where: { chatId: this.id, id: { notIn: [userMessage!.id, assistantMessage!.id] } },
+        orderBy: { createdAt: "asc" }
+      });
+
+      const history = historyRecords.map((m: any) => ({
+        role: m.role,
+        content: m.content || ""
+      }));
+
+      const coreChat = await this.prepareCoreChat(history, assistantMessage!.id);
+      const response = await coreChat.ask(input);
+
+      return await (this.prisma as any)[messageModel].update({
+        where: { id: assistantMessage!.id },
+        data: {
+          content: response.content,
+          contentRaw: JSON.stringify(response.meta),
+          inputTokens: response.usage?.input_tokens || 0,
+          outputTokens: response.usage?.output_tokens || 0,
+          modelId: response.model || null,
+          provider: response.provider || null
+        }
+      });
+    } catch (error) {
+      await (this.prisma as any)[messageModel].delete({ where: { id: assistantMessage!.id } });
+      // await (this.prisma as any)[messageModel].delete({ where: { id: userMessage!.id } });
+      throw error;
+    }
+  }
+
+  /**
+   * Stream a response and persist the conversation.
+   */
+  async *askStream(input: string): AsyncGenerator<string, MessageRecord, undefined> {
+    const messageModel = this.tables.message;
+    const userMessage = await (this.prisma as any)[messageModel].create({
+      data: { chatId: this.id, role: "user", content: input }
+    });
+
+    const assistantMessage = await (this.prisma as any)[messageModel].create({
+      data: { chatId: this.id, role: "assistant", content: null }
+    });
+
+    try {
+      const historyRecords = await (this.prisma as any)[messageModel].findMany({
+        where: { chatId: this.id, id: { notIn: [userMessage!.id, assistantMessage!.id] } },
+        orderBy: { createdAt: "asc" }
+      });
+
+      const history = historyRecords.map((m: any) => ({
+        role: m.role,
+        content: m.content || ""
+      }));
+
+      const coreChat = await this.prepareCoreChat(history, assistantMessage!.id);
+      const stream = coreChat.stream(input);
+
+      let fullContent = "";
+      let metadata: any = {};
+
+      for await (const chunk of stream) {
+        if (chunk.content) {
+          fullContent += chunk.content;
+          yield chunk.content;
+        }
+        if (chunk.usage) {
+          metadata = { ...metadata, ...chunk.usage };
+        }
+      }
+
+      return await (this.prisma as any)[messageModel].update({
+        where: { id: assistantMessage!.id },
+        data: {
+          content: fullContent,
+          contentRaw: JSON.stringify(metadata),
+          inputTokens: metadata.input_tokens || 0,
+          outputTokens: metadata.output_tokens || 0,
+          modelId: coreChat.model || null,
+          provider: coreChat.provider?.id || null
+        }
+      });
+    } catch (error) {
+      await (this.prisma as any)[messageModel].delete({ where: { id: assistantMessage!.id } });
+      // await (this.prisma as any)[messageModel].delete({ where: { id: userMessage!.id } });
+      throw error;
+    }
+  }
+
+  /**
+   * Get all messages for this chat.
+   */
+  async messages(): Promise<MessageRecord[]> {
+    const messageModel = this.tables.message;
+    return await (this.prisma as any)[messageModel].findMany({
+      where: { chatId: this.id },
+      orderBy: { createdAt: "asc" }
+    });
+  }
+}
+
+/**
+ * Convenience method to create a new chat session.
+ */
+export async function createChat<T = Record<string, any>>(
+  prisma: PrismaClient,
+  llm: NodeLLMCore,
+  options: ChatOptions & { tableNames?: TableNames } & T = {} as any
+): Promise<Chat> {
+  const chatTable = options.tableNames?.chat || "chat";
+
+  // Extract known options so we don't double-pass them or pass them incorrectly
+  const { model, provider, instructions, metadata, tableNames, debug, persistence, ...extras } =
+    options;
+
+  const record = await (prisma as any)[chatTable].create({
+    data: {
+      model,
+      provider,
+      instructions,
+      metadata: metadata ?? null,
+      ...extras
+    }
+  });
+
+  return new Chat(prisma, llm, record, options, options.tableNames);
+}
+
+/**
+ * Convenience method to load an existing chat session.
+ */
+export async function loadChat(
+  prisma: PrismaClient,
+  llm: NodeLLMCore,
+  chatId: string,
+  options: ChatOptions & { tableNames?: TableNames } = {}
+): Promise<Chat | null> {
+  const chatTable = options.tableNames?.chat || "chat";
+  const record = await (prisma as any)[chatTable].findUnique({
+    where: { id: chatId }
+  });
+
+  if (!record) return null;
+  return new Chat(prisma, llm, record, options, options.tableNames);
+}

package/src/adapters/prisma/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @node-llm/orm/prisma
+ *
+ * Prisma adapter for NodeLLM ORM.
+ * Provides automatic persistence of chats, messages, tool calls, and API requests.
+ *
+ * @example
+ * ```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' });
+ *
+ * const chat = await createChat(prisma, llm, {
+ *   model: 'gpt-4',
+ *   instructions: 'You are a helpful assistant.'
+ * });
+ *
+ * const response = await chat.ask('Hello!');
+ * console.log(response.content);
+ * ```
+ */
+
+export { Chat, createChat, loadChat } from "./Chat.js";
+export type { ChatRecord, MessageRecord, ChatOptions, TableNames } from "./Chat.js";

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * @node-llm/orm
+ *
+ * Database persistence layer for NodeLLM.
+ * Automatically tracks chats, messages, tool calls, and API requests.
+ *
+ * ## Quick Start
+ *
+ * 1. Copy `schema.prisma` from this package into your project
+ * 2. Run `npx prisma migrate dev`
+ * 3. Use the ORM:
+ *
+ * ```typescript
+ * import { createChat } from '@node-llm/orm/prisma';
+ * import { prisma } from './db.js';
+ * import { llm } from './llm.js';
+ *
+ * const chat = await createChat(prisma, llm, {
+ *   model: 'gpt-4',
+ *   instructions: 'You are a helpful assistant.'
+ * });
+ *
+ * await chat.ask('Hello!');
+ * ```
+ *
+ * ## Adapters
+ *
+ * - `@node-llm/orm/prisma` - Prisma adapter (recommended)
+ *
+ * ## Schema
+ *
+ * The ORM tracks four core entities:
+ * - **Chat** - Session container (model, provider, instructions)
+ * - **Message** - User/Assistant conversation history
+ * - **ToolCall** - Tool executions (name, arguments, results)
+ * - **Request** - API call metrics (tokens, latency, cost)
+ */
+
+// Re-export Prisma adapter as default
+export * from "./adapters/prisma/index.js";