@appweaver/ai 0.0.0-stage → 2.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Luka Matosevic
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
@@ -1,3 +1,63 @@
1
- # Temporary Holding Version
1
+ <p align="center">
2
+ <a href="https://appweaver.co" target="_blank"><img src="https://raw.githubusercontent.com/lmatosevic/appweaver/refs/heads/main/resources/appweaver-logo.svg" width="460" alt="Appweaver Logo" /></a>
3
+ </p>
2
4
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
5
+ <p align="center">
6
+ The AI module of Appweaver, the AI-first <a href="https://nodejs.org" target="_blank">Node.js</a> framework for backends built with agents.
7
+ </p>
8
+
9
+ <p align="center">
10
+ <a href="https://www.npmjs.com/package/@appweaver/ai" target="_blank"><img src="https://img.shields.io/npm/v/@appweaver/ai.svg" alt="NPM Version" /></a>
11
+ <a href="https://github.com/lmatosevic/appweaver/blob/main/LICENSE" target="_blank"><img src="https://img.shields.io/npm/l/@appweaver/ai.svg" alt="Package License" /></a>
12
+ <a href="https://www.npmjs.com/package/@appweaver/ai" target="_blank"><img src="https://img.shields.io/npm/dw/@appweaver/ai.svg" alt="NPM Downloads" /></a>
13
+ <a href="https://github.com/lmatosevic/appweaver/actions/workflows/ci.yml?query=branch%3Amain" target="_blank"><img src="https://img.shields.io/github/actions/workflow/status/lmatosevic/appweaver/ci.yml?branch=main&label=CI" alt="CI Status" /></a>
14
+ <a href="https://codecov.io/gh/lmatosevic/appweaver" target="_blank"><img src="https://codecov.io/gh/lmatosevic/appweaver/graph/badge.svg" alt="Test Coverage" /></a>
15
+ <a href="https://nodejs.org" target="_blank"><img src="https://img.shields.io/node/v/@appweaver/ai.svg" alt="Node Version" /></a>
16
+ </p>
17
+
18
+ ## Description
19
+
20
+ `@appweaver/ai` is the AI module of [Appweaver](https://github.com/lmatosevic/appweaver), enabled by installing it.
21
+ `AiService` calls the models (LLMs) of the endpoints of the `ai` config: a whole response, a stream, an object matching
22
+ a TypeBox schema, a classification or embeddings, directly or through the `ai` queue, running the tools the model calls
23
+ (`createAiTool`). The models are named by references (`local:qwen3:8b`) or by aliases (`fast`, `smart`), so every
24
+ environment picks its own: a local Ollama while developing, the built-in `mock` model in the tests, OpenRouter or OpenAI
25
+ in production. The drivers are modules of their own, every installed one usable at once: `@appweaver/openai` reaches
26
+ OpenAI and every OpenAI-compatible server.
27
+
28
+ ## Installation
29
+
30
+ ```sh
31
+ npm install @appweaver/ai @appweaver/openai
32
+ ```
33
+
34
+ or `weaver module add ai` in a project created with `@appweaver/create`.
35
+
36
+ ```json
37
+ {
38
+ "config": {
39
+ "ai": {
40
+ "endpoints": { "local": { "preset": "ollama" } },
41
+ "defaultModel": "local:qwen3:8b",
42
+ "aliases": { "fast": "local:qwen3:8b" }
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ ```ts
49
+ const ai = inject(AiService);
50
+ const { text } = await ai.generate({ model: 'fast', prompt: 'Summarize: ...' });
51
+ for await (const delta of ai.stream({ prompt: question }))
52
+ process.stdout.write(delta);
53
+ ```
54
+
55
+ ## Documentation
56
+
57
+ - [Appweaver README](https://github.com/lmatosevic/appweaver#readme) – getting started, configuration, and the overview of every package
58
+ - [AI reference](https://github.com/lmatosevic/appweaver/blob/main/skill/references/ai.md) – the endpoints, the presets, `AiService`, the tools and the drivers
59
+ - [Agent skill](https://github.com/lmatosevic/appweaver/blob/main/skill/SKILL.md) – the complete framework reference shipped to every scaffolded project
60
+
61
+ ## License
62
+
63
+ Appweaver is [MIT licensed](LICENSE).
package/config.d.ts ADDED
@@ -0,0 +1,49 @@
1
+ /** An endpoint of the `ai.endpoints` config: a server speaking the API of a driver. */
2
+ export declare const aiEndpointSchema: import("@sinclair/typebox").TObject<{
3
+ /** The preset of the driver, the base URL, the API key variable and the capabilities, i.e. `ollama`. */
4
+ preset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
5
+ /** The driver talking to the endpoint. Default: the driver of the preset, otherwise `openai`. */
6
+ driver: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
7
+ /** The base URL of the API, i.e. `http://localhost:11434/v1`. Default: the one of the preset. */
8
+ baseUrl: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
9
+ /** The API key. Default: the environment variable of the preset, i.e. `OPENROUTER_API_KEY`. */
10
+ apiKey: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
11
+ /** Headers sent with every request, as `Name: value` strings. */
12
+ headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
13
+ /** The capabilities of its models (`tools`, `json`, `json-schema`, `images`, `files`, `reasoning`, `embeddings`).
14
+ * Default: the ones of the preset. */
15
+ capabilities: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
16
+ /** The timeout of a request in milliseconds. Default: `ai.timeout`. */
17
+ timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
18
+ /** The retries of a failed request. Default: `ai.maxRetries`. */
19
+ maxRetries: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
20
+ }>;
21
+ export declare const aiConfig: Readonly<{
22
+ DEFAULT_MODEL?: string | undefined;
23
+ DEFAULT_EMBEDDING_MODEL?: string | undefined;
24
+ MAX_TOKENS?: number | undefined;
25
+ TEMPERATURE?: number | undefined;
26
+ ENDPOINTS: {
27
+ [x: string]: {
28
+ preset?: string | undefined;
29
+ driver?: string | undefined;
30
+ baseUrl?: string | undefined;
31
+ apiKey?: string | undefined;
32
+ headers?: string[] | undefined;
33
+ capabilities?: string[] | undefined;
34
+ timeout?: number | undefined;
35
+ maxRetries?: number | undefined;
36
+ };
37
+ };
38
+ ALIASES: {
39
+ [x: string]: string | string[];
40
+ };
41
+ TIMEOUT: number;
42
+ MAX_RETRIES: number;
43
+ MAX_STEPS: number;
44
+ REPAIR_ATTEMPTS: number;
45
+ LOG_PROMPTS: boolean;
46
+ HEALTH_CHECK_ENDPOINTS: string[];
47
+ QUEUE_CONCURRENCY: number;
48
+ STREAM_FLUSH_INTERVAL: number;
49
+ }>;
package/config.js ADDED
@@ -0,0 +1,58 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.aiConfig = exports.aiEndpointSchema = void 0;
4
+ const typebox_1 = require("@sinclair/typebox");
5
+ const common_1 = require("@appweaver/common");
6
+ /** An endpoint of the `ai.endpoints` config: a server speaking the API of a driver. */
7
+ exports.aiEndpointSchema = typebox_1.Type.Object({
8
+ /** The preset of the driver, the base URL, the API key variable and the capabilities, i.e. `ollama`. */
9
+ preset: typebox_1.Type.Optional(typebox_1.Type.String()),
10
+ /** The driver talking to the endpoint. Default: the driver of the preset, otherwise `openai`. */
11
+ driver: typebox_1.Type.Optional(typebox_1.Type.String()),
12
+ /** The base URL of the API, i.e. `http://localhost:11434/v1`. Default: the one of the preset. */
13
+ baseUrl: typebox_1.Type.Optional(typebox_1.Type.String()),
14
+ /** The API key. Default: the environment variable of the preset, i.e. `OPENROUTER_API_KEY`. */
15
+ apiKey: typebox_1.Type.Optional(typebox_1.Type.String({ secret: true })),
16
+ /** Headers sent with every request, as `Name: value` strings. */
17
+ headers: typebox_1.Type.Optional(typebox_1.Type.Array(typebox_1.Type.String())),
18
+ /** The capabilities of its models (`tools`, `json`, `json-schema`, `images`, `files`, `reasoning`, `embeddings`).
19
+ * Default: the ones of the preset. */
20
+ capabilities: typebox_1.Type.Optional(typebox_1.Type.Array(typebox_1.Type.String())),
21
+ /** The timeout of a request in milliseconds. Default: `ai.timeout`. */
22
+ timeout: typebox_1.Type.Optional(typebox_1.Type.Integer()),
23
+ /** The retries of a failed request. Default: `ai.maxRetries`. */
24
+ maxRetries: typebox_1.Type.Optional(typebox_1.Type.Integer())
25
+ });
26
+ exports.aiConfig = (0, common_1.defineConfig)('ai', {
27
+ /** The endpoints by name, the prefix of the model references (`local:qwen3:8b`), i.e.
28
+ * `{ "local": { "preset": "ollama" } }`, each property also a variable (`AI_ENDPOINTS_LOCAL_BASE_URL`). The `mock`
29
+ * endpoint is built in. Default: `{}`. */
30
+ ENDPOINTS: typebox_1.Type.Record(typebox_1.Type.String(), exports.aiEndpointSchema, { default: {} }),
31
+ /** The model of a call naming none, a model reference (`<endpoint>:<model>`) or an alias, i.e. `local:qwen3:8b`. */
32
+ DEFAULT_MODEL: typebox_1.Type.Optional(typebox_1.Type.String()),
33
+ /** The embedding model of a call naming none, a model reference or an alias, i.e. `local:nomic-embed-text`. */
34
+ DEFAULT_EMBEDDING_MODEL: typebox_1.Type.Optional(typebox_1.Type.String()),
35
+ /** Names the code calls the models by, i.e. `{ "fast": "local:qwen3:8b" }`, each a model reference or a list of
36
+ * them tried in turn on a retriable error (comma-separated in a variable). Default: `{}`. */
37
+ ALIASES: typebox_1.Type.Record(typebox_1.Type.String(), typebox_1.Type.Union([typebox_1.Type.String(), typebox_1.Type.Array(typebox_1.Type.String())]), { default: {} }),
38
+ /** The maximum output tokens of a call setting none. Default: the one of the model. */
39
+ MAX_TOKENS: typebox_1.Type.Optional(typebox_1.Type.Integer()),
40
+ /** The temperature of a call setting none. Default: the one of the model. */
41
+ TEMPERATURE: typebox_1.Type.Optional(typebox_1.Type.Number()),
42
+ /** The timeout of a request to a model in milliseconds. Default: `120000`. */
43
+ TIMEOUT: typebox_1.Type.Integer({ default: 120000 }),
44
+ /** The retries of a request failing with a rate limit, a timeout or a server error. Default: `2`. */
45
+ MAX_RETRIES: typebox_1.Type.Integer({ default: 2 }),
46
+ /** The maximum model calls of a call running tools. Default: `5`. */
47
+ MAX_STEPS: typebox_1.Type.Integer({ default: 5 }),
48
+ /** The calls repairing an object not matching its schema. Default: `1`. */
49
+ REPAIR_ATTEMPTS: typebox_1.Type.Integer({ default: 1 }),
50
+ /** Log the prompts and the responses at the debug level. Default: `false`. */
51
+ LOG_PROMPTS: typebox_1.Type.Boolean({ default: false }),
52
+ /** The endpoints the health check of the AI service checks, by listing their models. Default: `[]`. */
53
+ HEALTH_CHECK_ENDPOINTS: typebox_1.Type.Array(typebox_1.Type.String(), { default: [] }),
54
+ /** The jobs of the `ai` queue a worker runs at once. Default: `4`. */
55
+ QUEUE_CONCURRENCY: typebox_1.Type.Integer({ default: 4 }),
56
+ /** The milliseconds the parts of a queued stream are batched for before they are published. Default: `50`. */
57
+ STREAM_FLUSH_INTERVAL: typebox_1.Type.Integer({ default: 50 })
58
+ });
@@ -0,0 +1,42 @@
1
+ import { HealthCheckResult } from '@appweaver/common';
2
+ import { AiCallOptions, AiCapability, AiEmbedRequest, AiEmbedResponse, AiModelRequest, AiModelResponse, AiStreamPart } from '../types';
3
+ /** An endpoint of the `ai.endpoints` config, completed with its preset and the `ai` defaults. */
4
+ export type AiEndpoint = {
5
+ /** The name of the endpoint, the prefix of its model references */
6
+ name: string;
7
+ driver: string;
8
+ capabilities: AiCapability[];
9
+ headers: Record<string, string>;
10
+ timeout: number;
11
+ maxRetries: number;
12
+ /** The driver options of the preset */
13
+ options: Record<string, unknown>;
14
+ preset?: string;
15
+ baseUrl?: string;
16
+ apiKey?: string;
17
+ };
18
+ /** The class of a driver, created once per endpoint using it. */
19
+ export type AiDriverClass = new (endpoint: AiEndpoint) => AiDriver;
20
+ /**
21
+ * The driver of the endpoints speaking one API, provided by a module as an `AiDriver` provider named by the driver
22
+ * name, i.e. `openai` of `@appweaver/openai`. It throws an `AiError` (`AI_RATE_LIMITED`, `AI_TIMEOUT` and
23
+ * `AI_PROVIDER_UNAVAILABLE` for the errors another model may not have), and the reason of an aborted signal as it is.
24
+ */
25
+ export declare abstract class AiDriver {
26
+ readonly endpoint: AiEndpoint;
27
+ constructor(endpoint: AiEndpoint);
28
+ /** Sends a request and returns the whole response. */
29
+ abstract generate(request: AiModelRequest, options?: AiCallOptions): Promise<AiModelResponse>;
30
+ /** Sends a request and streams the response, the tool calls whole, ending with a `finish` part. */
31
+ abstract stream(request: AiModelRequest, options?: AiCallOptions): AsyncIterable<AiStreamPart>;
32
+ /** Checks that the endpoint answers, i.e. by listing its models. */
33
+ abstract checkHealth(): Promise<HealthCheckResult>;
34
+ /**
35
+ * Embeds texts into vectors, which a driver of an API without embeddings leaves to this default.
36
+ *
37
+ * @throws {AiError} `AI_CAPABILITY_UNSUPPORTED`.
38
+ */
39
+ embed(request: AiEmbedRequest, options?: AiCallOptions): Promise<AiEmbedResponse>;
40
+ /** Tells whether the models of the endpoint have a capability, from the endpoint or its preset. */
41
+ supports(capability: AiCapability, model: string): boolean;
42
+ }
@@ -0,0 +1,31 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.AiDriver = void 0;
4
+ const common_1 = require("@appweaver/common");
5
+ /**
6
+ * The driver of the endpoints speaking one API, provided by a module as an `AiDriver` provider named by the driver
7
+ * name, i.e. `openai` of `@appweaver/openai`. It throws an `AiError` (`AI_RATE_LIMITED`, `AI_TIMEOUT` and
8
+ * `AI_PROVIDER_UNAVAILABLE` for the errors another model may not have), and the reason of an aborted signal as it is.
9
+ */
10
+ class AiDriver {
11
+ endpoint;
12
+ constructor(endpoint) {
13
+ this.endpoint = endpoint;
14
+ }
15
+ /**
16
+ * Embeds texts into vectors, which a driver of an API without embeddings leaves to this default.
17
+ *
18
+ * @throws {AiError} `AI_CAPABILITY_UNSUPPORTED`.
19
+ */
20
+ async embed(request, options) {
21
+ throw new common_1.AiError(common_1.ErrorCode.AiCapabilityUnsupported, `The '${this.endpoint.driver}' driver of the '${this.endpoint.name}' endpoint has no embeddings`, {
22
+ model: `${this.endpoint.name}:${request.model}`,
23
+ capability: 'embeddings'
24
+ });
25
+ }
26
+ /** Tells whether the models of the endpoint have a capability, from the endpoint or its preset. */
27
+ supports(capability, model) {
28
+ return this.endpoint.capabilities.includes(capability);
29
+ }
30
+ }
31
+ exports.AiDriver = AiDriver;
@@ -0,0 +1,27 @@
1
+ import { HealthCheckResult } from '@appweaver/common';
2
+ import { AiEmbedRequest, AiEmbedResponse, AiModelRequest, AiModelResponse, AiStreamPart } from '../types';
3
+ import { AiDriver } from './ai-driver';
4
+ /** Answers the requests of the mock models in a test, with a text or a part of the response. */
5
+ export type MockAiHandler = (request: AiModelRequest) => string | Partial<AiModelResponse> | Promise<string | Partial<AiModelResponse>>;
6
+ /**
7
+ * Sets the answers of the `mock` endpoint, i.e. in a test asserting what the application does with a response, or
8
+ * removes them with `undefined`, back to the built-in models.
9
+ *
10
+ * @example
11
+ * mockAiResponse((request) => (request.tools ? { toolCalls: [...] } : 'Paris'));
12
+ *
13
+ * @param {MockAiHandler | undefined} handler - Answers the requests, or `undefined` to remove it.
14
+ */
15
+ export declare function mockAiResponse(handler: MockAiHandler | undefined): void;
16
+ /**
17
+ * The built-in `mock` endpoint, calling no server, for the tests and the development without a model. Its `echo`
18
+ * model (any model name) answers with the text of the last user message, its `tools` model calls every tool once
19
+ * before it answers, and a request of a JSON schema is answered with the default value of the schema. Its embeddings
20
+ * are vectors derived from the texts, the same for the same text.
21
+ */
22
+ export declare class MockAiDriver extends AiDriver {
23
+ generate(request: AiModelRequest): Promise<AiModelResponse>;
24
+ stream(request: AiModelRequest): AsyncIterable<AiStreamPart>;
25
+ embed(request: AiEmbedRequest): Promise<AiEmbedResponse>;
26
+ checkHealth(): Promise<HealthCheckResult>;
27
+ }
@@ -0,0 +1,147 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.MockAiDriver = void 0;
4
+ exports.mockAiResponse = mockAiResponse;
5
+ const value_1 = require("@sinclair/typebox/value");
6
+ const ai_driver_1 = require("./ai-driver");
7
+ const MOCK_HANDLER = Symbol.for('appweaver.MockAiHandler');
8
+ const handlers = globalThis;
9
+ /**
10
+ * Sets the answers of the `mock` endpoint, i.e. in a test asserting what the application does with a response, or
11
+ * removes them with `undefined`, back to the built-in models.
12
+ *
13
+ * @example
14
+ * mockAiResponse((request) => (request.tools ? { toolCalls: [...] } : 'Paris'));
15
+ *
16
+ * @param {MockAiHandler | undefined} handler - Answers the requests, or `undefined` to remove it.
17
+ */
18
+ function mockAiResponse(handler) {
19
+ handlers[MOCK_HANDLER] = handler;
20
+ }
21
+ /**
22
+ * The built-in `mock` endpoint, calling no server, for the tests and the development without a model. Its `echo`
23
+ * model (any model name) answers with the text of the last user message, its `tools` model calls every tool once
24
+ * before it answers, and a request of a JSON schema is answered with the default value of the schema. Its embeddings
25
+ * are vectors derived from the texts, the same for the same text.
26
+ */
27
+ class MockAiDriver extends ai_driver_1.AiDriver {
28
+ async generate(request) {
29
+ const handler = handlers[MOCK_HANDLER];
30
+ const answer = handler ? await handler(request) : this.answer(request);
31
+ const response = typeof answer === 'string' ? { text: answer } : answer;
32
+ const text = response.text ?? '';
33
+ const toolCalls = response.toolCalls ?? [];
34
+ const inputTokens = countTokens(request.messages);
35
+ const outputTokens = text.split(/\s+/).filter(Boolean).length;
36
+ return {
37
+ id: 'mock',
38
+ model: request.model,
39
+ finishReason: toolCalls.length ? 'tool-calls' : 'stop',
40
+ usage: {
41
+ inputTokens,
42
+ outputTokens,
43
+ totalTokens: inputTokens + outputTokens
44
+ },
45
+ ...response,
46
+ text,
47
+ toolCalls
48
+ };
49
+ }
50
+ async *stream(request) {
51
+ const response = await this.generate(request);
52
+ if (response.reasoning) {
53
+ yield { type: 'reasoning-delta', text: response.reasoning };
54
+ }
55
+ for (const chunk of response.text.match(/\S+\s*|\s+/g) ?? []) {
56
+ yield { type: 'text-delta', text: chunk };
57
+ }
58
+ for (const toolCall of response.toolCalls) {
59
+ yield { type: 'tool-call', toolCall };
60
+ }
61
+ yield {
62
+ type: 'finish',
63
+ finishReason: response.finishReason,
64
+ usage: response.usage,
65
+ id: response.id,
66
+ model: response.model
67
+ };
68
+ }
69
+ async embed(request) {
70
+ const dimensions = request.dimensions ?? 8;
71
+ return {
72
+ model: request.model,
73
+ embeddings: request.input.map((text) => embedText(text, dimensions)),
74
+ usage: { inputTokens: request.input.join(' ').split(/\s+/).length }
75
+ };
76
+ }
77
+ async checkHealth() {
78
+ return { success: true };
79
+ }
80
+ /** @internal */
81
+ answer(request) {
82
+ const format = request.responseFormat;
83
+ if (format?.type === 'json-schema') {
84
+ return { text: JSON.stringify(createValue(format.schema)) };
85
+ }
86
+ if (format?.type === 'json') {
87
+ return { text: '{}' };
88
+ }
89
+ const last = request.messages[request.messages.length - 1];
90
+ if (request.model === 'tools' &&
91
+ request.tools?.length &&
92
+ request.toolChoice !== 'none' &&
93
+ last?.role !== 'tool') {
94
+ return {
95
+ toolCalls: request.tools.map((tool, i) => ({
96
+ id: `call_${i + 1}`,
97
+ name: tool.name,
98
+ arguments: createValue(tool.parameters)
99
+ }))
100
+ };
101
+ }
102
+ return { text: lastUserText(request.messages) };
103
+ }
104
+ }
105
+ exports.MockAiDriver = MockAiDriver;
106
+ /** The text of the last user message, or of the results of the tools after it. */
107
+ function lastUserText(messages) {
108
+ for (let i = messages.length - 1; i >= 0; i--) {
109
+ const message = messages[i];
110
+ if (message.role === 'tool') {
111
+ return message.content
112
+ .map((part) => typeof part.result === 'string'
113
+ ? part.result
114
+ : JSON.stringify(part.result))
115
+ .join('\n');
116
+ }
117
+ if (message.role === 'user') {
118
+ return typeof message.content === 'string'
119
+ ? message.content
120
+ : message.content
121
+ .map((part) => (part.type === 'text' ? part.text : ''))
122
+ .join('');
123
+ }
124
+ }
125
+ return '';
126
+ }
127
+ /** The default value of a schema, or an empty object for one TypeBox cannot create. */
128
+ function createValue(schema) {
129
+ try {
130
+ return value_1.Value.Create(schema);
131
+ }
132
+ catch {
133
+ return {};
134
+ }
135
+ }
136
+ function countTokens(messages) {
137
+ return JSON.stringify(messages).split(/\s+/).length;
138
+ }
139
+ /** A unit vector derived from the characters of a text, the same for the same text. */
140
+ function embedText(text, dimensions) {
141
+ const vector = new Array(dimensions).fill(0);
142
+ for (let i = 0; i < text.length; i++) {
143
+ vector[i % dimensions] += text.charCodeAt(i) * ((i % 7) + 1);
144
+ }
145
+ const norm = Math.sqrt(vector.reduce((sum, value) => sum + value * value, 0));
146
+ return norm ? vector.map((value) => value / norm) : vector;
147
+ }
@@ -0,0 +1,53 @@
1
+ import { AiDriver, AiDriverClass, AiEndpoint } from './ai-driver';
2
+ /** A model reference resolved to its endpoint. */
3
+ export type ResolvedModel = {
4
+ /** The model reference, i.e. `local:qwen3:8b` */
5
+ reference: string;
6
+ /** The name of the endpoint, i.e. `local` */
7
+ endpoint: string;
8
+ /** The model name on the endpoint, i.e. `qwen3:8b` */
9
+ model: string;
10
+ };
11
+ /**
12
+ * Registers a driver class under a name without a module providing it, i.e. a stub in a test. It takes precedence
13
+ * over the driver of a module with the same name.
14
+ *
15
+ * @param {string} name - The name of the driver.
16
+ * @param {AiDriverClass | undefined} driver - The driver class, or `undefined` to remove it.
17
+ */
18
+ export declare function registerAiDriver(name: string, driver: AiDriverClass | undefined): void;
19
+ /** Resolves the model references and the aliases to their endpoints, and creates each endpoint's driver once. */
20
+ export declare class ModelRegistry {
21
+ /**
22
+ * Resolves a model reference or an alias into the models to call in turn, the default model when none is given.
23
+ *
24
+ * @param {string} [model] - A model reference (`local:qwen3:8b`), an alias (`fast`), or none.
25
+ * @param {string} [fallback] - The default reference or alias, i.e. `ai.defaultModel`.
26
+ * @return {ResolvedModel[]} The models, more than one for an alias listing fallbacks.
27
+ * @throws {AiError} `AI_MODEL_UNKNOWN` for an unknown alias or endpoint, or no model at all.
28
+ */
29
+ resolve(model: string | undefined, fallback?: string | undefined): ResolvedModel[];
30
+ /**
31
+ * Returns the endpoint of a name, completed with the defaults of its preset and the `ai` config.
32
+ *
33
+ * @param {string} name - The name of the endpoint.
34
+ * @return {AiEndpoint} The endpoint.
35
+ * @throws {AiError} `AI_MODEL_UNKNOWN` for an endpoint that is not configured.
36
+ */
37
+ endpoint(name: string): AiEndpoint;
38
+ /**
39
+ * Returns the driver of an endpoint, created on its first call.
40
+ *
41
+ * @param {string} name - The name of the endpoint.
42
+ * @return {Promise<AiDriver>} The driver.
43
+ * @throws {ConfigurationError} `CONFIGURATION_INVALID` when no enabled module provides its driver, or the endpoint
44
+ * requires an API key it has not.
45
+ */
46
+ driver(name: string): Promise<AiDriver>;
47
+ /**
48
+ * Checks that the default models and every alias name configured endpoints.
49
+ *
50
+ * @return {string[]} The errors, empty when the config is valid.
51
+ */
52
+ validate(): string[];
53
+ }