@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.
@@ -0,0 +1,48 @@
1
+ import { AiStreamPart } from '../types';
2
+ import { AiResult } from './prompt';
3
+ /** Produces the parts of a stream, returning the result once it ends. */
4
+ export type AiStreamSource<R> = (signal: AbortSignal) => AsyncGenerator<AiStreamPart, R>;
5
+ /**
6
+ * A streamed response of a model: an async iterable of the text deltas, i.e. returned by the handler of a streaming
7
+ * realtime action or piped into an HTTP response, with the result once it ends. The stream is read once, by iterating
8
+ * it, {@link parts} or {@link text}; awaiting only the {@link result} reads it in the background.
9
+ *
10
+ * @example
11
+ * const stream = ai.stream({ model: 'fast', prompt: 'Tell a story' });
12
+ * for await (const text of stream) {
13
+ * process.stdout.write(text);
14
+ * }
15
+ * const { usage } = await stream.result;
16
+ */
17
+ export declare class AiStream<R = AiResult> implements AsyncIterable<string> {
18
+ private readonly source;
19
+ /**
20
+ * @param {AiStreamSource} source - Produces the parts, aborted with the stream.
21
+ * @param {AbortSignal} [signal] - Aborts the stream.
22
+ */
23
+ constructor(source: AiStreamSource<R>, signal?: AbortSignal);
24
+ /** The result once the stream ends, read in the background when the stream is not read otherwise. */
25
+ get result(): Promise<R>;
26
+ /** Aborted once the stream is aborted. */
27
+ get signal(): AbortSignal;
28
+ /**
29
+ * Reads the parts of the stream: the text and reasoning deltas, the tool calls and their results, and the finish.
30
+ *
31
+ * @return {AsyncIterable<AiStreamPart>} The parts.
32
+ * @throws {Error} When the stream is already read.
33
+ */
34
+ parts(): AsyncGenerator<AiStreamPart, void>;
35
+ /**
36
+ * Reads the stream to its end.
37
+ *
38
+ * @return {Promise<string>} The whole text.
39
+ */
40
+ text(): Promise<string>;
41
+ /**
42
+ * Aborts the stream, its model call and its tool calls.
43
+ *
44
+ * @param {unknown} [reason] - The reason of the abort, thrown to the reader.
45
+ */
46
+ abort(reason?: unknown): void;
47
+ [Symbol.asyncIterator](): AsyncIterator<string>;
48
+ }
@@ -0,0 +1,133 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.AiStream = void 0;
4
+ /**
5
+ * A streamed response of a model: an async iterable of the text deltas, i.e. returned by the handler of a streaming
6
+ * realtime action or piped into an HTTP response, with the result once it ends. The stream is read once, by iterating
7
+ * it, {@link parts} or {@link text}; awaiting only the {@link result} reads it in the background.
8
+ *
9
+ * @example
10
+ * const stream = ai.stream({ model: 'fast', prompt: 'Tell a story' });
11
+ * for await (const text of stream) {
12
+ * process.stdout.write(text);
13
+ * }
14
+ * const { usage } = await stream.result;
15
+ */
16
+ class AiStream {
17
+ source;
18
+ /** @internal */
19
+ _controller = new AbortController();
20
+ /** @internal */
21
+ _result;
22
+ /** @internal */
23
+ _resolve;
24
+ /** @internal */
25
+ _reject;
26
+ /** @internal */
27
+ _started = false;
28
+ /**
29
+ * @param {AiStreamSource} source - Produces the parts, aborted with the stream.
30
+ * @param {AbortSignal} [signal] - Aborts the stream.
31
+ */
32
+ constructor(source, signal) {
33
+ this.source = source;
34
+ this._result = new Promise((resolve, reject) => {
35
+ this._resolve = resolve;
36
+ this._reject = reject;
37
+ });
38
+ // The error is also thrown to the reader, the result may never be awaited
39
+ this._result.catch(() => { });
40
+ if (signal) {
41
+ if (signal.aborted) {
42
+ this._controller.abort(signal.reason);
43
+ }
44
+ else {
45
+ signal.addEventListener('abort', () => this._controller.abort(signal.reason), { once: true });
46
+ }
47
+ }
48
+ }
49
+ /** The result once the stream ends, read in the background when the stream is not read otherwise. */
50
+ get result() {
51
+ if (!this._started) {
52
+ void this.drain();
53
+ }
54
+ return this._result;
55
+ }
56
+ /** Aborted once the stream is aborted. */
57
+ get signal() {
58
+ return this._controller.signal;
59
+ }
60
+ /**
61
+ * Reads the parts of the stream: the text and reasoning deltas, the tool calls and their results, and the finish.
62
+ *
63
+ * @return {AsyncIterable<AiStreamPart>} The parts.
64
+ * @throws {Error} When the stream is already read.
65
+ */
66
+ async *parts() {
67
+ if (this._started) {
68
+ throw new Error('The AI stream is already read');
69
+ }
70
+ this._started = true;
71
+ const parts = this.source(this._controller.signal);
72
+ try {
73
+ while (true) {
74
+ const next = await parts.next();
75
+ if (next.done) {
76
+ this._resolve(next.value);
77
+ return;
78
+ }
79
+ yield next.value;
80
+ }
81
+ }
82
+ catch (error) {
83
+ this._reject(error);
84
+ throw error;
85
+ }
86
+ finally {
87
+ if (!this._controller.signal.aborted) {
88
+ // A reader stopping early ends the stream
89
+ await parts.return?.(undefined);
90
+ }
91
+ this._reject(new Error('The AI stream was not read to its end'));
92
+ }
93
+ }
94
+ /**
95
+ * Reads the stream to its end.
96
+ *
97
+ * @return {Promise<string>} The whole text.
98
+ */
99
+ async text() {
100
+ let text = '';
101
+ for await (const delta of this) {
102
+ text += delta;
103
+ }
104
+ return text;
105
+ }
106
+ /**
107
+ * Aborts the stream, its model call and its tool calls.
108
+ *
109
+ * @param {unknown} [reason] - The reason of the abort, thrown to the reader.
110
+ */
111
+ abort(reason) {
112
+ this._controller.abort(reason);
113
+ }
114
+ async *[Symbol.asyncIterator]() {
115
+ for await (const part of this.parts()) {
116
+ if (part.type === 'text-delta') {
117
+ yield part.text;
118
+ }
119
+ }
120
+ }
121
+ /** @internal */
122
+ async drain() {
123
+ try {
124
+ for await (const _ of this.parts()) {
125
+ // Read for the result
126
+ }
127
+ }
128
+ catch {
129
+ // Rejected through the result
130
+ }
131
+ }
132
+ }
133
+ exports.AiStream = AiStream;
@@ -0,0 +1,100 @@
1
+ import { Static, TSchema } from '@sinclair/typebox';
2
+ import { AiTool } from '../tools/create-tool';
3
+ import { AiMessage, AiModelResponse, AiReasoningEffort, AiResponseFormat, AiToolChoice, AiToolResultPart, AiUsage, AiUserPart } from '../types';
4
+ /** A prompt rendered from a template of the template engine. */
5
+ export type AiTemplatePrompt = {
6
+ /** The template name, with the `.md` format when it has none, i.e. `prompts/summarize` for `prompts/summarize.md` */
7
+ template: string;
8
+ /** The data to render the template with */
9
+ data?: Record<string, unknown>;
10
+ /** The locale to render the template in. Default: the `locale.default` config */
11
+ locale?: string;
12
+ };
13
+ /** A call of a model: the model, the messages, and the parameters. */
14
+ export type AiPrompt = {
15
+ /** A model reference (`local:qwen3:8b`) or an alias (`fast`). Default: `ai.defaultModel` */
16
+ model?: string;
17
+ /** The system prompt, a text or a template */
18
+ system?: string | AiTemplatePrompt;
19
+ /** The user message added after the `messages`, a text, a template, or its parts (i.e. with images) */
20
+ prompt?: string | AiTemplatePrompt | AiUserPart[];
21
+ /** The conversation so far */
22
+ messages?: AiMessage[];
23
+ /** The maximum output tokens. Default: `ai.maxTokens` */
24
+ maxTokens?: number;
25
+ /** The temperature. Default: `ai.temperature` */
26
+ temperature?: number;
27
+ topP?: number;
28
+ stop?: string[];
29
+ seed?: number;
30
+ /** The reasoning effort of a reasoning model */
31
+ reasoning?: AiReasoningEffort;
32
+ /** The tools the model may call, or the names of the tools of `createAiTool` */
33
+ tools?: (AiTool<any, any> | string)[];
34
+ toolChoice?: AiToolChoice;
35
+ /** The maximum model calls running the tools the model calls. Default: `ai.maxSteps` */
36
+ maxSteps?: number;
37
+ /** The format of the output: text (the default), any JSON object, or JSON matching a schema */
38
+ responseFormat?: AiResponseFormat;
39
+ /** Parameters of the endpoint sent as they are, i.e. the `provider` routing of OpenRouter */
40
+ providerOptions?: Record<string, unknown>;
41
+ /** Aborts the call */
42
+ signal?: AbortSignal;
43
+ /** The timeout of a model request in milliseconds. Default: the one of the endpoint */
44
+ timeout?: number;
45
+ };
46
+ /** A call of a model returning an object matching a schema. */
47
+ export type AiObjectPrompt<T extends TSchema> = Omit<AiPrompt, 'responseFormat'> & {
48
+ /** The schema of the object, a TypeBox schema */
49
+ schema: T;
50
+ /** The name of the schema, sent to the endpoints naming it. Default: `response` */
51
+ schemaName?: string;
52
+ /** The calls repairing an object not matching the schema. Default: `ai.repairAttempts` */
53
+ repairAttempts?: number;
54
+ };
55
+ /** A call of a model run by a worker of the `ai` queue: a JSON value, its tools named. */
56
+ export type AiQueuedPrompt = Omit<AiPrompt, 'signal' | 'tools'> & {
57
+ /** The names of the tools of `createAiTool` */
58
+ tools?: string[];
59
+ };
60
+ /** A model call of a call running tools, and the results of the tools it called. */
61
+ export type AiStep = {
62
+ response: AiModelResponse;
63
+ toolResults: AiToolResultPart[];
64
+ };
65
+ /** The response of a call, after the tools it called. */
66
+ export type AiResult = AiModelResponse & {
67
+ /** The model reference that answered, i.e. the second model of an alias when the first failed */
68
+ model: string;
69
+ /** The model calls, one per step running tools */
70
+ steps: AiStep[];
71
+ /** The conversation with the response, to continue it */
72
+ messages: AiMessage[];
73
+ /** The tokens of every step */
74
+ usage: AiUsage;
75
+ };
76
+ /** The response of a call returning an object. */
77
+ export type AiObjectResult<T extends TSchema> = AiResult & {
78
+ object: Static<T>;
79
+ };
80
+ /** The embeddings of a call. */
81
+ export type AiEmbedResult = {
82
+ /** A vector per text, in their order */
83
+ embeddings: number[][];
84
+ /** The model reference that embedded */
85
+ model: string;
86
+ usage?: {
87
+ inputTokens: number;
88
+ };
89
+ };
90
+ /** The options of an embedding call. */
91
+ export type AiEmbedOptions = {
92
+ /** A model reference or an alias. Default: `ai.defaultEmbeddingModel` */
93
+ model?: string;
94
+ /** The dimensions of the vectors, for a model supporting fewer */
95
+ dimensions?: number;
96
+ /** Parameters of the endpoint sent as they are */
97
+ providerOptions?: Record<string, unknown>;
98
+ signal?: AbortSignal;
99
+ timeout?: number;
100
+ };
@@ -0,0 +1,2 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
@@ -0,0 +1,53 @@
1
+ import { Static, TSchema } from '@sinclair/typebox';
2
+ import { AiMessage, AiToolCall } from '../types';
3
+ /** The key of the tools in the application context. */
4
+ export declare const AI_TOOL: unique symbol;
5
+ /** What the `execute` of a tool receives besides its arguments. */
6
+ export type AiToolContext = {
7
+ /** The call of the model */
8
+ toolCall: AiToolCall;
9
+ /** The messages of the conversation so far */
10
+ messages: AiMessage[];
11
+ /** Aborted with the call of the model */
12
+ signal?: AbortSignal;
13
+ };
14
+ /** A tool the model may call. */
15
+ export type AiTool<P extends TSchema = TSchema, R = unknown> = {
16
+ /** Letters, digits, `_` and `-`, i.e. `getWeather` */
17
+ name: string;
18
+ /** The TypeBox schema of the arguments, validated before `execute` runs */
19
+ parameters: P;
20
+ /** Read by the model to decide when to call the tool */
21
+ description?: string;
22
+ /**
23
+ * Runs the tool, as the user of the call. Its result (or the message of its error) is sent back to the model.
24
+ * Without it, a call of the tool ends the call, returning the tool calls to the caller.
25
+ */
26
+ execute?: (args: Static<P>, context: AiToolContext) => R | Promise<R>;
27
+ };
28
+ /**
29
+ * Creates a tool, registered under its name so a prompt can name it (a queued prompt must).
30
+ *
31
+ * @example
32
+ * export const getWeather = createAiTool({
33
+ * name: 'getWeather',
34
+ * description: 'The current weather of a city',
35
+ * parameters: Type.Object({ city: Type.String() }),
36
+ * execute: async ({ city }) => weather.current(city)
37
+ * });
38
+ *
39
+ * @param {AiTool} tool - The name, the description, the parameters and the function of the tool.
40
+ * @return {AiTool} The tool.
41
+ * @throws {ConfigurationError} `CONFIGURATION_INVALID` for an invalid name, or one already taken.
42
+ */
43
+ export declare function createAiTool<P extends TSchema, R = unknown>(tool: AiTool<P, R>): AiTool<P, R>;
44
+ /** Lists the tools of {@link createAiTool}. */
45
+ export declare function aiTools(): AiTool[];
46
+ /** Finds a tool of {@link createAiTool} by its name. */
47
+ export declare function findAiTool(name: string): AiTool | undefined;
48
+ /**
49
+ * Checks the name of a tool.
50
+ *
51
+ * @throws {ConfigurationError} `CONFIGURATION_INVALID` for a name the APIs refuse.
52
+ */
53
+ export declare function validateToolName(name: string): void;
@@ -0,0 +1,57 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.AI_TOOL = void 0;
4
+ exports.createAiTool = createAiTool;
5
+ exports.aiTools = aiTools;
6
+ exports.findAiTool = findAiTool;
7
+ exports.validateToolName = validateToolName;
8
+ const common_1 = require("@appweaver/common");
9
+ const core_1 = require("@appweaver/core");
10
+ const logger = (0, common_1.createLogger)('ai');
11
+ /** The key of the tools in the application context. */
12
+ exports.AI_TOOL = Symbol.for('appweaver.AiTool');
13
+ /** The names the OpenAI-compatible APIs accept for a tool. */
14
+ const NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
15
+ /**
16
+ * Creates a tool, registered under its name so a prompt can name it (a queued prompt must).
17
+ *
18
+ * @example
19
+ * export const getWeather = createAiTool({
20
+ * name: 'getWeather',
21
+ * description: 'The current weather of a city',
22
+ * parameters: Type.Object({ city: Type.String() }),
23
+ * execute: async ({ city }) => weather.current(city)
24
+ * });
25
+ *
26
+ * @param {AiTool} tool - The name, the description, the parameters and the function of the tool.
27
+ * @return {AiTool} The tool.
28
+ * @throws {ConfigurationError} `CONFIGURATION_INVALID` for an invalid name, or one already taken.
29
+ */
30
+ function createAiTool(tool) {
31
+ validateToolName(tool.name);
32
+ if (findAiTool(tool.name)) {
33
+ throw new common_1.ConfigurationError(common_1.ErrorCode.ConfigurationInvalid, `AI tool '${tool.name}' is already defined`);
34
+ }
35
+ // Wrapped in an object, since the context would instantiate a function
36
+ (0, core_1.define)({ tool }, exports.AI_TOOL, 'append');
37
+ logger.debug({ tool: tool.name }, 'Created AI tool');
38
+ return tool;
39
+ }
40
+ /** Lists the tools of {@link createAiTool}. */
41
+ function aiTools() {
42
+ return (0, core_1.injectAll)(exports.AI_TOOL).map((entry) => entry.tool);
43
+ }
44
+ /** Finds a tool of {@link createAiTool} by its name. */
45
+ function findAiTool(name) {
46
+ return aiTools().find((tool) => tool.name === name);
47
+ }
48
+ /**
49
+ * Checks the name of a tool.
50
+ *
51
+ * @throws {ConfigurationError} `CONFIGURATION_INVALID` for a name the APIs refuse.
52
+ */
53
+ function validateToolName(name) {
54
+ if (!NAME_PATTERN.test(name)) {
55
+ throw new common_1.ConfigurationError(common_1.ErrorCode.ConfigurationInvalid, `Invalid AI tool name '${name}': up to 64 letters, digits, '_' and '-'`);
56
+ }
57
+ }