@node-llm/orm 0.7.1 → 0.8.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.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,42 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [1.16.0] - 2026-04-18 (@node-llm/core)
6
+
7
+ ### Features
8
+
9
+ - **Advanced Tool Control**: Precise orchestration of model tool behavior via `choice` and `calls` parameters.
10
+ - `choice`: Mandatory tool usage (`required`), specific tool forcing (`"tool_name"`), or disabling (`none`).
11
+ - `calls`: Control over parallel vs. sequential tool execution (`one` vs. `many`).
12
+ - **Robust Tool Error Recovery**: Intelligent handling of tool calling failures to enable model self-correction.
13
+ - Intercepts hallucinated tool calls and returns descriptive "unavailable tool" messages with valid alternatives.
14
+ - Converts Zod validation errors and runtime execution failures into model-readable feedback strings.
15
+ - **Normalized Provider Orchestration**: Unified tool-control behavior across OpenAI, Anthropic, Gemini, Bedrock, and Mistral.
16
+ - **Advanced Transcription**: Deep diarization and word-level timestamp support.
17
+ - Added `timestamp_granularities` for precise word-level timing in Whisper.
18
+ - Enhanced `Transcription` class with `.meta` and `.raw` getters for DB parity with `ChatResponseString`.
19
+ - Fixed speaker-label preservation across OpenAI and Mistral transcription adapters.
20
+ - **Gemini 2.5 Advanced Support**:
21
+ - **Structured Output**: Native `responseJsonSchema` respect with improved `nullable` and `anyOf` mapping.
22
+ - **Parallel Tool Support**: Grouped tool responses in a single message for higher accuracy.
23
+ - **Inline Generated Images**: Surface model-generated images (like Gemini Nano) as `attachments` directly in the chat response.
24
+ - **Advanced Image Editing & Manipulation**:
25
+ - **In-painting & Edits**: Added support for editing existing images via `images` and `mask` parameters.
26
+ - **Image Variations**: Generate new variations of a source image by providing it to the `paint()` method without a prompt.
27
+ - **Broad Asset Support**: Seamlessly handle local files, remote URLs, and base64 strings as image sources.
28
+ - **Multimodal Cost Tracking**: Added `image_tokens` to usage tracking with automated cost calculation in the `ModelRegistry`.
29
+ - **Enhanced OpenAI Image Support**: Native integration with `/v1/images/edits` and `/v1/images/variations` endpoints, including automatic fallback to `gpt-image-1` (DALL-E 2) for manipulation tasks.
30
+
31
+ ### Improvements
32
+
33
+ - **Code Consolidation**: Unified OpenAI-compatible `tool_choice` normalization logic into a shared utility.
34
+ - **TypeScript Alignment**: Hardened type definitions for `ToolChoice` and provider-specific request bodies.
35
+ - **Enhanced Verification**: New comprehensive unit test suite for tool failure recovery paths and updated example scripts.
36
+ - **Testing DX**: Major upgrades to `@node-llm/testing` mocker.
37
+ - Added `.throws()` support for chaos engineering and failure simulation.
38
+ - Improved `.callsTool()` to support simultaneous conversational content.
39
+ - Surfaced `thinking`, `metadata`, and `reasoning` through the mock execution proxy.
40
+
5
41
  ## [1.15.0] - 2026-03-28 (@node-llm/core)
6
42
 
7
43
  ### Features
@@ -22,6 +58,7 @@ All notable changes to this project will be documented in this file.
22
58
  ### Features
23
59
 
24
60
  - **Enhanced Tool Persistence**: Correctly capture schema-validated tool arguments in `AgentSession` hooks.
61
+ - **Self-Correction Tracking**: New `correctionRounds` column in `LlmRequest` to track middleware retry attempts when using `SchemaSelfCorrection`.
25
62
  - **Improved Type Safety**: Resolved generic constraint issues in `createAgentSession` to better support user-defined agent interfaces.
26
63
 
27
64
  ## [1.14.1] - 2026-03-14 (@node-llm/core)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@node-llm/orm",
3
- "version": "0.7.1",
3
+ "version": "0.8.0",
4
4
  "description": "Database persistence layer for NodeLLM - Chat, Message, and ToolCall tracking with streaming support",
5
5
  "publishConfig": {
6
6
  "access": "public"
@@ -21,6 +21,15 @@
21
21
  "types": "./dist/adapters/prisma/index.d.ts"
22
22
  }
23
23
  },
24
+ "scripts": {
25
+ "build": "prisma generate --schema=schema.prisma && tsc",
26
+ "test": "vitest run",
27
+ "test:docs": "vitest run test/docs",
28
+ "test:watch": "vitest",
29
+ "prepack": "npm run build && cp ../../CHANGELOG.md ./CHANGELOG.md",
30
+ "postpack": "rm ./CHANGELOG.md",
31
+ "prepublishOnly": "npm run build && npm run test:docs"
32
+ },
24
33
  "keywords": [
25
34
  "llm",
26
35
  "orm",
@@ -65,13 +74,7 @@
65
74
  "@types/node": "^20.0.0",
66
75
  "prisma": "^5.0.0",
67
76
  "typescript": "^5.0.0",
68
- "vitest": "^1.0.0"
77
+ "vitest": "^4.0.0"
69
78
  },
70
- "dependencies": {},
71
- "scripts": {
72
- "build": "prisma generate --schema=schema.prisma && tsc",
73
- "test": "vitest run",
74
- "test:docs": "vitest run test/docs",
75
- "test:watch": "vitest"
76
- }
77
- }
79
+ "dependencies": {}
80
+ }
package/schema.prisma CHANGED
@@ -87,13 +87,14 @@ model LlmRequest {
87
87
  chatId String
88
88
  messageId String? // Optional because requests might fail before message creation
89
89
 
90
- provider String
91
- model String
92
- statusCode Int
93
- duration Int // milliseconds
94
- inputTokens Int
95
- outputTokens Int
96
- cost Float?
90
+ provider String
91
+ model String
92
+ statusCode Int
93
+ duration Int // milliseconds
94
+ inputTokens Int
95
+ outputTokens Int
96
+ cost Float?
97
+ correctionRounds Int? // Number of self-correction retries (v0.7.0+)
97
98
 
98
99
  createdAt DateTime @default(now())
99
100
 
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;
@@ -66,9 +66,14 @@ export class Chat extends BaseChat {
66
66
 
67
67
  const llmInstance = provider ? this.llm.withProvider(provider as string) : this.llm;
68
68
 
69
+ // `schema` needs core's own normalization (raw Zod schema -> Schema
70
+ // instance), so it's applied via withSchema() below rather than spread
71
+ // as a raw ChatOptions field.
72
+ const { schema, ...chatOptions } = this.localOptions;
73
+
69
74
  const coreChat = llmInstance.chat(model || undefined, {
70
75
  messages: history,
71
- ...this.localOptions,
76
+ ...chatOptions,
72
77
  middlewares: this.customMiddlewares
73
78
  }) as any;
74
79
 
@@ -77,6 +82,10 @@ export class Chat extends BaseChat {
77
82
  coreChat.withTools(this.customTools);
78
83
  }
79
84
 
85
+ if (schema) {
86
+ coreChat.withSchema(schema);
87
+ }
88
+
80
89
  // --- Persistence Hooks ---
81
90
 
82
91
  coreChat.onToolCallStart(async (call: any) => {
@@ -174,6 +183,32 @@ export class Chat extends BaseChat {
174
183
  });
175
184
  }
176
185
 
186
+ if (this.userHooks.onToolCallError.length > 0) {
187
+ coreChat.onToolCallError(async (call: any, error: Error) => {
188
+ // First handler to return a directive (STOP/CONTINUE/RETRY) wins,
189
+ // but every handler still runs so all of them get to observe it.
190
+ let directive: any;
191
+ for (const h of this.userHooks.onToolCallError) {
192
+ const value = await h(call, error);
193
+ if (value !== undefined && directive === undefined) {
194
+ directive = value;
195
+ }
196
+ }
197
+ return directive;
198
+ });
199
+ }
200
+
201
+ if (this.userHooks.onConfirmToolCall.length > 0) {
202
+ coreChat.onConfirmToolCall(async (call: any) => {
203
+ // Every registered handler must approve for the call to proceed.
204
+ for (const h of this.userHooks.onConfirmToolCall) {
205
+ const approved = await h(call);
206
+ if (approved === false) return false;
207
+ }
208
+ return true;
209
+ });
210
+ }
211
+
177
212
  return coreChat;
178
213
  }
179
214
 
@@ -76,9 +76,14 @@ describe("AgentSession", () => {
76
76
  metadata: { userId: "user-1" }
77
77
  });
78
78
 
79
- const session = await createAgentSession(mockPrisma as any, mockLlm, TestAgent, {
80
- metadata: { userId: "user-1" }
81
- });
79
+ const session = await createAgentSession<Record<string, any>, TestAgent>(
80
+ mockPrisma as any,
81
+ mockLlm,
82
+ TestAgent,
83
+ {
84
+ metadata: { userId: "user-1" }
85
+ }
86
+ );
82
87
 
83
88
  // Verify DB calls
84
89
  expect(mockPrisma.llmChat.create).toHaveBeenCalledWith(
@@ -211,7 +216,10 @@ describe("AgentSession", () => {
211
216
 
212
217
  class LazyTestAgent extends Agent<TestInputs> {
213
218
  static model = "gpt-4-lazy";
214
- static instructions = (i: TestInputs) => `Hello ${i.userName}`;
219
+ // Static members can't reference the class's own generic type parameter
220
+ // in TypeScript, so this matches the base class's static signature
221
+ // (Record<string, any>) and narrows internally.
222
+ static instructions = (i: Record<string, any>) => `Hello ${(i as TestInputs).userName}`;
215
223
  }
216
224
 
217
225
  it("injects metadata as inputs for lazy resolution during load", async () => {
@@ -0,0 +1,180 @@
1
+ import { describe, it, expect, beforeEach, vi } from "vitest";
2
+ import { createChat } from "../src/adapters/prisma/index.js";
3
+
4
+ // Mock Prisma Client
5
+ const createMockPrisma = () => {
6
+ const messages: any[] = [];
7
+ const chats: any[] = [];
8
+
9
+ const tables: any = {
10
+ chat: {
11
+ create: vi.fn(async ({ data }) => {
12
+ const chat = { id: "chat-123", ...data, createdAt: new Date(), updatedAt: new Date() };
13
+ chats.push(chat);
14
+ return chat;
15
+ })
16
+ },
17
+ message: {
18
+ create: vi.fn(async ({ data }) => {
19
+ const message = { id: `msg-${messages.length}`, ...data, createdAt: new Date() };
20
+ messages.push(message);
21
+ return message;
22
+ }),
23
+ findMany: vi.fn(async ({ where }) => {
24
+ let filtered = messages.filter((m) => m.chatId === where.chatId);
25
+ if (where.id?.notIn) {
26
+ filtered = filtered.filter((m) => !where.id.notIn.includes(m.id));
27
+ }
28
+ return filtered;
29
+ }),
30
+ update: vi.fn(async ({ where, data }) => {
31
+ const message = messages.find((m) => m.id === where.id);
32
+ if (message) {
33
+ Object.assign(message, data);
34
+ }
35
+ return message;
36
+ }),
37
+ delete: vi.fn()
38
+ },
39
+ toolCall: {
40
+ create: vi.fn(),
41
+ update: vi.fn()
42
+ },
43
+ request: {
44
+ create: vi.fn()
45
+ }
46
+ };
47
+
48
+ return new Proxy(tables, {
49
+ get(target, prop) {
50
+ if (prop in target) return target[prop];
51
+ if (typeof prop === "string") {
52
+ if (prop.toLowerCase().includes("chat")) return target.chat;
53
+ if (prop.toLowerCase().includes("message")) return target.message;
54
+ if (prop.toLowerCase().includes("toolcall")) return target.toolCall;
55
+ if (prop.toLowerCase().includes("request")) return target.request;
56
+ }
57
+ return undefined;
58
+ }
59
+ });
60
+ };
61
+
62
+ // Mock NodeLLM capturing everything passed/registered on the core chat
63
+ const createMockLLM = () => {
64
+ let capturedOptions: any;
65
+ let capturedSchema: any;
66
+
67
+ const mockChat: any = {
68
+ withTools: vi.fn(() => mockChat),
69
+ withSchema: vi.fn((schema) => {
70
+ capturedSchema = schema;
71
+ return mockChat;
72
+ }),
73
+ onToolCallStart: vi.fn(() => mockChat),
74
+ onToolCallEnd: vi.fn(() => mockChat),
75
+ onToolCallError: vi.fn(() => mockChat),
76
+ onConfirmToolCall: vi.fn(() => mockChat),
77
+ afterResponse: vi.fn(() => mockChat),
78
+ onNewMessage: vi.fn(() => mockChat),
79
+ onEndMessage: vi.fn(() => mockChat),
80
+ beforeRequest: vi.fn(() => mockChat),
81
+ ask: vi.fn(async () => ({
82
+ content: "Test response",
83
+ meta: {},
84
+ usage: { input_tokens: 10, output_tokens: 5, total_tokens: 15 },
85
+ model: "gpt-4o-mini",
86
+ provider: "openai"
87
+ }))
88
+ };
89
+
90
+ const llm: any = {
91
+ chat: vi.fn((_model, options) => {
92
+ capturedOptions = options;
93
+ return mockChat;
94
+ }),
95
+ withProvider: vi.fn(() => llm),
96
+ getCapturedOptions: () => capturedOptions,
97
+ getCapturedSchema: () => capturedSchema
98
+ };
99
+
100
+ return llm;
101
+ };
102
+
103
+ describe("ORM toolChoice/toolCalls/schema options", () => {
104
+ let mockPrisma: any;
105
+ let mockLLM: any;
106
+
107
+ beforeEach(() => {
108
+ mockPrisma = createMockPrisma();
109
+ mockLLM = createMockLLM();
110
+ });
111
+
112
+ it("forwards toolChoice to the underlying core chat", async () => {
113
+ const chat = await createChat(mockPrisma, mockLLM, {
114
+ model: "gpt-4o-mini",
115
+ toolChoice: { type: "function", function: { name: "get_weather" } }
116
+ });
117
+
118
+ await chat.ask("Hello");
119
+
120
+ expect(mockLLM.getCapturedOptions()).toEqual(
121
+ expect.objectContaining({
122
+ toolChoice: { type: "function", function: { name: "get_weather" } }
123
+ })
124
+ );
125
+ });
126
+
127
+ it("forwards toolCalls to the underlying core chat", async () => {
128
+ const chat = await createChat(mockPrisma, mockLLM, {
129
+ model: "gpt-4o-mini",
130
+ toolCalls: "one"
131
+ });
132
+
133
+ await chat.ask("Hello");
134
+
135
+ expect(mockLLM.getCapturedOptions()).toEqual(expect.objectContaining({ toolCalls: "one" }));
136
+ });
137
+
138
+ it("supports withToolChoice/withToolCalls fluent methods", async () => {
139
+ const chat = await createChat(mockPrisma, mockLLM, { model: "gpt-4o-mini" });
140
+ chat.withToolChoice("required").withToolCalls(1);
141
+
142
+ await chat.ask("Hello");
143
+
144
+ expect(mockLLM.getCapturedOptions()).toEqual(
145
+ expect.objectContaining({ toolChoice: "required", toolCalls: 1 })
146
+ );
147
+ });
148
+
149
+ it("applies a schema passed at createChat() time via withSchema(), not the raw options spread", async () => {
150
+ const schema = { name: "output", shape: {} };
151
+ const chat = await createChat(mockPrisma, mockLLM, {
152
+ model: "gpt-4o-mini",
153
+ schema
154
+ });
155
+
156
+ await chat.ask("Hello");
157
+
158
+ // schema must NOT be forwarded raw (core doesn't normalize it outside withSchema())
159
+ expect(mockLLM.getCapturedOptions().schema).toBeUndefined();
160
+ expect(mockLLM.getCapturedSchema()).toBe(schema);
161
+ });
162
+
163
+ it("applies a schema set via the fluent withSchema() method", async () => {
164
+ const schema = { name: "output", shape: {} };
165
+ const chat = await createChat(mockPrisma, mockLLM, { model: "gpt-4o-mini" });
166
+ chat.withSchema(schema);
167
+
168
+ await chat.ask("Hello");
169
+
170
+ expect(mockLLM.getCapturedSchema()).toBe(schema);
171
+ });
172
+
173
+ it("does not call withSchema when no schema is configured", async () => {
174
+ const chat = await createChat(mockPrisma, mockLLM, { model: "gpt-4o-mini" });
175
+ await chat.ask("Hello");
176
+
177
+ const mockChat = mockLLM.chat.mock.results[0].value;
178
+ expect(mockChat.withSchema).not.toHaveBeenCalled();
179
+ });
180
+ });