@node-llm/orm 0.8.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/CHANGELOG.md +155 -0
  2. package/LICENSE +21 -0
  3. package/README.md +38 -14
  4. package/dist/BaseChat.d.ts +124 -0
  5. package/dist/BaseChat.d.ts.map +1 -0
  6. package/dist/BaseChat.js +182 -0
  7. package/dist/Store.d.ts +109 -0
  8. package/dist/Store.d.ts.map +1 -0
  9. package/dist/Store.js +14 -0
  10. package/dist/adapters/prisma/AgentSession.d.ts +178 -0
  11. package/dist/adapters/prisma/AgentSession.d.ts.map +1 -0
  12. package/dist/adapters/prisma/AgentSession.js +328 -0
  13. package/dist/adapters/prisma/Chat.d.ts +70 -0
  14. package/dist/adapters/prisma/Chat.d.ts.map +1 -0
  15. package/dist/adapters/prisma/Chat.js +301 -0
  16. package/dist/adapters/prisma/PrismaStore.d.ts +54 -0
  17. package/dist/adapters/prisma/PrismaStore.d.ts.map +1 -0
  18. package/dist/adapters/prisma/PrismaStore.js +97 -0
  19. package/dist/adapters/prisma/index.d.ts +51 -0
  20. package/dist/adapters/prisma/index.d.ts.map +1 -0
  21. package/dist/adapters/prisma/index.js +51 -0
  22. package/dist/index.d.ts +61 -0
  23. package/dist/index.d.ts.map +1 -0
  24. package/dist/index.js +61 -0
  25. package/migrations/README.md +5 -4
  26. package/migrations/add_cached_tokens.sql +5 -0
  27. package/package.json +14 -12
  28. package/schema.prisma +1 -0
  29. package/src/Store.ts +135 -0
  30. package/src/adapters/prisma/AgentSession.ts +89 -185
  31. package/src/adapters/prisma/Chat.ts +95 -162
  32. package/src/adapters/prisma/PrismaStore.ts +156 -0
  33. package/src/adapters/prisma/index.ts +3 -0
  34. package/src/index.ts +14 -0
  35. package/test/CachedTokens.test.ts +40 -0
  36. package/test/Store.test.ts +214 -0
  37. package/test/docs/readme-exports.test.ts +8 -0
  38. package/tsconfig.tsbuildinfo +1 -0
@@ -15,7 +15,8 @@ import {
15
15
  * We use 'any' here because PrismaClient has no index signature by default,
16
16
  * making it hard to access models dynamically by string name.
17
17
  */
18
- type GenericPrismaClient = any;
18
+ import type { ChatStore } from "../../Store.js";
19
+ import { toStore } from "./PrismaStore.js";
19
20
 
20
21
  /**
21
22
  * Record structure for the LLM Agent Session table.
@@ -62,17 +63,6 @@ export interface TableNames {
62
63
  /**
63
64
  * Internal interface for dynamic Prisma model access
64
65
  */
65
- interface PrismaModel<T = Record<string, unknown>> {
66
- create(args: { data: Record<string, unknown> }): Promise<T>;
67
- update(args: { where: { id: string }; data: Record<string, unknown> }): Promise<T>;
68
- delete(args: { where: { id: string } }): Promise<void>;
69
- findMany(args: {
70
- where: Record<string, unknown>;
71
- orderBy?: Record<string, string>;
72
- }): Promise<T[]>;
73
- findUnique(args: { where: { id: string } }): Promise<T | null>;
74
- }
75
-
76
66
  type AgentClass<T extends Agent<any, any> = Agent<any, any>> = (new (
77
67
  overrides?: Partial<AgentConfig<any> & ChatOptions>
78
68
  ) => T) & {
@@ -109,11 +99,11 @@ export class AgentSession<
109
99
  T extends Agent<I, any> = Agent<I, any>
110
100
  > {
111
101
  private currentMessageId: string | null = null;
112
- private tableNames: Required<TableNames>;
102
+ private store: ChatStore;
113
103
  private debug: boolean;
114
104
 
115
105
  constructor(
116
- private prisma: any,
106
+ prismaOrStore: unknown,
117
107
  private llm: NodeLLMCore,
118
108
  private AgentClass: AgentClass<T>,
119
109
  private record: AgentSessionRecord,
@@ -125,13 +115,7 @@ export class AgentSession<
125
115
  debug: boolean = false
126
116
  ) {
127
117
  this.debug = debug;
128
- this.tableNames = {
129
- agentSession: tableNames?.agentSession || "llmAgentSession",
130
- chat: tableNames?.chat || "llmChat",
131
- message: tableNames?.message || "llmMessage",
132
- toolCall: tableNames?.toolCall || "llmToolCall",
133
- request: tableNames?.request || "llmRequest"
134
- };
118
+ this.store = toStore(prismaOrStore, tableNames);
135
119
 
136
120
  this.registerHooks();
137
121
  }
@@ -185,10 +169,6 @@ export class AgentSession<
185
169
  /**
186
170
  * Helper to get a typed Prisma model by its dynamic name.
187
171
  */
188
- private getModel<R = Record<string, unknown>>(name: string): PrismaModel<R> {
189
- return getTable(this.prisma, name) as unknown as PrismaModel<R>;
190
- }
191
-
192
172
  /**
193
173
  * Register persistence hooks on the agent.
194
174
  */
@@ -196,32 +176,20 @@ export class AgentSession<
196
176
  this.agent.onToolCallStart(async (tc) => {
197
177
  const toolCall = tc as ToolCall;
198
178
  if (!this.currentMessageId) return;
199
- const model = this.getModel(this.tableNames.toolCall);
200
- await model.create({
201
- data: {
202
- messageId: this.currentMessageId,
203
- toolCallId: toolCall.id,
204
- name: toolCall.function.name,
205
- arguments: toolCall.function.arguments
206
- }
179
+ await this.store.createToolCall({
180
+ messageId: this.currentMessageId,
181
+ toolCallId: toolCall.id,
182
+ name: toolCall.function.name,
183
+ arguments: toolCall.function.arguments
207
184
  });
208
185
  });
209
186
 
210
187
  this.agent.onToolCallEnd(async (tc, result) => {
211
188
  const toolCall = tc as ToolCall;
212
189
  if (!this.currentMessageId) return;
213
- const model = this.getModel(this.tableNames.toolCall);
214
190
  try {
215
- await model.update({
216
- where: {
217
- messageId_toolCallId: {
218
- messageId: this.currentMessageId,
219
- toolCallId: toolCall.id
220
- }
221
- } as any,
222
- data: {
223
- result: typeof result === "string" ? result : JSON.stringify(result)
224
- }
191
+ await this.store.finishToolCall(this.currentMessageId, toolCall.id, {
192
+ result: typeof result === "string" ? result : JSON.stringify(result)
225
193
  });
226
194
  } catch (e) {
227
195
  this.log(`Failed to update tool call result: ${e}`);
@@ -229,19 +197,17 @@ export class AgentSession<
229
197
  });
230
198
 
231
199
  this.agent.afterResponse(async (response) => {
232
- const model = this.getModel(this.tableNames.request);
233
- await model.create({
234
- data: {
235
- chatId: this.chatId,
236
- messageId: this.currentMessageId,
237
- provider: response.provider || "unknown",
238
- model: response.model || "unknown",
239
- statusCode: 200,
240
- duration: 0,
241
- inputTokens: response.usage?.input_tokens || 0,
242
- outputTokens: response.usage?.output_tokens || 0,
243
- cost: response.usage?.cost || 0
244
- }
200
+ await this.store.createRequest({
201
+ chatId: this.chatId,
202
+ messageId: this.currentMessageId,
203
+ provider: response.provider || "unknown",
204
+ model: response.model || "unknown",
205
+ statusCode: 200,
206
+ duration: (response as { latency?: number }).latency || 0,
207
+ inputTokens: response.usage?.input_tokens || 0,
208
+ outputTokens: response.usage?.output_tokens || 0,
209
+ cachedTokens: response.usage?.cached_tokens,
210
+ cost: response.usage?.cost || 0
245
211
  });
246
212
  });
247
213
  }
@@ -250,16 +216,14 @@ export class AgentSession<
250
216
  * Send a message and persist the conversation.
251
217
  */
252
218
  async ask(message: string, options: AskOptions & { inputs?: I } = {}): Promise<MessageRecord> {
253
- const model = this.getModel<MessageRecord>(this.tableNames.message);
254
-
255
219
  // Persist user message
256
- await model.create({
257
- data: { chatId: this.chatId, role: "user", content: message }
258
- });
220
+ await this.store.createMessage({ chatId: this.chatId, role: "user", content: message });
259
221
 
260
222
  // Create placeholder for assistant message
261
- const assistantMessage = await model.create({
262
- data: { chatId: this.chatId, role: "assistant", content: null }
223
+ const assistantMessage = await this.store.createMessage({
224
+ chatId: this.chatId,
225
+ role: "assistant",
226
+ content: null
263
227
  });
264
228
 
265
229
  this.currentMessageId = assistantMessage.id;
@@ -272,23 +236,20 @@ export class AgentSession<
272
236
  const response = await this.agent.ask(message, { ...options, inputs });
273
237
 
274
238
  // Update assistant message with response
275
- return await model.update({
276
- where: { id: assistantMessage.id },
277
- data: {
278
- content: response.content,
279
- contentRaw: JSON.stringify(response.meta),
280
- inputTokens: response.usage?.input_tokens || 0,
281
- outputTokens: response.usage?.output_tokens || 0,
282
- thinkingText: response.thinking?.text || null,
283
- thinkingSignature: response.thinking?.signature || null,
284
- thinkingTokens: response.thinking?.tokens || null,
285
- modelId: response.model || null,
286
- provider: response.provider || null
287
- }
288
- });
239
+ return (await this.store.updateMessage(assistantMessage.id, {
240
+ content: response.content,
241
+ contentRaw: JSON.stringify(response.meta),
242
+ inputTokens: response.usage?.input_tokens || 0,
243
+ outputTokens: response.usage?.output_tokens || 0,
244
+ thinkingText: response.thinking?.text || null,
245
+ thinkingSignature: response.thinking?.signature || null,
246
+ thinkingTokens: response.thinking?.tokens || null,
247
+ modelId: response.model || null,
248
+ provider: response.provider || null
249
+ })) as MessageRecord;
289
250
  } catch (error) {
290
251
  // Clean up placeholder on error
291
- await model.delete({ where: { id: assistantMessage.id } });
252
+ await this.store.deleteMessage(assistantMessage.id);
292
253
  throw error;
293
254
  }
294
255
  }
@@ -300,16 +261,14 @@ export class AgentSession<
300
261
  message: string,
301
262
  options: AskOptions & { inputs?: I } = {}
302
263
  ): AsyncGenerator<ChatChunk, MessageRecord, undefined> {
303
- const model = this.getModel<MessageRecord>(this.tableNames.message);
304
-
305
264
  // Persist user message
306
- await model.create({
307
- data: { chatId: this.chatId, role: "user", content: message }
308
- });
265
+ await this.store.createMessage({ chatId: this.chatId, role: "user", content: message });
309
266
 
310
267
  // Create placeholder for assistant message
311
- const assistantMessage = await model.create({
312
- data: { chatId: this.chatId, role: "assistant", content: null }
268
+ const assistantMessage = await this.store.createMessage({
269
+ chatId: this.chatId,
270
+ role: "assistant",
271
+ content: null
313
272
  });
314
273
 
315
274
  this.currentMessageId = assistantMessage.id;
@@ -329,21 +288,18 @@ export class AgentSession<
329
288
  }
330
289
 
331
290
  // Final update with accumulated result
332
- return await model.update({
333
- where: { id: assistantMessage.id },
334
- data: {
335
- content: fullContent,
336
- inputTokens: lastChunk?.usage?.input_tokens || 0,
337
- outputTokens: lastChunk?.usage?.output_tokens || 0,
338
- thinkingText: lastChunk?.thinking?.text || null,
339
- thinkingSignature: lastChunk?.thinking?.signature || null,
340
- thinkingTokens: lastChunk?.thinking?.tokens || null,
341
- modelId: (lastChunk?.metadata?.model as string) || null,
342
- provider: (lastChunk?.metadata?.provider as string) || null
343
- }
344
- });
291
+ return (await this.store.updateMessage(assistantMessage.id, {
292
+ content: fullContent,
293
+ inputTokens: lastChunk?.usage?.input_tokens || 0,
294
+ outputTokens: lastChunk?.usage?.output_tokens || 0,
295
+ thinkingText: lastChunk?.thinking?.text || null,
296
+ thinkingSignature: lastChunk?.thinking?.signature || null,
297
+ thinkingTokens: lastChunk?.thinking?.tokens || null,
298
+ modelId: (lastChunk?.metadata?.model as string) || null,
299
+ provider: (lastChunk?.metadata?.provider as string) || null
300
+ })) as MessageRecord;
345
301
  } catch (error) {
346
- await model.delete({ where: { id: assistantMessage.id } });
302
+ await this.store.deleteMessage(assistantMessage.id);
347
303
  throw error;
348
304
  }
349
305
  }
@@ -352,21 +308,13 @@ export class AgentSession<
352
308
  * Returns a usage summary for this chat session.
353
309
  */
354
310
  async stats(): Promise<Usage> {
355
- const requestModel = getTable(this.prisma, this.tableNames.request);
356
- const aggregate = await (requestModel as any).aggregate({
357
- where: { chatId: this.chatId },
358
- _sum: {
359
- inputTokens: true,
360
- outputTokens: true,
361
- cost: true
362
- }
363
- });
311
+ const totals = await this.store.requestTotals(this.chatId);
364
312
 
365
313
  return {
366
- input_tokens: Number(aggregate._sum.inputTokens || 0),
367
- output_tokens: Number(aggregate._sum.outputTokens || 0),
368
- total_tokens: Number((aggregate._sum.inputTokens || 0) + (aggregate._sum.outputTokens || 0)),
369
- cost: Number(aggregate._sum.cost || 0)
314
+ input_tokens: totals.inputTokens,
315
+ output_tokens: totals.outputTokens,
316
+ total_tokens: totals.inputTokens + totals.outputTokens,
317
+ cost: totals.cost
370
318
  };
371
319
  }
372
320
 
@@ -390,19 +338,14 @@ export class AgentSession<
390
338
  * Returns the current full message history for this session.
391
339
  */
392
340
  async messages(): Promise<MessageRecord[]> {
393
- const model = this.getModel<MessageRecord>(this.tableNames.message);
394
- return await model.findMany({
395
- where: { chatId: this.chatId },
396
- orderBy: { createdAt: "asc" }
397
- });
341
+ return (await this.store.listMessages(this.chatId)) as MessageRecord[];
398
342
  }
399
343
 
400
344
  /**
401
345
  * Delete the entire session and its history.
402
346
  */
403
347
  async delete(): Promise<void> {
404
- const chatTable = this.getModel(this.tableNames.chat);
405
- await chatTable.delete({ where: { id: this.chatId } });
348
+ await this.store.deleteChat(this.chatId);
406
349
  // AgentSession record is deleted via Cascade from LlmChat
407
350
  }
408
351
 
@@ -410,13 +353,9 @@ export class AgentSession<
410
353
  * Update session metadata and re-resolve agent configuration.
411
354
  */
412
355
  async updateMetadata(metadata: Partial<I>): Promise<void> {
413
- const sessionTable = this.getModel<AgentSessionRecord>(this.tableNames.agentSession);
414
356
  const newMetadata = { ...(this.record.metadata as I), ...metadata };
415
357
 
416
- await sessionTable.update({
417
- where: { id: this.id },
418
- data: { metadata: newMetadata as any }
419
- });
358
+ await this.store.updateAgentSession(this.id, { metadata: newMetadata as any });
420
359
 
421
360
  this.record.metadata = newMetadata as any;
422
361
 
@@ -438,49 +377,41 @@ export interface CreateAgentSessionOptions<I = any> {
438
377
  provider?: string;
439
378
  instructions?: string;
440
379
  maxToolCalls?: number;
380
+ /** Tools for this session, in place of the ones the agent class defines */
381
+ tools?: ChatOptions["tools"];
441
382
  }
442
383
 
443
384
  /**
444
385
  * Creates a new agent session and its persistent chat record.
445
386
  */
446
387
  export async function createAgentSession<I extends Record<string, any>, T extends Agent<I, any>>(
447
- prisma: any,
388
+ prismaOrStore: unknown,
448
389
  llm: NodeLLMCore,
449
390
  AgentClass: AgentClass<T>,
450
391
  options: CreateAgentSessionOptions<I> = {}
451
392
  ): Promise<AgentSession<I, T>> {
452
- const tableNames = {
453
- agentSession: options.tableNames?.agentSession || "llmAgentSession",
454
- chat: options.tableNames?.chat || "llmChat",
455
- message: options.tableNames?.message || "llmMessage"
456
- };
393
+ const store = toStore(prismaOrStore, options.tableNames);
457
394
 
458
395
  if (options.debug) {
459
396
  console.log(`[@node-llm/orm] createAgentSession: agentClass=${AgentClass.name}`);
460
397
  }
461
398
 
462
399
  // 1. Create underlying LlmChat record
463
- const chatTable = getTable(prisma, tableNames.chat);
464
- const chatRecord = (await chatTable.create({
465
- data: {
466
- model: options.model || AgentClass.model || null,
467
- provider: options.provider || null,
468
- instructions:
469
- options.instructions ||
470
- (typeof AgentClass.instructions === "string" ? AgentClass.instructions : null),
471
- metadata: null // Runtime metadata goes in Chat, session context in AgentSession
472
- }
473
- })) as unknown as { id: string };
400
+ const chatRecord = await store.createChat({
401
+ model: options.model || AgentClass.model || null,
402
+ provider: options.provider || null,
403
+ instructions:
404
+ options.instructions ||
405
+ (typeof AgentClass.instructions === "string" ? AgentClass.instructions : null),
406
+ metadata: null // Runtime metadata goes in Chat, session context in AgentSession
407
+ });
474
408
 
475
409
  // 2. Create AgentSession record
476
- const sessionTable = getTable(prisma, tableNames.agentSession);
477
- const sessionRecord = (await sessionTable.create({
478
- data: {
479
- agentClass: AgentClass.name,
480
- chatId: chatRecord.id,
481
- metadata: (options.metadata as any) || null
482
- }
483
- })) as unknown as AgentSessionRecord;
410
+ const sessionRecord = (await store.createAgentSession({
411
+ agentClass: AgentClass.name,
412
+ chatId: chatRecord.id,
413
+ metadata: (options.metadata as any) || null
414
+ })) as AgentSessionRecord;
484
415
 
485
416
  // 3. Instantiate Agent with overrides
486
417
  const agent = new AgentClass({
@@ -489,11 +420,12 @@ export async function createAgentSession<I extends Record<string, any>, T extend
489
420
  model: options.model,
490
421
  provider: options.provider,
491
422
  instructions: options.instructions,
492
- maxToolCalls: options.maxToolCalls
423
+ maxToolCalls: options.maxToolCalls,
424
+ ...(options.tools ? { tools: options.tools } : {})
493
425
  });
494
426
 
495
427
  return new AgentSession<I, T>(
496
- prisma,
428
+ store,
497
429
  llm,
498
430
  AgentClass,
499
431
  sessionRecord,
@@ -515,27 +447,20 @@ export interface LoadAgentSessionOptions {
515
447
  * Loads an existing agent session and re-instantiates the agent with history.
516
448
  */
517
449
  export async function loadAgentSession<I extends Record<string, any>, T extends Agent<I, any>>(
518
- prisma: any,
450
+ prismaOrStore: unknown,
519
451
  llm: NodeLLMCore,
520
452
  AgentClass: AgentClass<T>,
521
453
  sessionId: string,
522
454
  options: LoadAgentSessionOptions = {}
523
455
  ): Promise<AgentSession<I, T> | null> {
524
- const tableNames = {
525
- agentSession: options.tableNames?.agentSession || "llmAgentSession",
526
- chat: options.tableNames?.chat || "llmChat",
527
- message: options.tableNames?.message || "llmMessage"
528
- };
456
+ const store = toStore(prismaOrStore, options.tableNames);
529
457
 
530
458
  if (options.debug) {
531
459
  console.log(`[@node-llm/orm] loadAgentSession: id=${sessionId}`);
532
460
  }
533
461
 
534
462
  // 1. Find session record
535
- const sessionTable = getTable(prisma, tableNames.agentSession);
536
- const sessionRecord = (await sessionTable.findUnique({
537
- where: { id: sessionId }
538
- })) as unknown as AgentSessionRecord | null;
463
+ const sessionRecord = (await store.findAgentSession(sessionId)) as AgentSessionRecord | null;
539
464
 
540
465
  if (!sessionRecord) {
541
466
  return null;
@@ -549,11 +474,7 @@ export async function loadAgentSession<I extends Record<string, any>, T extends
549
474
  }
550
475
 
551
476
  // 2. Load message history
552
- const messageTable = getTable(prisma, tableNames.message);
553
- const messages = (await messageTable.findMany({
554
- where: { chatId: sessionRecord.chatId },
555
- orderBy: { createdAt: "asc" }
556
- })) as unknown as MessageRecord[];
477
+ const messages = (await store.listMessages(sessionRecord.chatId)) as MessageRecord[];
557
478
 
558
479
  // 3. Convert DB messages to NodeLLM Message format
559
480
  const history: Message[] = messages.map((m) => ({
@@ -571,7 +492,7 @@ export async function loadAgentSession<I extends Record<string, any>, T extends
571
492
  }) as T;
572
493
 
573
494
  return new AgentSession<I, T>(
574
- prisma,
495
+ store,
575
496
  llm,
576
497
  AgentClass,
577
498
  sessionRecord,
@@ -585,20 +506,3 @@ export async function loadAgentSession<I extends Record<string, any>, T extends
585
506
  * Dynamic helper to access Prisma models by name.
586
507
  * Handles both case-sensitive and case-insensitive lookups for flexibility.
587
508
  */
588
- function getTable(prisma: GenericPrismaClient, tableName: string): PrismaModel {
589
- const p = prisma as unknown as Record<string, PrismaModel>;
590
-
591
- // 1. Direct match
592
- const table = p[tableName];
593
- if (table) return table;
594
-
595
- // 2. Case-insensitive match
596
- const keys = Object.keys(prisma).filter((k) => !k.startsWith("$") && !k.startsWith("_"));
597
- const match = keys.find((k) => k.toLowerCase() === tableName.toLowerCase());
598
-
599
- if (match && p[match]) return p[match];
600
-
601
- throw new Error(
602
- `[@node-llm/orm] Prisma table "${tableName}" not found. Available tables: ${keys.join(", ")}`
603
- );
604
- }