@node-llm/orm 0.8.0 → 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.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,155 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [1.19.0] - 2026-11-02 (@node-llm/core)
6
+
7
+ ### Features
8
+
9
+ - **Azure AI Foundry Provider**: `provider: "azure"` reaches every model deployed on an Azure resource, OpenAI's and others' such as Llama, DeepSeek, Mistral, Grok and Phi, with chat, streaming, tools, structured output, vision, embeddings and model listing. `azureApiBase` takes any address the Azure portal shows (a deployment's, a model endpoint's, the resource's v1 address or the resource itself) and the model is the deployment's name. Requests are signed with the resource's key (`azureApiKey`), as a bearer token on serverless endpoints, or with a Microsoft Entra ID token (`azureAuthToken`). `azureDeployments` maps deployment names to the models they run, so capabilities and cost are known; a deployment NodeLLM doesn't know is assumed able, since Azure decides. Configured from `AZURE_API_KEY`, `AZURE_API_BASE` and `AZURE_AUTH_TOKEN` too.
10
+ - **Tools on OpenAI GPT-6**: GPT-6 models, like GPT-5.6, take function tools through the Responses API, on OpenAI and on Azure.
11
+ - **Tools on OpenAI GPT-5.6**: GPT-5.6 models reject function tools on Chat Completions ("use /v1/responses"). NodeLLM now sends tool requests for them through OpenAI's Responses API, mapping messages, tool calls and results, images, structured output and reasoning effort, with nothing stored on OpenAI's side. Every other request still uses Chat Completions as before.
12
+ - **`envFallback`**: `createLLM({ envFallback: false })` takes keys, base URLs and the provider only from what is passed in code, never from environment variables. Apps that call providers with each customer's key set it, so a missing key fails instead of quietly using the server's own. The default is unchanged.
13
+ - **`maxCost`**: A chat option and agent setting that caps what an ask may spend, in US dollars. A tool loop that has spent the limit stops before its next request and throws `CostLimitError` (code `COST_LIMIT`), with the `limit` and `usage`, and the tool calls it didn't run are answered so the chat can be asked again. A safety net for agents whose tools can return very large results.
14
+ - **`keepToolResults`**: A chat option and agent setting that sends only the most recent tool results in full, replacing older ones with a short placeholder. Long tool loops, such as an agent reading page after page, no longer resend every earlier result on every request. Results are left out in blocks of N, so the start of the conversation changes only every N requests and prompt caching keeps working. The chat's history keeps them all.
15
+ - **Response Latency**: Each response has `latency`, how long the provider took to answer that request in milliseconds, set before `afterResponse` hooks run and kept by `withContent()`. What `ask()` returns has the total across its requests. The ORM records it as each request's `duration`, which was always `0` before.
16
+ - **Prompt Caching**: `withPromptCache()`, the `promptCache` chat option and `static promptCache` on Agents cache the repeated start of each request (instructions, tools and earlier turns) on Anthropic, so an agent loop pays the full input price once. Providers that cache automatically are unaffected. Providers declare it with the new optional `supportsPromptCaching(model)` capability.
17
+ - **`defineTool()`**: Defines a tool without a class, with the arguments of `execute` typed from its Zod schema, as `defineAgent()` does for agents.
18
+ - **Zod 4 Schemas**: `withSchema()`, the `schema` option, Agents and `Tool` accept Zod 4 schemas (Zod 4.2 or later, from `"zod"`) as well as Zod 3, with types inferred from either. Schemas are recognised by shape, so a schema from another copy of Zod validates too; before, it skipped validation silently.
19
+ - **Adaptive Thinking for Claude**: On Claude generations that only think adaptively (Opus 4.7 and later, Sonnet 5 and later, Fable), `withEffort()` and `withThinking({ effort })` now send adaptive thinking with `output_config.effort`. Before, effort was not sent to Anthropic, and these models reject a fixed `budget`. `effort` also accepts `"xhigh"` and `"max"`.
20
+ - **Thinking Display**: `withThinking({ display: "summarized" })` returns a summary of Claude's thinking, which newer models hide by default.
21
+ - **Typed `defineAgent()` Output**: `defineAgent({ schema })` infers the Zod schema's type, so `response.data` is typed without repeating the schema as a type argument.
22
+ - **`LLMConfig` Type**: The options type `createLLM()` takes is now exported, so an app can build them (for example a provider and its key from its own settings) without reaching for `Parameters<typeof createLLM>`.
23
+ - **`ToolCallLimitError`**: Reaching `maxToolCalls` now throws `ToolCallLimitError` (code `TOOL_CALL_LIMIT`) instead of a plain `Error`. It carries the `limit` and the `usage` of every request in that ask. The message is unchanged.
24
+
25
+ ### Bug Fixes
26
+
27
+ - **Zod Security Fix**: Core now depends on Zod 4.6.6 or later, which fixes a memory exhaustion advisory (GHSA-mrhx-c7xc-m3w5) that has no fix in Zod 3. The `z` NodeLLM exports is unchanged: it is still the Zod 3 API, now from `zod/v3`, and Zod 3 and Zod 4 schemas work as before.
28
+ - **Billing Errors on Every Provider**: Whether an account can't pay is now decided the same way for every provider (status 402, the `insufficient_quota` code, or wording such as "credit balance", "insufficient balance" or "billing"), and is always an `InsufficientQuotaError`. Before, each provider checked differently: Anthropic's 400 and xAI's billing errors weren't recognised, and only DeepSeek handled 402. A plain "quota" is no longer treated as billing, since Gemini and others use it for per-minute rate limits, which should be retried. The xAI handler no longer prints raw error bodies to the console.
29
+ - **No Retries When Out of Quota**: `InsufficientQuotaError` is a `RateLimitError`, so retries kept trying an account with no credit or quota left, with growing back-off. It now fails straight away, as other fatal errors do.
30
+ - **`beforeRequest` in Tool Loops**: `ask()` ran `beforeRequest` hooks only on the first request; the requests that follow each round of tool calls skipped them, so content policy hooks (such as redaction) didn't apply to tool results. They now run on every request, as they already did when streaming.
31
+ - **Prompt Cache Usage and Cost**: On Anthropic and Bedrock, `input_tokens` now includes tokens read from and written to the prompt cache, as it does on the other providers, and `total_tokens` with it. Before, cached input was subtracted from a total that didn't include it, so the cost of a cached request was too low or even negative. Cache writes are now priced at the model's cache write rate (1.25x input on Claude). Streaming requests to Anthropic now report cache usage too.
32
+ - **Anthropic Streaming Parameters**: Streaming requests to Anthropic now send extra parameters, such as those from `withParams()`, as non-streaming requests already did. Both now build the same request body.
33
+ - **Cancelling Requests**: An `AbortSignal` passed to `ask()` now cancels the request on Anthropic, Bedrock, DeepSeek, Gemini, Mistral and xAI, as it already did on OpenAI. Before, those providers ignored it, and Anthropic, DeepSeek, Gemini and xAI also sent it in the request body.
34
+ - **Temperature on Models That Reject It**: Claude Opus 4.7 and later, the Claude 5 family, OpenAI's reasoning models and others return an error when a request sets a temperature. For models the registry marks this way, chats and agents now send the request without one and log a warning once per model. Providers declare it with the new optional `supportsTemperature(model)` capability.
35
+ - **Tool Call Limit Leaves a Valid History**: When `maxToolCalls` is reached, the tool calls the model asked for but that weren't run are now answered with an error result. Before, the history ended with unanswered tool calls, which providers reject, so the chat could not be asked again.
36
+ - **Streaming Tool Call Limit**: `stream()` counted every model request against `maxToolCalls`, so it allowed one round of tool calls fewer than `ask()`. Both now count rounds of tool calls.
37
+ - **Agent and Chat `provider` Option**: An Agent's `provider` (static or passed to the constructor) and `chat(model, { provider })` now choose the provider. Before, they were ignored, so the chat used the instance's own provider, or threw `LLM provider not configured` when it had none (for example `NodeLLM` without `NODELLM_PROVIDER`).
38
+
39
+ ### Improvements
40
+
41
+ - **Model Catalog Sync**: `models.json` now records each model's thinking controls (`metadata.reasoning_options`) and whether it accepts a temperature (`metadata.temperature`) from models.dev.
42
+
43
+ ### Deprecations
44
+
45
+ - **Zod 3 schemas**: still supported, but deprecated and may be removed in a future major version. Use Zod 4 for new code. The `z` exported by `@node-llm/core` stays Zod 3 until then.
46
+
47
+ ### Compatibility
48
+
49
+ - Anthropic and Bedrock `input_tokens` and `total_tokens` are higher for requests that read or write the prompt cache, because they now include those tokens.
50
+ - Zod 3 schemas are converted and validated exactly as before.
51
+ - `stream()` allows one more round of tool calls than before, matching `ask()`.
52
+ - After `maxToolCalls` is reached, the chat history ends with an error tool result for each call that wasn't run.
53
+ - Requests to budget-thinking Claude models (Sonnet 4.5, Haiku 4.5, Opus 4.5, Opus 4.6, Sonnet 4.6) are unchanged: `budget` is sent as before, and `effort` alone is still not sent.
54
+
55
+ ## [0.3.1] - 2026-11-02 (@node-llm/mcp)
56
+
57
+ ### Bug Fixes
58
+
59
+ - **MCP SDK Security Fixes**: `@modelcontextprotocol/sdk` is now 1.32.0 or later, which fixes advisories on OAuth credentials sent to a server-chosen authorization server, cross-origin redirects re-sending headers, unbounded request bodies and batches, and tasks not tied to their session.
60
+
61
+ ## [0.9.0] - 2026-11-02 (@node-llm/orm)
62
+
63
+ ### Features
64
+
65
+ - **Custom Stores**: Chats and agent sessions record through a `ChatStore`. A Prisma client still works as before (it is wrapped in the new `PrismaStore`); any other store, such as one that sends records to your own API, can be passed in its place. `isChatStore()`, `PrismaStore` and the store record types are exported.
66
+ - **Prisma Is Optional**: `@prisma/client` is now an optional peer dependency and the build no longer runs `prisma generate`, since only the Prisma store uses Prisma. Apps with their own store don't install it.
67
+ - **Session Tools**: `createAgentSession()` takes `tools`, for tools built per session (for example ones bound to a user's data), used in place of the agent class's own.
68
+
69
+ ### Bug Fixes
70
+
71
+ - **Agent Session Request Duration**: Requests recorded by agent sessions now store the response's latency. Before, their `duration` was always `0`.
72
+
73
+ ## [1.18.0] - 2026-10-03 (@node-llm/core)
74
+
75
+ ### Features
76
+
77
+ - **Judgments**: `NodeLLM.judge()` asks TypeSafe's Jev models (`jev-latest`, `jev-preview`) yes/no, multiple-choice and scored questions about a piece of state, and returns calibrated probabilities and confidence per answer. Build questions with `probability()`, `choice()` and `score()`, or reuse a set with `defineJudge()`. Configure with `typesafeApiKey` (`TYPESAFE_API_KEY`, or `JEV_API_KEY`). Usage is priced at $0.042 per million input tokens.
78
+ - **Typed Structured Output**: `withSchema(zodSchema)` now infers the schema's type, so `response.data` from `Chat#ask()` and `Agent#ask()`/`say()` is typed instead of `unknown`.
79
+
80
+ ### Bug Fixes
81
+
82
+ - **`schema` Chat Option**: A Zod schema or plain JSON Schema passed as the `schema` option no longer throws when the request is built; it is converted as `withSchema()` does.
83
+ - **Tool Typing**: `Tool`'s argument type defaults to `Record<string, any>`, so `execute({ location })` overrides compile and the tool is accepted by `withTool()`. Tool-call hooks (`onToolCall`, `onToolCallStart`, `onToolCallEnd`, `onConfirmToolCall` and the Agent hooks) receive a `ToolCall`.
84
+ - **Tool Execution Mode**: `withToolExecution()`, the `toolExecution` chat option and the `createLLM` config accept the mode's string value (`"confirm"`) as well as the enum member.
85
+ - **Transcription Options**: `transcribe()` accepts `timestamp_granularities`.
86
+
87
+ ### Improvements
88
+
89
+ - **Model Catalog Sync**: Refreshed `models.json` and aliases with the latest provider model catalogs.
90
+ - **Docs**: Every code example in the docs and READMEs now compiles and runs; broken links and retired model IDs are fixed.
91
+
92
+ ### Compatibility
93
+
94
+ - Annotating a chat with a data type before setting a schema, as in `const chat: Chat<Person> = NodeLLM.chat()`, no longer compiles. Use `NodeLLM.chat().withSchema(PersonSchema)`, which infers the type.
95
+
96
+ ## [0.3.0] - 2026-10-03 (@node-llm/mcp)
97
+
98
+ ### Features
99
+
100
+ - **`MCPPrompt.getMessages()`**: Resolves a prompt and returns NodeLLM messages, ready for `chat.addMessages()`. Converts text, images, audio and resources. `get()` still returns MCP's own format, which a chat cannot send.
101
+
102
+ ### Bug Fixes
103
+
104
+ - **Installable from npm**: The `@node-llm/core` peer dependency was published as `workspace:*`, so `npm install @node-llm/mcp` failed with `EUNSUPPORTEDPROTOCOL`. It is now `^1.17.0`.
105
+
106
+ ## [0.6.0] - 2026-10-03 (@node-llm/testing)
107
+
108
+ ### Features
109
+
110
+ - **Judgment Mocking**: `mocker.judge()` mocks `NodeLLM.judge()` calls, and VCR records and replays them.
111
+
112
+ ### Improvements
113
+
114
+ - **Shared Method Registry**: VCR and the Mocker intercept provider methods from one shared registry, so a new provider method is covered by both.
115
+
116
+ ## [1.17.0] - 2026-07-04 (@node-llm/core)
117
+
118
+ ### Features
119
+
120
+ - **Concurrent Tool Execution**: Opt-in `toolConcurrency` config / `withToolConcurrency()` executes independent tool calls in parallel within `ask()`, `stream()`, and Agent mode instead of one at a time.
121
+ - **Additive Callback Stacking**: `on*()`, `beforeRequest()`, and `afterResponse()` handlers now stack instead of silently overwriting the previous registration, so independent concerns can each register their own hook.
122
+ - **Bedrock Custom Endpoints**: Added `bedrockApiBase` for routing Bedrock requests through a custom endpoint.
123
+ - **`ToolChoice` Export**: Exposed the `ToolChoice` type from the package root for downstream packages (e.g. `@node-llm/orm`).
124
+
125
+ ### Improvements
126
+
127
+ - **Provider Factory Typing**: Widened `registerProvider()`'s factory type to accept configuration.
128
+ - **Tool Response Fidelity**: Metadata and attachments now carry through to the final tool-call response.
129
+ - **Model Catalog Sync**: Refreshed `models.json` and aliases with the latest provider model catalogs.
130
+
131
+ ## [0.2.0] - 2026-07-04 (@node-llm/mcp)
132
+
133
+ ### Features
134
+
135
+ - **MCP Sampling Support**: Servers can now request LLM completions from the client via `sampling/createMessage`. `createLLMSamplingHandler()` answers these requests using an existing NodeLLM instance, or pass a custom handler for full control over the response.
136
+
137
+ ## [0.8.0] - 2026-07-04 (@node-llm/orm)
138
+
139
+ ### Features
140
+
141
+ - **Tool Execution Options**: `withToolConcurrency()`, `withToolExecution()` (`auto` / `confirm` / `dry-run`), `onConfirmToolCall()`, and `onToolCallError()` bring core's tool-orchestration controls to Prisma-backed chats.
142
+ - **Tool Choice & Schema Options**: `withToolChoice()`, `withToolCalls()`, and `withSchema()` are now supported in the ORM adapter.
143
+
144
+ ## [0.5.1] - 2026-07-04 (@node-llm/testing)
145
+
146
+ ### Bug Fixes
147
+
148
+ - **VCR Auto-Naming Race**: Fixed an async race condition in VCR cassette auto-naming.
149
+
150
+ ### Improvements
151
+
152
+ - **Peer Dependency**: `vitest` is now declared as a peer dependency instead of a hard dependency, avoiding version resolution conflicts with a consumer's own vitest install.
153
+
5
154
  ## [1.16.0] - 2026-04-18 (@node-llm/core)
6
155
 
7
156
  ### Features
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 NodeLLM contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -165,18 +165,18 @@ For **stateful agents** with persistence, use `AgentSession`. This follows the "
165
165
  ```typescript
166
166
  import { Agent, Tool, z } from "@node-llm/core";
167
167
 
168
- class LookupOrderTool extends Tool {
169
- static definition = {
170
- name: "lookup_order",
171
- description: "Look up order status",
172
- parameters: z.object({ orderId: z.string() })
173
- };
174
- async execute({ orderId }) {
168
+ class LookupOrderTool extends Tool<{ orderId: string }> {
169
+ name = "lookup_order";
170
+ description = "Look up order status";
171
+ schema = z.object({ orderId: z.string() });
172
+
173
+ async execute({ orderId }: { orderId: string }) {
175
174
  return { status: "shipped", eta: "Tomorrow" };
176
175
  }
177
176
  }
178
177
 
179
- class SupportAgent extends Agent {
178
+ // The session metadata is the agent's input type.
179
+ class SupportAgent extends Agent<{ userId: string; ticketId: string }> {
180
180
  static model = "gpt-4.1";
181
181
  static instructions = "You are a helpful support agent.";
182
182
  static tools = [LookupOrderTool];
@@ -197,8 +197,8 @@ await session.ask("Where is my order #789?");
197
197
  console.log(session.id); // "sess_abc123" - save this!
198
198
 
199
199
  // Resume later (even after code upgrades)
200
- const session = await loadAgentSession(prisma, llm, SupportAgent, "sess_abc123");
201
- await session.ask("Can you cancel it?");
200
+ const resumed = await loadAgentSession(prisma, llm, SupportAgent, "sess_abc123");
201
+ await resumed?.ask("Can you cancel it?");
202
202
  ```
203
203
 
204
204
  ### Code Wins Principle
@@ -252,8 +252,8 @@ const chat = await createChat(prisma, llm, {
252
252
  });
253
253
 
254
254
  // Stream tokens in real-time
255
- for await (const token of chat.askStream("Tell me a story")) {
256
- process.stdout.write(token); // Print each token immediately
255
+ for await (const chunk of chat.askStream("Tell me a story")) {
256
+ process.stdout.write(chunk.content); // Print each token immediately
257
257
  }
258
258
 
259
259
  // Message is automatically persisted after streaming completes
@@ -302,10 +302,10 @@ const tableNames = {
302
302
  };
303
303
 
304
304
  // Create chat with custom table names
305
- const chat = await createChat(prisma, llm, { model: "gpt-4" }, tableNames);
305
+ const chat = await createChat(prisma, llm, { model: "gpt-4", tableNames });
306
306
 
307
307
  // Load chat (must use same table names)
308
- const loaded = await loadChat(prisma, llm, chatId, tableNames);
308
+ const loaded = await loadChat(prisma, llm, chatId, { tableNames });
309
309
  ```
310
310
 
311
311
  **Note**: Your Prisma schema model names must match the table names you specify. For example:
@@ -317,6 +317,30 @@ model AssistantChat {
317
317
  }
318
318
  ```
319
319
 
320
+ ### Custom Stores
321
+
322
+ Chats and agent sessions record through a store. By default that's your Prisma client, but anything that implements `ChatStore` works in its place. That's useful when the code that talks to the model can't reach the database, such as a worker on another machine that reports to your API:
323
+
324
+ ```typescript
325
+ import { createAgentSession, type ChatStore } from "@node-llm/orm";
326
+
327
+ class ApiStore implements ChatStore {
328
+ async createChat(chat) {
329
+ return post("/llm/chats", chat);
330
+ }
331
+ async createMessage(message) {
332
+ return post("/llm/messages", message);
333
+ }
334
+ // ...updateMessage, listMessages, createToolCall, finishToolCall, createRequest and the rest
335
+ }
336
+
337
+ const session = await createAgentSession(new ApiStore(), llm, SupportAgent, {
338
+ tools: [lookupOrder] // tools for this session, in place of the agent class's own
339
+ });
340
+ ```
341
+
342
+ The records are the same as in the Prisma tables (chats, messages, tool calls with their results, and a request row per API call with its duration, tokens and cost), so one schema serves both. `createChat`, `loadChat`, `createAgentSession` and `loadAgentSession` take a store or a Prisma client; `isChatStore()` tells them apart.
343
+
320
344
  ### With Tools
321
345
 
322
346
  ```typescript
@@ -0,0 +1,124 @@
1
+ import type { Usage, Middleware, ToolExecutionMode, ToolChoice } from "@node-llm/core";
2
+ export interface ChatRecord {
3
+ id: string;
4
+ model?: string | null;
5
+ provider?: string | null;
6
+ instructions?: string | null;
7
+ metadata?: string | null;
8
+ createdAt: Date;
9
+ updatedAt: Date;
10
+ }
11
+ export interface ChatOptions {
12
+ model?: string;
13
+ provider?: string;
14
+ instructions?: string;
15
+ metadata?: Record<string, any>;
16
+ debug?: boolean;
17
+ persistence?: {
18
+ toolCalls?: boolean;
19
+ requests?: boolean;
20
+ };
21
+ thinking?: {
22
+ effort?: "low" | "medium" | "high" | "none";
23
+ budget?: number;
24
+ };
25
+ temperature?: number;
26
+ maxTokens?: number;
27
+ headers?: Record<string, string>;
28
+ maxToolCalls?: number;
29
+ toolConcurrency?: boolean;
30
+ toolExecution?: ToolExecutionMode;
31
+ toolChoice?: ToolChoice;
32
+ toolCalls?: "one" | "many" | number;
33
+ schema?: any;
34
+ requestTimeout?: number;
35
+ params?: Record<string, any>;
36
+ middlewares?: Middleware[];
37
+ }
38
+ export interface UserHooks {
39
+ onToolCallStart: ((call: any) => void | Promise<void>)[];
40
+ onToolCallEnd: ((call: any, result: any) => void | Promise<void>)[];
41
+ onToolCallError: ((call: any, error: Error) => any | Promise<any>)[];
42
+ onConfirmToolCall: ((call: any) => boolean | Promise<boolean>)[];
43
+ afterResponse: ((resp: any) => any | Promise<any>)[];
44
+ onNewMessage: (() => void | Promise<void>)[];
45
+ onEndMessage: ((message: any) => void | Promise<void>)[];
46
+ onBeforeRequest: ((messages: any[]) => any | Promise<any>)[];
47
+ }
48
+ /**
49
+ * BaseChat - A generic base class for ORM chat implementations.
50
+ */
51
+ export declare abstract class BaseChat<R extends ChatRecord = ChatRecord, O extends ChatOptions = ChatOptions> {
52
+ record: R;
53
+ options: O;
54
+ id: string;
55
+ protected localOptions: any;
56
+ protected customTools: any[];
57
+ protected customMiddlewares: Middleware[];
58
+ protected userHooks: UserHooks;
59
+ constructor(record: R, options?: O);
60
+ protected log(...args: any[]): void;
61
+ withInstructions(instruction: string, options?: {
62
+ replace?: boolean;
63
+ }): this;
64
+ system(instruction: string, options?: {
65
+ replace?: boolean;
66
+ }): this;
67
+ withTemperature(temp: number): this;
68
+ withModel(model: string): this;
69
+ withProvider(provider: string): this;
70
+ withTools(tools: any[]): this;
71
+ withTool(tool: any): this;
72
+ use(tool: any): this;
73
+ withSchema(schema: any): this;
74
+ withParams(params: Record<string, any>): this;
75
+ withThinking(thinking: {
76
+ effort?: "low" | "medium" | "high" | "none";
77
+ budget?: number;
78
+ }): this;
79
+ withEffort(effort: "low" | "medium" | "high" | "none"): this;
80
+ /**
81
+ * Runs independent tool calls within the same turn concurrently instead
82
+ * of sequentially. See core's Tools guide for details.
83
+ */
84
+ withToolConcurrency(enabled: boolean): this;
85
+ /**
86
+ * Controls how tool calls are executed: "auto" (default), "confirm"
87
+ * (calls onConfirmToolCall before each execution), or "dry-run".
88
+ */
89
+ withToolExecution(mode: ToolExecutionMode): this;
90
+ /**
91
+ * Forces, forbids, or requires a specific tool for the next request.
92
+ */
93
+ withToolChoice(choice: ToolChoice): this;
94
+ /**
95
+ * Restricts how many tool calls the model may return in a single turn:
96
+ * "one" (sequential), "many" (default), or an exact number.
97
+ */
98
+ withToolCalls(calls: "one" | "many" | number): this;
99
+ onToolCallStart(callback: (call: any) => void | Promise<void>): this;
100
+ onToolCall(callback: (call: any) => void | Promise<void>): this;
101
+ onToolCallEnd(callback: (call: any, result: any) => void | Promise<void>): this;
102
+ onToolResult(callback: (result: any) => void | Promise<void>): this;
103
+ /**
104
+ * Registers a handler run when a tool call throws. Return "STOP",
105
+ * "CONTINUE", or "RETRY" to control recovery; the first handler to return
106
+ * a directive wins, but every registered handler still runs.
107
+ */
108
+ onToolCallError(callback: (call: any, error: Error) => any | Promise<any>): this;
109
+ /**
110
+ * Registers an approval handler used when toolExecution is "confirm".
111
+ * Every registered handler must approve (return true) for the call to
112
+ * proceed.
113
+ */
114
+ onConfirmToolCall(callback: (call: any) => boolean | Promise<boolean>): this;
115
+ afterResponse(callback: (resp: any) => any | Promise<any>): this;
116
+ onBeforeRequest(callback: (messages: any[]) => any | Promise<any>): this;
117
+ onNewMessage(callback: () => void | Promise<void>): this;
118
+ onEndMessage(callback: (message: any) => void | Promise<void>): this;
119
+ /**
120
+ * Returns a usage summary for this chat session.
121
+ */
122
+ abstract stats(): Promise<Usage>;
123
+ }
124
+ //# sourceMappingURL=BaseChat.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"BaseChat.d.ts","sourceRoot":"","sources":["../src/BaseChat.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,182 @@
1
+ /**
2
+ * BaseChat - A generic base class for ORM chat implementations.
3
+ */
4
+ export class BaseChat {
5
+ record;
6
+ options;
7
+ id;
8
+ localOptions = {};
9
+ customTools = [];
10
+ customMiddlewares = [];
11
+ userHooks = {
12
+ onToolCallStart: [],
13
+ onToolCallEnd: [],
14
+ onToolCallError: [],
15
+ onConfirmToolCall: [],
16
+ afterResponse: [],
17
+ onNewMessage: [],
18
+ onEndMessage: [],
19
+ onBeforeRequest: []
20
+ };
21
+ constructor(record, options = {}) {
22
+ this.record = record;
23
+ this.options = options;
24
+ this.id = record.id;
25
+ // Initialize local options from record/options
26
+ this.localOptions.instructions = options.instructions || record.instructions;
27
+ this.localOptions.model = options.model || record.model;
28
+ this.localOptions.provider = options.provider || record.provider;
29
+ this.localOptions.thinking = options.thinking;
30
+ this.localOptions.temperature = options.temperature;
31
+ this.localOptions.maxTokens = options.maxTokens;
32
+ this.localOptions.headers = options.headers;
33
+ this.localOptions.maxToolCalls = options.maxToolCalls;
34
+ this.localOptions.toolConcurrency = options.toolConcurrency;
35
+ this.localOptions.toolExecution = options.toolExecution;
36
+ this.localOptions.toolChoice = options.toolChoice;
37
+ this.localOptions.toolCalls = options.toolCalls;
38
+ this.localOptions.schema = options.schema;
39
+ this.localOptions.requestTimeout = options.requestTimeout;
40
+ this.localOptions.params = options.params;
41
+ // Initialize middlewares
42
+ if (options.middlewares) {
43
+ this.customMiddlewares = options.middlewares;
44
+ }
45
+ }
46
+ log(...args) {
47
+ if (this.options?.debug) {
48
+ console.log(`[@node-llm/orm]`, ...args);
49
+ }
50
+ }
51
+ // --- Fluent Configuration Methods ---
52
+ withInstructions(instruction, options) {
53
+ if (options?.replace) {
54
+ this.localOptions.instructions = instruction;
55
+ }
56
+ else {
57
+ this.localOptions.instructions = (this.localOptions.instructions || "") + "\n" + instruction;
58
+ }
59
+ return this;
60
+ }
61
+ system(instruction, options) {
62
+ return this.withInstructions(instruction, options);
63
+ }
64
+ withTemperature(temp) {
65
+ this.localOptions.temperature = temp;
66
+ return this;
67
+ }
68
+ withModel(model) {
69
+ this.localOptions.model = model;
70
+ return this;
71
+ }
72
+ withProvider(provider) {
73
+ this.localOptions.provider = provider;
74
+ return this;
75
+ }
76
+ withTools(tools) {
77
+ this.customTools.push(...tools);
78
+ return this;
79
+ }
80
+ withTool(tool) {
81
+ this.customTools.push(tool);
82
+ return this;
83
+ }
84
+ use(tool) {
85
+ return this.withTool(tool);
86
+ }
87
+ withSchema(schema) {
88
+ this.localOptions.schema = schema;
89
+ return this;
90
+ }
91
+ withParams(params) {
92
+ this.localOptions.params = { ...(this.localOptions.params || {}), ...params };
93
+ return this;
94
+ }
95
+ withThinking(thinking) {
96
+ this.localOptions.thinking = { ...(this.localOptions.thinking || {}), ...thinking };
97
+ return this;
98
+ }
99
+ withEffort(effort) {
100
+ return this.withThinking({ effort });
101
+ }
102
+ /**
103
+ * Runs independent tool calls within the same turn concurrently instead
104
+ * of sequentially. See core's Tools guide for details.
105
+ */
106
+ withToolConcurrency(enabled) {
107
+ this.localOptions.toolConcurrency = enabled;
108
+ return this;
109
+ }
110
+ /**
111
+ * Controls how tool calls are executed: "auto" (default), "confirm"
112
+ * (calls onConfirmToolCall before each execution), or "dry-run".
113
+ */
114
+ withToolExecution(mode) {
115
+ this.localOptions.toolExecution = mode;
116
+ return this;
117
+ }
118
+ /**
119
+ * Forces, forbids, or requires a specific tool for the next request.
120
+ */
121
+ withToolChoice(choice) {
122
+ this.localOptions.toolChoice = choice;
123
+ return this;
124
+ }
125
+ /**
126
+ * Restricts how many tool calls the model may return in a single turn:
127
+ * "one" (sequential), "many" (default), or an exact number.
128
+ */
129
+ withToolCalls(calls) {
130
+ this.localOptions.toolCalls = calls;
131
+ return this;
132
+ }
133
+ // --- Hook Registration ---
134
+ onToolCallStart(callback) {
135
+ this.userHooks.onToolCallStart.push(callback);
136
+ return this;
137
+ }
138
+ onToolCall(callback) {
139
+ return this.onToolCallStart(callback);
140
+ }
141
+ onToolCallEnd(callback) {
142
+ this.userHooks.onToolCallEnd.push(callback);
143
+ return this;
144
+ }
145
+ onToolResult(callback) {
146
+ return this.onToolCallEnd((_call, result) => callback(result));
147
+ }
148
+ /**
149
+ * Registers a handler run when a tool call throws. Return "STOP",
150
+ * "CONTINUE", or "RETRY" to control recovery; the first handler to return
151
+ * a directive wins, but every registered handler still runs.
152
+ */
153
+ onToolCallError(callback) {
154
+ this.userHooks.onToolCallError.push(callback);
155
+ return this;
156
+ }
157
+ /**
158
+ * Registers an approval handler used when toolExecution is "confirm".
159
+ * Every registered handler must approve (return true) for the call to
160
+ * proceed.
161
+ */
162
+ onConfirmToolCall(callback) {
163
+ this.userHooks.onConfirmToolCall.push(callback);
164
+ return this;
165
+ }
166
+ afterResponse(callback) {
167
+ this.userHooks.afterResponse.push(callback);
168
+ return this;
169
+ }
170
+ onBeforeRequest(callback) {
171
+ this.userHooks.onBeforeRequest.push(callback);
172
+ return this;
173
+ }
174
+ onNewMessage(callback) {
175
+ this.userHooks.onNewMessage.push(callback);
176
+ return this;
177
+ }
178
+ onEndMessage(callback) {
179
+ this.userHooks.onEndMessage.push(callback);
180
+ return this;
181
+ }
182
+ }