@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,13 @@
1
+ /**
2
+ * A queue of values read as an async iterable, filled by a producer pushing them, i.e. the parts of a queued stream
3
+ * arriving through the pub/sub. It ends once ended, or throws the error it failed with after its values are read.
4
+ */
5
+ export declare class AsyncQueue<T> implements AsyncIterable<T> {
6
+ /** Adds a value, ignored once the queue ended. */
7
+ push(value: T): void;
8
+ /** Ends the queue once its values are read. */
9
+ end(): void;
10
+ /** Ends the queue with an error, thrown once its values are read. */
11
+ fail(error: unknown): void;
12
+ [Symbol.asyncIterator](): AsyncIterator<T>;
13
+ }
@@ -0,0 +1,59 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.AsyncQueue = void 0;
4
+ /**
5
+ * A queue of values read as an async iterable, filled by a producer pushing them, i.e. the parts of a queued stream
6
+ * arriving through the pub/sub. It ends once ended, or throws the error it failed with after its values are read.
7
+ */
8
+ class AsyncQueue {
9
+ /** @internal */
10
+ _values = [];
11
+ /** @internal */
12
+ _waiting;
13
+ /** @internal */
14
+ _ended = false;
15
+ /** @internal */
16
+ _error;
17
+ /** Adds a value, ignored once the queue ended. */
18
+ push(value) {
19
+ if (!this._ended) {
20
+ this._values.push(value);
21
+ this.wake();
22
+ }
23
+ }
24
+ /** Ends the queue once its values are read. */
25
+ end() {
26
+ this._ended = true;
27
+ this.wake();
28
+ }
29
+ /** Ends the queue with an error, thrown once its values are read. */
30
+ fail(error) {
31
+ if (!this._ended) {
32
+ this._error = { error };
33
+ this.end();
34
+ }
35
+ }
36
+ async *[Symbol.asyncIterator]() {
37
+ while (true) {
38
+ if (this._values.length) {
39
+ yield this._values.shift();
40
+ }
41
+ else if (this._ended) {
42
+ if (this._error) {
43
+ throw this._error.error;
44
+ }
45
+ return;
46
+ }
47
+ else {
48
+ await new Promise((resolve) => (this._waiting = resolve));
49
+ }
50
+ }
51
+ }
52
+ /** @internal */
53
+ wake() {
54
+ const waiting = this._waiting;
55
+ this._waiting = undefined;
56
+ waiting?.();
57
+ }
58
+ }
59
+ exports.AsyncQueue = AsyncQueue;
@@ -0,0 +1,26 @@
1
+ import { TSchema } from '@sinclair/typebox';
2
+ /**
3
+ * Parses the JSON of a model output: the whole text, or the first object or array in it, i.e. inside a Markdown code
4
+ * block.
5
+ *
6
+ * @param {string} text - The output of the model.
7
+ * @return {unknown} The parsed value.
8
+ * @throws {SyntaxError} When the text holds no valid JSON.
9
+ */
10
+ export declare function parseJsonOutput(text: string): unknown;
11
+ /**
12
+ * Parses an incomplete JSON object or array, i.e. the output of a model while it streams, closing its open strings,
13
+ * arrays and objects. A value cut in the middle of a key, a number or a literal is left out.
14
+ *
15
+ * @param {string} text - The JSON received so far.
16
+ * @return {unknown} The value parsed so far, `undefined` before an object or an array starts.
17
+ */
18
+ export declare function parsePartialJson(text: string): unknown;
19
+ /**
20
+ * Lists the errors of a value against a schema, each with its path.
21
+ *
22
+ * @param {TSchema} schema - The schema.
23
+ * @param {unknown} value - The value.
24
+ * @return {string[]} The first ten errors, empty for a valid value.
25
+ */
26
+ export declare function schemaErrors(schema: TSchema, value: unknown): string[];
@@ -0,0 +1,124 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.parseJsonOutput = parseJsonOutput;
4
+ exports.parsePartialJson = parsePartialJson;
5
+ exports.schemaErrors = schemaErrors;
6
+ const value_1 = require("@sinclair/typebox/value");
7
+ /** The characters a partial JSON is trimmed by at most, looking for a prefix that completes into a valid value. */
8
+ const MAX_TRIM = 64;
9
+ /**
10
+ * Parses the JSON of a model output: the whole text, or the first object or array in it, i.e. inside a Markdown code
11
+ * block.
12
+ *
13
+ * @param {string} text - The output of the model.
14
+ * @return {unknown} The parsed value.
15
+ * @throws {SyntaxError} When the text holds no valid JSON.
16
+ */
17
+ function parseJsonOutput(text) {
18
+ const trimmed = text.trim();
19
+ try {
20
+ return JSON.parse(trimmed);
21
+ }
22
+ catch (error) {
23
+ const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(trimmed)?.[1];
24
+ if (fenced !== undefined) {
25
+ return JSON.parse(fenced.trim());
26
+ }
27
+ const start = trimmed.search(/[{[]/);
28
+ const end = Math.max(trimmed.lastIndexOf('}'), trimmed.lastIndexOf(']'));
29
+ if (start >= 0 && end > start) {
30
+ return JSON.parse(trimmed.slice(start, end + 1));
31
+ }
32
+ throw error;
33
+ }
34
+ }
35
+ /**
36
+ * Parses an incomplete JSON object or array, i.e. the output of a model while it streams, closing its open strings,
37
+ * arrays and objects. A value cut in the middle of a key, a number or a literal is left out.
38
+ *
39
+ * @param {string} text - The JSON received so far.
40
+ * @return {unknown} The value parsed so far, `undefined` before an object or an array starts.
41
+ */
42
+ function parsePartialJson(text) {
43
+ const start = text.search(/[{[]/);
44
+ if (start < 0) {
45
+ return undefined;
46
+ }
47
+ const source = text.slice(start);
48
+ const shortest = Math.max(1, source.length - MAX_TRIM);
49
+ for (let end = source.length; end >= shortest; end--) {
50
+ const completed = completeJson(source.slice(0, end));
51
+ if (completed === undefined) {
52
+ continue;
53
+ }
54
+ try {
55
+ return JSON.parse(completed);
56
+ }
57
+ catch {
58
+ // A shorter prefix may complete into a valid value
59
+ }
60
+ }
61
+ return undefined;
62
+ }
63
+ /**
64
+ * Lists the errors of a value against a schema, each with its path.
65
+ *
66
+ * @param {TSchema} schema - The schema.
67
+ * @param {unknown} value - The value.
68
+ * @return {string[]} The first ten errors, empty for a valid value.
69
+ */
70
+ function schemaErrors(schema, value) {
71
+ const errors = [];
72
+ for (const error of value_1.Value.Errors(schema, value)) {
73
+ errors.push(`${error.path || '/'}: ${error.message}`);
74
+ if (errors.length === 10) {
75
+ break;
76
+ }
77
+ }
78
+ return errors;
79
+ }
80
+ /** Closes the open strings, arrays and objects of a JSON prefix, `undefined` for one ending where no value can. */
81
+ function completeJson(prefix) {
82
+ const closers = [];
83
+ let inString = false;
84
+ let escaped = false;
85
+ for (const char of prefix) {
86
+ if (inString) {
87
+ if (escaped) {
88
+ escaped = false;
89
+ }
90
+ else if (char === '\\') {
91
+ escaped = true;
92
+ }
93
+ else if (char === '"') {
94
+ inString = false;
95
+ }
96
+ }
97
+ else if (char === '"') {
98
+ inString = true;
99
+ }
100
+ else if (char === '{') {
101
+ closers.push('}');
102
+ }
103
+ else if (char === '[') {
104
+ closers.push(']');
105
+ }
106
+ else if (char === '}' || char === ']') {
107
+ closers.pop();
108
+ }
109
+ }
110
+ let completed = prefix;
111
+ if (inString) {
112
+ if (escaped) {
113
+ completed = completed.slice(0, -1);
114
+ }
115
+ completed += '"';
116
+ }
117
+ else {
118
+ completed = completed.trimEnd();
119
+ if (/[,:]$/.test(completed)) {
120
+ return undefined;
121
+ }
122
+ }
123
+ return completed + closers.reverse().join('');
124
+ }
@@ -0,0 +1,53 @@
1
+ import { Readable } from 'node:stream';
2
+ import { AiStream } from '../service/ai-stream';
3
+ import { AiStreamPart } from '../types';
4
+ /**
5
+ * The writer of a stream the text of a model is piped into, i.e. a `StreamWriter` of `createStream` of
6
+ * `@appweaver/realtime`.
7
+ */
8
+ export type AiStreamWriter = {
9
+ /** Writes a text delta */
10
+ write(chunk: string): void;
11
+ /** Ends the stream with a result */
12
+ end(result?: unknown): void;
13
+ /** Ends the stream with an error */
14
+ error(error: unknown): void;
15
+ /** Aborted once the stream is cancelled: the model call is aborted */
16
+ readonly signal?: AbortSignal;
17
+ /** Resolves once the subscribers can take more chunks */
18
+ readonly ready?: Promise<void>;
19
+ };
20
+ /**
21
+ * Pipes the text of a model into a stream writer, i.e. the answer of an LLM shown to every subscriber of a realtime
22
+ * stream, aborting the model call once the stream is cancelled. The stream ends with the finish reason and the tokens,
23
+ * or with the error of the call.
24
+ *
25
+ * @example
26
+ * const writer = roomAnswer.open(String(roomId));
27
+ * await pipeAiStream(ai.stream({ model: 'fast', prompt: question }), writer);
28
+ *
29
+ * @param {AiStream} stream - The stream of the model.
30
+ * @param {AiStreamWriter} writer - The writer.
31
+ * @return {Promise<boolean>} `true` once the stream ended, `false` when it failed.
32
+ */
33
+ export declare function pipeAiStream(stream: AiStream, writer: AiStreamWriter): Promise<boolean>;
34
+ /**
35
+ * Encodes the parts of a model stream as Server-Sent Events, each an event named by the type of its part with the part
36
+ * as its JSON data, and an `error` event with the code and the message of a failure.
37
+ *
38
+ * @param {AiStream | AsyncIterable<AiStreamPart>} stream - The stream, or its parts.
39
+ * @return {AsyncGenerator<string>} The events.
40
+ */
41
+ export declare function toServerSentEvents(stream: AiStream | AsyncIterable<AiStreamPart>): AsyncGenerator<string>;
42
+ /**
43
+ * Creates the body of an HTTP response streaming a model as Server-Sent Events, sent by a route with the
44
+ * `text/event-stream` content type. The model call is aborted when the client disconnects.
45
+ *
46
+ * @example
47
+ * reply.header('content-type', 'text/event-stream');
48
+ * return reply.send(aiEventStream(ai.stream({ prompt: request.body.question })));
49
+ *
50
+ * @param {AiStream} stream - The stream of the model.
51
+ * @return {Readable} The body of the response.
52
+ */
53
+ export declare function aiEventStream(stream: AiStream): Readable;
@@ -0,0 +1,90 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.pipeAiStream = pipeAiStream;
4
+ exports.toServerSentEvents = toServerSentEvents;
5
+ exports.aiEventStream = aiEventStream;
6
+ const node_stream_1 = require("node:stream");
7
+ const common_1 = require("@appweaver/common");
8
+ const ai_stream_1 = require("../service/ai-stream");
9
+ /**
10
+ * Pipes the text of a model into a stream writer, i.e. the answer of an LLM shown to every subscriber of a realtime
11
+ * stream, aborting the model call once the stream is cancelled. The stream ends with the finish reason and the tokens,
12
+ * or with the error of the call.
13
+ *
14
+ * @example
15
+ * const writer = roomAnswer.open(String(roomId));
16
+ * await pipeAiStream(ai.stream({ model: 'fast', prompt: question }), writer);
17
+ *
18
+ * @param {AiStream} stream - The stream of the model.
19
+ * @param {AiStreamWriter} writer - The writer.
20
+ * @return {Promise<boolean>} `true` once the stream ended, `false` when it failed.
21
+ */
22
+ async function pipeAiStream(stream, writer) {
23
+ const abort = () => stream.abort(writer.signal?.reason);
24
+ writer.signal?.addEventListener('abort', abort, { once: true });
25
+ try {
26
+ for await (const text of stream) {
27
+ await writer.ready;
28
+ writer.write(text);
29
+ }
30
+ const { finishReason, usage } = await stream.result;
31
+ writer.end({ finishReason, usage });
32
+ return true;
33
+ }
34
+ catch (error) {
35
+ writer.error(error);
36
+ return false;
37
+ }
38
+ finally {
39
+ writer.signal?.removeEventListener('abort', abort);
40
+ }
41
+ }
42
+ /**
43
+ * Encodes the parts of a model stream as Server-Sent Events, each an event named by the type of its part with the part
44
+ * as its JSON data, and an `error` event with the code and the message of a failure.
45
+ *
46
+ * @param {AiStream | AsyncIterable<AiStreamPart>} stream - The stream, or its parts.
47
+ * @return {AsyncGenerator<string>} The events.
48
+ */
49
+ async function* toServerSentEvents(stream) {
50
+ const parts = stream instanceof ai_stream_1.AiStream ? stream.parts() : stream;
51
+ try {
52
+ for await (const part of parts) {
53
+ yield `event: ${part.type}\ndata: ${JSON.stringify(part)}\n\n`;
54
+ }
55
+ }
56
+ catch (error) {
57
+ yield `event: error\ndata: ${JSON.stringify(streamError(error))}\n\n`;
58
+ }
59
+ }
60
+ /**
61
+ * Creates the body of an HTTP response streaming a model as Server-Sent Events, sent by a route with the
62
+ * `text/event-stream` content type. The model call is aborted when the client disconnects.
63
+ *
64
+ * @example
65
+ * reply.header('content-type', 'text/event-stream');
66
+ * return reply.send(aiEventStream(ai.stream({ prompt: request.body.question })));
67
+ *
68
+ * @param {AiStream} stream - The stream of the model.
69
+ * @return {Readable} The body of the response.
70
+ */
71
+ function aiEventStream(stream) {
72
+ let finished = false;
73
+ const body = node_stream_1.Readable.from((async function* () {
74
+ yield* toServerSentEvents(stream);
75
+ finished = true;
76
+ })());
77
+ body.once('close', () => {
78
+ if (!finished) {
79
+ stream.abort();
80
+ }
81
+ });
82
+ return body;
83
+ }
84
+ /** The code and the message of the error of a stream, sent to its client. */
85
+ function streamError(error) {
86
+ return {
87
+ code: (0, common_1.isAppweaverError)(error) ? error.code : 'INTERNAL_ERROR',
88
+ message: error?.message ?? String(error)
89
+ };
90
+ }
@@ -0,0 +1,38 @@
1
+ import { Span, TraceContext } from '@appweaver/common';
2
+ import { AiEndpoint } from '../driver/ai-driver';
3
+ import { AiModelRequest, AiModelResponse, AiToolCall, AiUsage } from '../types';
4
+ /** The operation of a model call, as the semantic conventions of generative AI name it. */
5
+ export type AiOperation = 'chat' | 'embeddings';
6
+ /** A model call being traced, ended with its response or its error. */
7
+ export type AiCallTrace = {
8
+ /** The span of the call, undefined while the `ai` instrumentation is off */
9
+ span?: Span;
10
+ /** The context holding the span */
11
+ context?: TraceContext;
12
+ /** Runs a function in the context of the span, so the spans it starts (the HTTP request) are its children. */
13
+ run<T>(fn: () => T): T;
14
+ /** Ends the span and records the metrics of the response. */
15
+ end(response?: Pick<AiModelResponse, 'id' | 'model' | 'finishReason'> & {
16
+ usage?: Partial<AiUsage>;
17
+ }): void;
18
+ /** Ends the span with an error. */
19
+ fail(error: unknown): void;
20
+ };
21
+ /**
22
+ * Starts the span of a model call (`chat qwen3:8b`), with the attributes of the semantic conventions of generative
23
+ * AI, and records its duration and tokens once it ends.
24
+ *
25
+ * @param {AiOperation} operation - The operation.
26
+ * @param {AiEndpoint} endpoint - The endpoint called.
27
+ * @param {Partial<AiModelRequest>} request - The model and the parameters of the request.
28
+ * @return {AiCallTrace} The trace of the call.
29
+ */
30
+ export declare function traceAiCall(operation: AiOperation, endpoint: AiEndpoint, request: Pick<AiModelRequest, 'model'> & Partial<AiModelRequest>): AiCallTrace;
31
+ /**
32
+ * Runs a tool in the span of its execution (`execute_tool getWeather`).
33
+ *
34
+ * @param {AiToolCall} toolCall - The call of the model.
35
+ * @param {Function} fn - Runs the tool.
36
+ * @return {Promise} The result of the tool.
37
+ */
38
+ export declare function traceToolCall<T>(toolCall: AiToolCall, fn: () => Promise<T>): Promise<T>;
@@ -0,0 +1,136 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.traceAiCall = traceAiCall;
4
+ exports.traceToolCall = traceToolCall;
5
+ const common_1 = require("@appweaver/common");
6
+ const tokenUsage = (0, common_1.telemetryHistogram)('gen_ai.client.token.usage', {
7
+ description: 'The tokens of the AI model calls, by their type',
8
+ unit: '{token}',
9
+ advice: {
10
+ explicitBucketBoundaries: [
11
+ 1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576
12
+ ]
13
+ }
14
+ });
15
+ const operationDuration = (0, common_1.telemetryHistogram)('gen_ai.client.operation.duration', {
16
+ description: 'The duration of the AI model calls',
17
+ unit: 's',
18
+ advice: { explicitBucketBoundaries: common_1.DURATION_BUCKETS }
19
+ });
20
+ /**
21
+ * Starts the span of a model call (`chat qwen3:8b`), with the attributes of the semantic conventions of generative
22
+ * AI, and records its duration and tokens once it ends.
23
+ *
24
+ * @param {AiOperation} operation - The operation.
25
+ * @param {AiEndpoint} endpoint - The endpoint called.
26
+ * @param {Partial<AiModelRequest>} request - The model and the parameters of the request.
27
+ * @return {AiCallTrace} The trace of the call.
28
+ */
29
+ function traceAiCall(operation, endpoint, request) {
30
+ if (!(0, common_1.telemetryEnabled)('ai')) {
31
+ return { run: (fn) => fn(), end: () => { }, fail: () => { } };
32
+ }
33
+ const started = performance.now();
34
+ const attributes = {
35
+ 'gen_ai.operation.name': operation,
36
+ 'gen_ai.provider.name': endpoint.preset ?? endpoint.driver,
37
+ 'gen_ai.request.model': request.model,
38
+ 'appweaver.ai.endpoint': endpoint.name,
39
+ ...serverAttributes(endpoint.baseUrl),
40
+ ...definedAttributes({
41
+ 'gen_ai.request.max_tokens': request.maxTokens,
42
+ 'gen_ai.request.temperature': request.temperature,
43
+ 'gen_ai.request.top_p': request.topP,
44
+ 'gen_ai.request.seed': request.seed
45
+ })
46
+ };
47
+ const { span, context } = (0, common_1.startSpan)(`${operation} ${request.model}`, {
48
+ kind: common_1.SpanKind.CLIENT,
49
+ attributes
50
+ });
51
+ const metricAttributes = {
52
+ 'gen_ai.operation.name': operation,
53
+ 'gen_ai.provider.name': attributes['gen_ai.provider.name'],
54
+ 'gen_ai.request.model': request.model
55
+ };
56
+ return {
57
+ span,
58
+ context,
59
+ run: (fn) => (0, common_1.runInTraceContext)(context, fn),
60
+ end: (response) => {
61
+ const responseModel = response?.model ?? request.model;
62
+ span.setAttributes(definedAttributes({
63
+ 'gen_ai.response.id': response?.id,
64
+ 'gen_ai.response.model': responseModel,
65
+ 'gen_ai.response.finish_reasons': response?.finishReason
66
+ ? [response.finishReason]
67
+ : undefined,
68
+ 'gen_ai.usage.input_tokens': response?.usage?.inputTokens,
69
+ 'gen_ai.usage.output_tokens': response?.usage?.outputTokens
70
+ }));
71
+ span.end();
72
+ const measured = {
73
+ ...metricAttributes,
74
+ 'gen_ai.response.model': responseModel
75
+ };
76
+ (0, common_1.recordDuration)(operationDuration(), started, measured);
77
+ for (const [type, tokens] of [
78
+ ['input', response?.usage?.inputTokens],
79
+ ['output', response?.usage?.outputTokens]
80
+ ]) {
81
+ if (tokens !== undefined) {
82
+ tokenUsage().record(tokens, {
83
+ ...measured,
84
+ 'gen_ai.token.type': type
85
+ });
86
+ }
87
+ }
88
+ },
89
+ fail: (error) => {
90
+ (0, common_1.failSpan)(span, error);
91
+ span.end();
92
+ (0, common_1.recordDuration)(operationDuration(), started, {
93
+ ...metricAttributes,
94
+ 'error.type': (0, common_1.spanErrorType)(error)
95
+ });
96
+ }
97
+ };
98
+ }
99
+ /**
100
+ * Runs a tool in the span of its execution (`execute_tool getWeather`).
101
+ *
102
+ * @param {AiToolCall} toolCall - The call of the model.
103
+ * @param {Function} fn - Runs the tool.
104
+ * @return {Promise} The result of the tool.
105
+ */
106
+ function traceToolCall(toolCall, fn) {
107
+ if (!(0, common_1.telemetryEnabled)('ai')) {
108
+ return fn();
109
+ }
110
+ return (0, common_1.withSpan)(`execute_tool ${toolCall.name}`, {
111
+ kind: common_1.SpanKind.INTERNAL,
112
+ attributes: {
113
+ 'gen_ai.operation.name': 'execute_tool',
114
+ 'gen_ai.tool.name': toolCall.name,
115
+ 'gen_ai.tool.call.id': toolCall.id
116
+ }
117
+ }, fn);
118
+ }
119
+ function serverAttributes(baseUrl) {
120
+ if (!baseUrl) {
121
+ return {};
122
+ }
123
+ try {
124
+ const url = new URL(baseUrl);
125
+ return {
126
+ 'server.address': url.hostname,
127
+ ...(url.port ? { 'server.port': Number(url.port) } : {})
128
+ };
129
+ }
130
+ catch {
131
+ return {};
132
+ }
133
+ }
134
+ function definedAttributes(attributes) {
135
+ return Object.fromEntries(Object.entries(attributes).filter(([, value]) => value !== undefined));
136
+ }
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Returns the cosine similarity of two vectors, i.e. of the embeddings of two texts: `1` for the same direction, `0`
3
+ * for unrelated ones.
4
+ *
5
+ * @param {number[]} a - The first vector.
6
+ * @param {number[]} b - The second vector, of the same length.
7
+ * @return {number} The similarity, from `-1` to `1`, `0` for a zero vector.
8
+ * @throws {RangeError} For vectors of different lengths.
9
+ */
10
+ export declare function cosineSimilarity(a: number[], b: number[]): number;
11
+ /**
12
+ * Ranks items by the similarity of their vectors to a query vector, i.e. the documents closest to the embedding of a
13
+ * question.
14
+ *
15
+ * @param {number[]} query - The query vector.
16
+ * @param {T[]} items - The items.
17
+ * @param {Function} vector - Returns the vector of an item.
18
+ * @param {number} [limit] - The number of items to return. Default: all of them.
19
+ * @return {{ item: T; score: number }[]} The items with their similarity, the most similar first.
20
+ */
21
+ export declare function rankBySimilarity<T>(query: number[], items: T[], vector: (item: T) => number[], limit?: number): {
22
+ item: T;
23
+ score: number;
24
+ }[];
@@ -0,0 +1,43 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.cosineSimilarity = cosineSimilarity;
4
+ exports.rankBySimilarity = rankBySimilarity;
5
+ /**
6
+ * Returns the cosine similarity of two vectors, i.e. of the embeddings of two texts: `1` for the same direction, `0`
7
+ * for unrelated ones.
8
+ *
9
+ * @param {number[]} a - The first vector.
10
+ * @param {number[]} b - The second vector, of the same length.
11
+ * @return {number} The similarity, from `-1` to `1`, `0` for a zero vector.
12
+ * @throws {RangeError} For vectors of different lengths.
13
+ */
14
+ function cosineSimilarity(a, b) {
15
+ if (a.length !== b.length) {
16
+ throw new RangeError(`The vectors have different lengths, ${a.length} and ${b.length}`);
17
+ }
18
+ let dot = 0;
19
+ let normA = 0;
20
+ let normB = 0;
21
+ for (let i = 0; i < a.length; i++) {
22
+ dot += a[i] * b[i];
23
+ normA += a[i] * a[i];
24
+ normB += b[i] * b[i];
25
+ }
26
+ return normA && normB ? dot / Math.sqrt(normA * normB) : 0;
27
+ }
28
+ /**
29
+ * Ranks items by the similarity of their vectors to a query vector, i.e. the documents closest to the embedding of a
30
+ * question.
31
+ *
32
+ * @param {number[]} query - The query vector.
33
+ * @param {T[]} items - The items.
34
+ * @param {Function} vector - Returns the vector of an item.
35
+ * @param {number} [limit] - The number of items to return. Default: all of them.
36
+ * @return {{ item: T; score: number }[]} The items with their similarity, the most similar first.
37
+ */
38
+ function rankBySimilarity(query, items, vector, limit = items.length) {
39
+ return items
40
+ .map((item) => ({ item, score: cosineSimilarity(query, vector(item)) }))
41
+ .sort((a, b) => b.score - a.score)
42
+ .slice(0, limit);
43
+ }