@node-llm/orm 0.7.1 → 0.9.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 (39) hide show
  1. package/CHANGELOG.md +186 -0
  2. package/README.md +38 -14
  3. package/dist/BaseChat.d.ts +39 -1
  4. package/dist/BaseChat.d.ts.map +1 -1
  5. package/dist/BaseChat.js +56 -0
  6. package/dist/Store.d.ts +107 -0
  7. package/dist/Store.d.ts.map +1 -0
  8. package/dist/Store.js +14 -0
  9. package/dist/adapters/prisma/AgentSession.d.ts +13 -6
  10. package/dist/adapters/prisma/AgentSession.d.ts.map +1 -1
  11. package/dist/adapters/prisma/AgentSession.js +83 -166
  12. package/dist/adapters/prisma/Chat.d.ts +8 -9
  13. package/dist/adapters/prisma/Chat.d.ts.map +1 -1
  14. package/dist/adapters/prisma/Chat.js +128 -155
  15. package/dist/adapters/prisma/PrismaStore.d.ts +54 -0
  16. package/dist/adapters/prisma/PrismaStore.d.ts.map +1 -0
  17. package/dist/adapters/prisma/PrismaStore.js +93 -0
  18. package/dist/adapters/prisma/index.d.ts +1 -0
  19. package/dist/adapters/prisma/index.d.ts.map +1 -1
  20. package/dist/adapters/prisma/index.js +2 -0
  21. package/dist/index.d.ts +2 -0
  22. package/dist/index.d.ts.map +1 -1
  23. package/dist/index.js +2 -0
  24. package/package.json +8 -3
  25. package/schema.prisma +8 -7
  26. package/src/BaseChat.ts +70 -1
  27. package/src/Store.ts +133 -0
  28. package/src/adapters/prisma/AgentSession.ts +88 -185
  29. package/src/adapters/prisma/Chat.ts +130 -163
  30. package/src/adapters/prisma/PrismaStore.ts +152 -0
  31. package/src/adapters/prisma/index.ts +3 -0
  32. package/src/index.ts +14 -0
  33. package/test/AgentSession.test.ts +12 -4
  34. package/test/Store.test.ts +214 -0
  35. package/test/ToolChoiceAndSchema.test.ts +180 -0
  36. package/test/ToolExecutionOptions.test.ts +205 -0
  37. package/test/docs/readme-exports.test.ts +8 -0
  38. package/tsconfig.json +1 -1
  39. package/tsconfig.tsbuildinfo +1 -1
package/src/BaseChat.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /* eslint-disable @typescript-eslint/no-explicit-any */
2
- import type { Usage, Middleware } from "@node-llm/core";
2
+ import type { Usage, Middleware, ToolExecutionMode, ToolChoice } from "@node-llm/core";
3
3
 
4
4
  export interface ChatRecord {
5
5
  id: string;
@@ -29,6 +29,11 @@ export interface ChatOptions {
29
29
  maxTokens?: number;
30
30
  headers?: Record<string, string>;
31
31
  maxToolCalls?: number;
32
+ toolConcurrency?: boolean;
33
+ toolExecution?: ToolExecutionMode;
34
+ toolChoice?: ToolChoice;
35
+ toolCalls?: "one" | "many" | number;
36
+ schema?: any;
32
37
  requestTimeout?: number;
33
38
  params?: Record<string, any>;
34
39
  middlewares?: Middleware[];
@@ -37,6 +42,8 @@ export interface ChatOptions {
37
42
  export interface UserHooks {
38
43
  onToolCallStart: ((call: any) => void | Promise<void>)[];
39
44
  onToolCallEnd: ((call: any, result: any) => void | Promise<void>)[];
45
+ onToolCallError: ((call: any, error: Error) => any | Promise<any>)[];
46
+ onConfirmToolCall: ((call: any) => boolean | Promise<boolean>)[];
40
47
  afterResponse: ((resp: any) => any | Promise<any>)[];
41
48
  onNewMessage: (() => void | Promise<void>)[];
42
49
  onEndMessage: ((message: any) => void | Promise<void>)[];
@@ -57,6 +64,8 @@ export abstract class BaseChat<
57
64
  protected userHooks: UserHooks = {
58
65
  onToolCallStart: [],
59
66
  onToolCallEnd: [],
67
+ onToolCallError: [],
68
+ onConfirmToolCall: [],
60
69
  afterResponse: [],
61
70
  onNewMessage: [],
62
71
  onEndMessage: [],
@@ -78,6 +87,11 @@ export abstract class BaseChat<
78
87
  this.localOptions.maxTokens = options.maxTokens;
79
88
  this.localOptions.headers = options.headers;
80
89
  this.localOptions.maxToolCalls = options.maxToolCalls;
90
+ this.localOptions.toolConcurrency = options.toolConcurrency;
91
+ this.localOptions.toolExecution = options.toolExecution;
92
+ this.localOptions.toolChoice = options.toolChoice;
93
+ this.localOptions.toolCalls = options.toolCalls;
94
+ this.localOptions.schema = options.schema;
81
95
  this.localOptions.requestTimeout = options.requestTimeout;
82
96
  this.localOptions.params = options.params;
83
97
 
@@ -156,6 +170,41 @@ export abstract class BaseChat<
156
170
  return this.withThinking({ effort });
157
171
  }
158
172
 
173
+ /**
174
+ * Runs independent tool calls within the same turn concurrently instead
175
+ * of sequentially. See core's Tools guide for details.
176
+ */
177
+ withToolConcurrency(enabled: boolean): this {
178
+ this.localOptions.toolConcurrency = enabled;
179
+ return this;
180
+ }
181
+
182
+ /**
183
+ * Controls how tool calls are executed: "auto" (default), "confirm"
184
+ * (calls onConfirmToolCall before each execution), or "dry-run".
185
+ */
186
+ withToolExecution(mode: ToolExecutionMode): this {
187
+ this.localOptions.toolExecution = mode;
188
+ return this;
189
+ }
190
+
191
+ /**
192
+ * Forces, forbids, or requires a specific tool for the next request.
193
+ */
194
+ withToolChoice(choice: ToolChoice): this {
195
+ this.localOptions.toolChoice = choice;
196
+ return this;
197
+ }
198
+
199
+ /**
200
+ * Restricts how many tool calls the model may return in a single turn:
201
+ * "one" (sequential), "many" (default), or an exact number.
202
+ */
203
+ withToolCalls(calls: "one" | "many" | number): this {
204
+ this.localOptions.toolCalls = calls;
205
+ return this;
206
+ }
207
+
159
208
  // --- Hook Registration ---
160
209
 
161
210
  onToolCallStart(callback: (call: any) => void | Promise<void>): this {
@@ -176,6 +225,26 @@ export abstract class BaseChat<
176
225
  return this.onToolCallEnd((_call, result) => callback(result));
177
226
  }
178
227
 
228
+ /**
229
+ * Registers a handler run when a tool call throws. Return "STOP",
230
+ * "CONTINUE", or "RETRY" to control recovery; the first handler to return
231
+ * a directive wins, but every registered handler still runs.
232
+ */
233
+ onToolCallError(callback: (call: any, error: Error) => any | Promise<any>): this {
234
+ this.userHooks.onToolCallError.push(callback);
235
+ return this;
236
+ }
237
+
238
+ /**
239
+ * Registers an approval handler used when toolExecution is "confirm".
240
+ * Every registered handler must approve (return true) for the call to
241
+ * proceed.
242
+ */
243
+ onConfirmToolCall(callback: (call: any) => boolean | Promise<boolean>): this {
244
+ this.userHooks.onConfirmToolCall.push(callback);
245
+ return this;
246
+ }
247
+
179
248
  afterResponse(callback: (resp: any) => any | Promise<any>): this {
180
249
  this.userHooks.afterResponse.push(callback);
181
250
  return this;
package/src/Store.ts ADDED
@@ -0,0 +1,133 @@
1
+ /* eslint-disable @typescript-eslint/no-explicit-any */
2
+
3
+ /**
4
+ * Where an ORM chat or agent session keeps its records. The Prisma store is the default; an app
5
+ * can pass its own to keep the same records anywhere else, such as behind its own HTTP API.
6
+ */
7
+
8
+ export interface StoredChat {
9
+ id: string;
10
+ model?: string | null;
11
+ provider?: string | null;
12
+ instructions?: string | null;
13
+ metadata?: any;
14
+ createdAt: Date;
15
+ updatedAt: Date;
16
+ }
17
+
18
+ export interface StoredMessage {
19
+ id: string;
20
+ chatId: string;
21
+ role: string;
22
+ content: string | null;
23
+ contentRaw?: string | null;
24
+ reasoning?: string | null;
25
+ inputTokens?: number | null;
26
+ outputTokens?: number | null;
27
+ thinkingText?: string | null;
28
+ thinkingSignature?: string | null;
29
+ thinkingTokens?: number | null;
30
+ modelId?: string | null;
31
+ provider?: string | null;
32
+ createdAt: Date;
33
+ }
34
+
35
+ export interface StoredAgentSession {
36
+ id: string;
37
+ agentClass: string;
38
+ chatId: string;
39
+ metadata?: Record<string, unknown> | null;
40
+ createdAt: Date;
41
+ updatedAt: Date;
42
+ }
43
+
44
+ export interface NewChat {
45
+ model?: string | null;
46
+ provider?: string | null;
47
+ instructions?: string | null;
48
+ metadata?: any;
49
+ /** Extra columns an app adds to its chat table, such as a user id */
50
+ [column: string]: unknown;
51
+ }
52
+
53
+ export type MessageUpdate = Partial<Omit<StoredMessage, "id" | "chatId" | "role" | "createdAt">>;
54
+
55
+ export interface NewToolCall {
56
+ messageId: string;
57
+ toolCallId: string;
58
+ name: string;
59
+ arguments: string;
60
+ thought?: string | null;
61
+ thoughtSignature?: string | null;
62
+ }
63
+
64
+ export interface NewRequest {
65
+ chatId: string;
66
+ messageId: string | null;
67
+ provider: string;
68
+ model: string;
69
+ statusCode: number;
70
+ /** Milliseconds */
71
+ duration: number;
72
+ inputTokens: number;
73
+ outputTokens: number;
74
+ cost: number;
75
+ }
76
+
77
+ export interface RequestTotals {
78
+ inputTokens: number;
79
+ outputTokens: number;
80
+ cost: number;
81
+ }
82
+
83
+ export interface ChatStore {
84
+ createChat(chat: NewChat): Promise<StoredChat>;
85
+ findChat(id: string): Promise<StoredChat | null>;
86
+ /** Removes the chat with everything recorded under it */
87
+ deleteChat(id: string): Promise<void>;
88
+
89
+ createMessage(message: {
90
+ chatId: string;
91
+ role: string;
92
+ content: string | null;
93
+ }): Promise<StoredMessage>;
94
+ updateMessage(id: string, changes: MessageUpdate): Promise<StoredMessage>;
95
+ deleteMessage(id: string): Promise<void>;
96
+ /** A chat's messages, oldest first, leaving out any listed in excludeIds */
97
+ listMessages(chatId: string, options?: { excludeIds?: string[] }): Promise<StoredMessage[]>;
98
+
99
+ createToolCall(toolCall: NewToolCall): Promise<void>;
100
+ finishToolCall(
101
+ messageId: string,
102
+ toolCallId: string,
103
+ finished: { result: string; thought?: string | null }
104
+ ): Promise<void>;
105
+
106
+ createRequest(request: NewRequest): Promise<void>;
107
+ requestTotals(chatId: string): Promise<RequestTotals>;
108
+
109
+ createAgentSession(session: {
110
+ agentClass: string;
111
+ chatId: string;
112
+ metadata: Record<string, unknown> | null;
113
+ }): Promise<StoredAgentSession>;
114
+ findAgentSession(id: string): Promise<StoredAgentSession | null>;
115
+ updateAgentSession(id: string, changes: { metadata: Record<string, unknown> }): Promise<void>;
116
+ }
117
+
118
+ const storeMethods: (keyof ChatStore)[] = [
119
+ "createChat",
120
+ "createMessage",
121
+ "updateMessage",
122
+ "listMessages",
123
+ "createRequest"
124
+ ];
125
+
126
+ /** Whether a value is a ChatStore rather than a Prisma client. */
127
+ export function isChatStore(value: unknown): value is ChatStore {
128
+ return (
129
+ typeof value === "object" &&
130
+ value !== null &&
131
+ storeMethods.every((method) => typeof (value as any)[method] === "function")
132
+ );
133
+ }