@appweaver/ai 0.0.0-stage → 2.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/LICENSE +21 -0
- package/README.md +62 -2
- package/config.d.ts +49 -0
- package/config.js +58 -0
- package/driver/ai-driver.d.ts +42 -0
- package/driver/ai-driver.js +31 -0
- package/driver/mock-driver.d.ts +27 -0
- package/driver/mock-driver.js +147 -0
- package/driver/model-registry.d.ts +53 -0
- package/driver/model-registry.js +244 -0
- package/driver/presets.d.ts +23 -0
- package/driver/presets.js +126 -0
- package/index.d.ts +14 -0
- package/index.js +30 -0
- package/module.d.ts +7 -0
- package/module.js +48 -0
- package/package.json +54 -3
- package/service/ai-object-stream.d.ts +35 -0
- package/service/ai-object-stream.js +58 -0
- package/service/ai-service.d.ts +118 -0
- package/service/ai-service.js +769 -0
- package/service/ai-stream.d.ts +48 -0
- package/service/ai-stream.js +133 -0
- package/service/prompt.d.ts +100 -0
- package/service/prompt.js +2 -0
- package/tools/create-tool.d.ts +53 -0
- package/tools/create-tool.js +57 -0
- package/tsconfig.build.tsbuildinfo +1 -0
- package/types.d.ts +201 -0
- package/types.js +2 -0
- package/utils/async-queue.d.ts +13 -0
- package/utils/async-queue.js +59 -0
- package/utils/json-util.d.ts +26 -0
- package/utils/json-util.js +124 -0
- package/utils/stream-util.d.ts +53 -0
- package/utils/stream-util.js +90 -0
- package/utils/telemetry.d.ts +38 -0
- package/utils/telemetry.js +136 -0
- package/utils/vector-util.d.ts +24 -0
- package/utils/vector-util.js +43 -0
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
|
-
|
|
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
|
-
|
|
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
|
+
}
|