@lowdefy/ai-utils 6.1.0 → 7.0.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,217 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */ import { type } from '@lowdefy/helpers';
16
+ // The question shapes a Decide request accepts, and the one place that knows
17
+ // how each shape reads back. A question is exactly one of:
18
+ //
19
+ // choice: <instructions> options: { <name>: <description> | { description, ... }, ... }
20
+ // yesno: <instructions> criteria: { yes: <description>, no: <description> } (optional)
21
+ // score: <instructions> levels: [<lowest>, ..., <highest>]
22
+ //
23
+ // Answers are keyed by question id, so a routine reads
24
+ // `_step: <stepId>.<questionId>.choice`. `usage` is reserved for the call's
25
+ // token usage.
26
+ export const RESERVED_QUESTION_IDS = [
27
+ 'usage'
28
+ ];
29
+ // The fields each answer carries — the build checks `_step` references
30
+ // against these, and the backends shape their answers to them.
31
+ export const ANSWER_FIELDS = {
32
+ choice: [
33
+ 'choice',
34
+ 'confidence',
35
+ 'probabilities'
36
+ ],
37
+ yesno: [
38
+ 'answer',
39
+ 'probability',
40
+ 'confidence'
41
+ ],
42
+ score: [
43
+ 'level',
44
+ 'index',
45
+ 'score',
46
+ 'confidence',
47
+ 'probabilities'
48
+ ]
49
+ };
50
+ export function questionKind(question) {
51
+ if (question?.choice !== undefined) return 'choice';
52
+ if (question?.yesno !== undefined) return 'yesno';
53
+ if (question?.score !== undefined) return 'score';
54
+ return null;
55
+ }
56
+ // An option is its description, or an object carrying one alongside keys Decide
57
+ // ignores (label, icon, ...), so one intents file can feed a Decide request and
58
+ // the block that shows the answer.
59
+ export function optionDescriptions(question) {
60
+ return Object.fromEntries(Object.entries(question.options ?? {}).map(([name, option])=>[
61
+ name,
62
+ type.isObject(option) ? option.description ?? null : option
63
+ ]));
64
+ }
65
+ // The values a branch may compare a field against — the options of a choice,
66
+ // the level names of a score. Used by the build's branch check.
67
+ export function answerValues(question) {
68
+ const kind = questionKind(question);
69
+ if (kind === 'choice') return {
70
+ field: 'choice',
71
+ values: Object.keys(question.options ?? {})
72
+ };
73
+ if (kind === 'score') return {
74
+ field: 'level',
75
+ values: question.levels ?? []
76
+ };
77
+ return null;
78
+ }
79
+ const clamp01 = (value)=>Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : null;
80
+ function maxEntry(probabilities) {
81
+ let best = null;
82
+ for (const [key, value] of Object.entries(probabilities ?? {})){
83
+ if (Number.isFinite(value) && (best === null || value > best[1])) best = [
84
+ key,
85
+ value
86
+ ];
87
+ }
88
+ return best;
89
+ }
90
+ // An answer outside the question's own terms (an option or level the question
91
+ // does not have, a yes/no that is not a boolean, no answer at all) is no
92
+ // answer: every field is null, the confidence included, so a gate such as
93
+ // `_lt: [{ _step: triage.team.confidence }, 0.7]` holds it back as it holds a
94
+ // low-confidence one.
95
+ function unanswered(kind) {
96
+ if (kind === 'choice') return {
97
+ choice: null,
98
+ confidence: null,
99
+ probabilities: null
100
+ };
101
+ if (kind === 'yesno') return {
102
+ answer: null,
103
+ probability: null,
104
+ confidence: null
105
+ };
106
+ return {
107
+ level: null,
108
+ index: null,
109
+ score: null,
110
+ confidence: null,
111
+ probabilities: null
112
+ };
113
+ }
114
+ function isOption({ question, choice }) {
115
+ return typeof choice === 'string' && Object.hasOwn(question.options ?? {}, choice);
116
+ }
117
+ function roundedScore(score) {
118
+ if (!Number.isFinite(score)) return null;
119
+ return Math.round(score);
120
+ }
121
+ // An evaluation model's answer (choice / score / boolean with probabilities)
122
+ // as a Decide answer. `confidence` is the provider's calibrated confidence
123
+ // when it reports one, otherwise the probability of the chosen answer.
124
+ export function fromEvaluationAnswer({ question, answer, providerConfidence }) {
125
+ const kind = questionKind(question);
126
+ const reported = clamp01(providerConfidence);
127
+ if (kind === 'choice') {
128
+ if (!isOption({
129
+ question,
130
+ choice: answer?.choice
131
+ })) return unanswered(kind);
132
+ const probabilities = answer.probabilities ?? null;
133
+ return {
134
+ choice: answer.choice,
135
+ confidence: reported ?? clamp01(probabilities?.[answer.choice]),
136
+ probabilities
137
+ };
138
+ }
139
+ if (kind === 'yesno') {
140
+ const probability = clamp01(answer?.probability);
141
+ if (probability === null) return unanswered(kind);
142
+ return {
143
+ answer: probability >= 0.5,
144
+ probability,
145
+ confidence: reported ?? Math.max(probability, 1 - probability)
146
+ };
147
+ }
148
+ const levels = question.levels ?? [];
149
+ const byIndex = answer?.probabilities ?? null;
150
+ const best = maxEntry(byIndex);
151
+ const index = best ? Number(best[0]) : roundedScore(answer?.score);
152
+ if (index === null || type.isUndefined(levels[index])) return unanswered(kind);
153
+ let bestConfidence = null;
154
+ if (best) bestConfidence = clamp01(best[1]);
155
+ let probabilities = null;
156
+ if (byIndex) {
157
+ probabilities = Object.fromEntries(Object.entries(byIndex).map(([i, p])=>[
158
+ levels[Number(i)] ?? i,
159
+ p
160
+ ]));
161
+ }
162
+ return {
163
+ level: levels[index],
164
+ index,
165
+ score: Number.isFinite(answer?.score) ? answer.score : null,
166
+ confidence: reported ?? bestConfidence,
167
+ probabilities
168
+ };
169
+ }
170
+ // The probability that a yes/no statement holds, from the model's confidence
171
+ // in the answer it gave.
172
+ function yesProbability({ answer, confidence }) {
173
+ if (confidence === null) return null;
174
+ if (answer) return confidence;
175
+ return 1 - confidence;
176
+ }
177
+ // A language model's structured-output answer ({ choice | answer | level,
178
+ // confidence }) as a Decide answer. The confidence is the model's own
179
+ // estimate — not calibrated the way an evaluation model's probabilities are.
180
+ // The SDK parses the output without checking it against the answer schema,
181
+ // so every answer is checked here.
182
+ export function fromStructuredAnswer({ question, answer }) {
183
+ const kind = questionKind(question);
184
+ const confidence = clamp01(answer?.confidence);
185
+ if (kind === 'choice') {
186
+ if (!isOption({
187
+ question,
188
+ choice: answer?.choice
189
+ })) return unanswered(kind);
190
+ return {
191
+ choice: answer.choice,
192
+ confidence,
193
+ probabilities: null
194
+ };
195
+ }
196
+ if (kind === 'yesno') {
197
+ if (!type.isBoolean(answer?.answer)) return unanswered(kind);
198
+ return {
199
+ answer: answer.answer,
200
+ probability: yesProbability({
201
+ answer: answer.answer,
202
+ confidence
203
+ }),
204
+ confidence
205
+ };
206
+ }
207
+ const levels = question.levels ?? [];
208
+ const index = levels.indexOf(answer?.level);
209
+ if (index === -1) return unanswered(kind);
210
+ return {
211
+ level: levels[index],
212
+ index,
213
+ score: index,
214
+ confidence,
215
+ probabilities: null
216
+ };
217
+ }
@@ -0,0 +1,89 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */ import { experimental_evaluate as evaluate } from 'ai';
16
+ import { type } from '@lowdefy/helpers';
17
+ import { fromEvaluationAnswer, optionDescriptions, questionKind } from './decideQuestions.js';
18
+ function toEvaluationQuestion(question) {
19
+ const kind = questionKind(question);
20
+ if (kind === 'choice') {
21
+ return {
22
+ type: 'choice',
23
+ instructions: question.choice,
24
+ criteria: optionDescriptions(question)
25
+ };
26
+ }
27
+ if (kind === 'yesno') {
28
+ return {
29
+ type: 'boolean',
30
+ instructions: question.yesno,
31
+ ...question.criteria ? {
32
+ criteria: {
33
+ true: question.criteria.yes ?? null,
34
+ false: question.criteria.no ?? null
35
+ }
36
+ } : {}
37
+ };
38
+ }
39
+ return {
40
+ type: 'score',
41
+ instructions: question.score,
42
+ criteria: question.levels
43
+ };
44
+ }
45
+ // evaluate takes no timeout, so the timeout becomes part of its abort signal. It takes
46
+ // no maxOutputTokens either: an evaluation model returns probabilities, not text.
47
+ function toEvaluateOptions({ abortSignal, maxOutputTokens, timeout, ...options }) {
48
+ const signals = [
49
+ abortSignal
50
+ ];
51
+ if (!type.isNone(timeout)) {
52
+ signals.push(AbortSignal.timeout(timeout));
53
+ }
54
+ const present = signals.filter((signal)=>!type.isNone(signal));
55
+ if (present.length > 0) {
56
+ options.abortSignal = AbortSignal.any(present);
57
+ }
58
+ return options;
59
+ }
60
+ // The evaluation backend: an evaluation model answers every question in one
61
+ // pass, with a probability for each option (ai experimental_evaluate).
62
+ async function decideWithEvaluation({ model, state, questions, options }) {
63
+ const result = await evaluate({
64
+ model,
65
+ state,
66
+ questions: Object.fromEntries(Object.entries(questions).map(([id, question])=>[
67
+ id,
68
+ toEvaluationQuestion(question)
69
+ ])),
70
+ ...toEvaluateOptions(options)
71
+ });
72
+ // TypeSafe reports a calibrated confidence per question alongside the
73
+ // probabilities; other evaluation providers may not.
74
+ const confidence = Object.values(result.providerMetadata ?? {}).find((metadata)=>metadata && typeof metadata.confidence === 'object')?.confidence;
75
+ const answers = {};
76
+ for (const [id, question] of Object.entries(questions)){
77
+ answers[id] = fromEvaluationAnswer({
78
+ question,
79
+ answer: result.answers?.[id],
80
+ providerConfidence: confidence?.[id]
81
+ });
82
+ }
83
+ return {
84
+ answers,
85
+ usage: result.usage,
86
+ providerMetadata: result.providerMetadata
87
+ };
88
+ }
89
+ export default decideWithEvaluation;
@@ -0,0 +1,125 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */ import { generateText, jsonSchema, Output } from 'ai';
16
+ import { fromStructuredAnswer, optionDescriptions, questionKind } from './decideQuestions.js';
17
+ const INSTRUCTIONS = [
18
+ 'You make typed decisions about the STATE below. Answer every question from the state alone.',
19
+ 'For each answer also give "confidence": the probability, from 0 to 1, that the answer is right.',
20
+ 'Be calibrated — 0.9 should be right nine times in ten. When the state does not settle a question, say so with a low confidence rather than guessing high.'
21
+ ].join('\n');
22
+ const confidence = {
23
+ type: 'number',
24
+ description: 'Probability from 0 to 1 that the answer is right.'
25
+ };
26
+ function answerSchema(question) {
27
+ const kind = questionKind(question);
28
+ const value = kind === 'choice' ? {
29
+ choice: {
30
+ type: 'string',
31
+ enum: Object.keys(question.options)
32
+ }
33
+ } : kind === 'yesno' ? {
34
+ answer: {
35
+ type: 'boolean'
36
+ }
37
+ } : {
38
+ level: {
39
+ type: 'string',
40
+ enum: question.levels
41
+ }
42
+ };
43
+ return {
44
+ type: 'object',
45
+ properties: {
46
+ ...value,
47
+ confidence
48
+ },
49
+ required: [
50
+ ...Object.keys(value),
51
+ 'confidence'
52
+ ],
53
+ additionalProperties: false
54
+ };
55
+ }
56
+ function describeQuestion(id, question) {
57
+ const kind = questionKind(question);
58
+ if (kind === 'choice') {
59
+ const options = Object.entries(optionDescriptions(question)).map(([name, description])=>` - ${name}${description ? `: ${description}` : ''}`);
60
+ return [
61
+ `- ${id} (pick one option): ${question.choice}`,
62
+ ...options
63
+ ].join('\n');
64
+ }
65
+ if (kind === 'yesno') {
66
+ const criteria = question.criteria ? [
67
+ question.criteria.yes ? ` - yes: ${question.criteria.yes}` : null,
68
+ question.criteria.no ? ` - no: ${question.criteria.no}` : null
69
+ ].filter(Boolean) : [];
70
+ return [
71
+ `- ${id} (true or false): ${question.yesno}`,
72
+ ...criteria
73
+ ].join('\n');
74
+ }
75
+ const levels = question.levels.map((level, index)=>` ${index}. ${level}`);
76
+ return [
77
+ `- ${id} (pick one level, lowest first): ${question.score}`,
78
+ ...levels
79
+ ].join('\n');
80
+ }
81
+ // The structured-output backend: a language model returns every answer as one
82
+ // schema-checked object — the stand-in wherever no evaluation model is
83
+ // available, on any AI connection.
84
+ async function decideWithStructuredOutput({ model, state, questions, options }) {
85
+ const entries = Object.entries(questions);
86
+ const schema = {
87
+ type: 'object',
88
+ properties: Object.fromEntries(entries.map(([id, question])=>[
89
+ id,
90
+ answerSchema(question)
91
+ ])),
92
+ required: entries.map(([id])=>id),
93
+ additionalProperties: false
94
+ };
95
+ const stateText = typeof state === 'string' ? state : JSON.stringify(state, null, 2);
96
+ const result = await generateText({
97
+ model,
98
+ instructions: INSTRUCTIONS,
99
+ prompt: [
100
+ '## STATE',
101
+ stateText,
102
+ '',
103
+ '## QUESTIONS',
104
+ ...entries.map(([id, question])=>describeQuestion(id, question))
105
+ ].join('\n'),
106
+ output: Output.object({
107
+ schema: jsonSchema(schema),
108
+ name: 'decisions'
109
+ }),
110
+ ...options
111
+ });
112
+ const answers = {};
113
+ for (const [id, question] of entries){
114
+ answers[id] = fromStructuredAnswer({
115
+ question,
116
+ answer: result.output?.[id]
117
+ });
118
+ }
119
+ return {
120
+ answers,
121
+ usage: result.usage,
122
+ providerMetadata: result.providerMetadata
123
+ };
124
+ }
125
+ export default decideWithStructuredOutput;
@@ -0,0 +1,160 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */ import createConnectPublic from '@lowdefy/node-utils/createConnectPublic.js';
16
+ import { Agent, fetch } from 'undici';
17
+ import createFileDownloadError from './createFileDownloadError.js';
18
+ const DEFAULT_MAX_BYTES = 20 * 1024 * 1024;
19
+ const DEFAULT_TIMEOUT = 30000;
20
+ const REDIRECT_STATUSES = new Set([
21
+ 301,
22
+ 302,
23
+ 303,
24
+ 307,
25
+ 308
26
+ ]);
27
+ const MAX_REDIRECTS = 10;
28
+ const dispatcher = new Agent({
29
+ connect: createConnectPublic({
30
+ createNotPublicError: (hostname)=>createFileDownloadError({
31
+ code: 'url_not_public',
32
+ message: `File link to ${hostname} leads to an address that is not public.`
33
+ })
34
+ })
35
+ });
36
+ function parseHttps(link) {
37
+ const parsed = URL.parse(link);
38
+ return parsed?.protocol === 'https:' ? parsed : null;
39
+ }
40
+ async function fetchOnce({ link, signal }) {
41
+ try {
42
+ return await fetch(link.href, {
43
+ dispatcher,
44
+ redirect: 'manual',
45
+ signal
46
+ });
47
+ } catch (error) {
48
+ if (signal.aborted) throw error;
49
+ if (error.cause?.code === 'url_not_public') throw error.cause;
50
+ throw createFileDownloadError({
51
+ code: 'fetch_failed',
52
+ message: `Could not download a file from ${link.hostname}: ${error.cause?.message ?? error.message}`,
53
+ cause: error
54
+ });
55
+ }
56
+ }
57
+ // Follows redirects by hand, so each link is checked to be https: before it is requested. The
58
+ // dispatcher checks each link's address as it connects.
59
+ async function fetchFile({ link, signal }) {
60
+ let current = link;
61
+ for(let redirects = 0; redirects <= MAX_REDIRECTS; redirects += 1){
62
+ const response = await fetchOnce({
63
+ link: current,
64
+ signal
65
+ });
66
+ const location = response.headers.get('location');
67
+ if (!REDIRECT_STATUSES.has(response.status) || location === null) {
68
+ return response;
69
+ }
70
+ await response.body?.cancel();
71
+ const next = parseHttps(URL.parse(location, current.href)?.href ?? '');
72
+ if (next === null) {
73
+ throw createFileDownloadError({
74
+ code: 'url_not_https',
75
+ message: `File link to ${current.hostname} redirected to a link that is not https:.`
76
+ });
77
+ }
78
+ current = next;
79
+ }
80
+ throw createFileDownloadError({
81
+ code: 'fetch_failed',
82
+ message: `File link to ${link.hostname} redirected more than ${MAX_REDIRECTS} times.`
83
+ });
84
+ }
85
+ async function readBody({ response, maxBytes, hostname }) {
86
+ const tooLarge = ()=>createFileDownloadError({
87
+ code: 'too_large',
88
+ message: `File from ${hostname} is larger than fileDownload.maxBytes (${maxBytes} bytes).`
89
+ });
90
+ const declaredLength = response.headers.get('content-length');
91
+ if (declaredLength !== null && Number(declaredLength) > maxBytes) {
92
+ await response.body?.cancel();
93
+ throw tooLarge();
94
+ }
95
+ const chunks = [];
96
+ let size = 0;
97
+ // Leaving the loop by a throw cancels the body, so nothing past maxBytes is read.
98
+ for await (const chunk of response.body ?? []){
99
+ size += chunk.byteLength;
100
+ if (size > maxBytes) {
101
+ throw tooLarge();
102
+ }
103
+ chunks.push(chunk);
104
+ }
105
+ return new Uint8Array(Buffer.concat(chunks, size));
106
+ }
107
+ // The AI SDK download function (experimental_download) for file links the model does not take as
108
+ // links, used by agents and by GenerateText and GenerateObject requests: an https: link to a
109
+ // public address, read within maxBytes and timeout. A link the model takes is left to the
110
+ // provider (null).
111
+ function createFileDownload({ maxBytes = DEFAULT_MAX_BYTES, timeout = DEFAULT_TIMEOUT, signal }) {
112
+ async function download(url) {
113
+ const link = parseHttps(url.toString());
114
+ if (link === null) {
115
+ throw createFileDownloadError({
116
+ code: 'url_not_https',
117
+ message: 'File links the server downloads must be https: links.'
118
+ });
119
+ }
120
+ const timeoutSignal = AbortSignal.timeout(timeout);
121
+ const fetchSignal = signal ? AbortSignal.any([
122
+ signal,
123
+ timeoutSignal
124
+ ]) : timeoutSignal;
125
+ try {
126
+ const response = await fetchFile({
127
+ link,
128
+ signal: fetchSignal
129
+ });
130
+ if (!response.ok) {
131
+ await response.body?.cancel();
132
+ throw createFileDownloadError({
133
+ code: 'fetch_failed',
134
+ message: `File link to ${link.hostname} answered ${response.status}.`,
135
+ status: response.status
136
+ });
137
+ }
138
+ const data = await readBody({
139
+ response,
140
+ maxBytes,
141
+ hostname: link.hostname
142
+ });
143
+ return {
144
+ data,
145
+ mediaType: response.headers.get('content-type') ?? undefined
146
+ };
147
+ } catch (error) {
148
+ if (timeoutSignal.aborted) {
149
+ throw createFileDownloadError({
150
+ code: 'timeout',
151
+ message: `File from ${link.hostname} did not download within fileDownload.timeout (${timeout} ms).`,
152
+ cause: error
153
+ });
154
+ }
155
+ throw error;
156
+ }
157
+ }
158
+ return (requestedDownloads)=>Promise.all(requestedDownloads.map(({ url, isUrlSupportedByModel })=>isUrlSupportedByModel ? null : download(url)));
159
+ }
160
+ export default createFileDownload;
@@ -0,0 +1,28 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */ // A refused or failed file download. `code` names the reason; `status` is the HTTP status
16
+ // the link answered with, when there was one. The message names the host, never the link: a file
17
+ // link is usually signed, and this error reaches the server log.
18
+ function createFileDownloadError({ code, message, status, cause }) {
19
+ const error = new Error(message, {
20
+ cause
21
+ });
22
+ error.code = code;
23
+ if (status !== undefined) {
24
+ error.status = status;
25
+ }
26
+ return error;
27
+ }
28
+ export default createFileDownloadError;