@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.
@@ -13,9 +13,9 @@
13
13
  See the License for the specific language governing permissions and
14
14
  limitations under the License.
15
15
  */ import { type } from '@lowdefy/helpers';
16
+ import createFileDownload from './fileDownload/createFileDownload.js';
17
+ // maxOutputTokens is a limit with a connection default, so buildCallLimits sets it.
16
18
  const callSettings = [
17
- 'system',
18
- 'maxOutputTokens',
19
19
  'temperature',
20
20
  'topP',
21
21
  'topK',
@@ -26,7 +26,7 @@ const callSettings = [
26
26
  'maxRetries',
27
27
  'providerOptions'
28
28
  ];
29
- function buildGenerateCallOptions({ request }) {
29
+ function buildGenerateCallOptions({ request, signal }) {
30
30
  if (type.isNone(request.prompt) && type.isNone(request.messages)) {
31
31
  throw new Error('Either "prompt" or "messages" must be provided.');
32
32
  }
@@ -39,6 +39,24 @@ function buildGenerateCallOptions({ request }) {
39
39
  }
40
40
  if (!type.isNone(request.messages)) {
41
41
  options.messages = request.messages;
42
+ // A file part the model does not take as a link is downloaded by the server, within
43
+ // fileDownload's limits and only from a public https: address.
44
+ options.experimental_download = createFileDownload({
45
+ ...request.fileDownload,
46
+ signal
47
+ });
48
+ }
49
+ // A system turn instructs the model as the app itself, and `messages` is
50
+ // often built from a user's input (`_payload`, `_state`), so ai v7 rejects
51
+ // one unless the call opts in. The request opts in explicitly.
52
+ if (request.allowSystemInMessages === true) {
53
+ options.allowSystemInMessages = true;
54
+ } else if ((request.messages ?? []).some((message)=>message?.role === 'system')) {
55
+ throw new Error('"messages" includes a system message. Use the "system" property for the system prompt, or set "allowSystemInMessages: true" if the system message comes from the app, never from a user.');
56
+ }
57
+ // `system` is the request's public property; ai v7 calls it `instructions`.
58
+ if (!type.isNone(request.system)) {
59
+ options.instructions = request.system;
42
60
  }
43
61
  callSettings.forEach((setting)=>{
44
62
  if (!type.isNone(request[setting])) {
@@ -0,0 +1,49 @@
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
+ */ // The model gets the prompt as plain text, or, with files, as one user message
16
+ // whose content is the prompt followed by a part per file. URLs stay URLs so
17
+ // the provider fetches them.
18
+ function buildGeneratePrompt({ prompt, files }) {
19
+ if (files.length === 0) {
20
+ return prompt;
21
+ }
22
+ const fileParts = files.map(({ url, mediaType })=>{
23
+ if (mediaType.startsWith('image/')) {
24
+ return {
25
+ type: 'image',
26
+ image: new URL(url),
27
+ mediaType
28
+ };
29
+ }
30
+ return {
31
+ type: 'file',
32
+ data: new URL(url),
33
+ mediaType
34
+ };
35
+ });
36
+ return [
37
+ {
38
+ role: 'user',
39
+ content: [
40
+ {
41
+ type: 'text',
42
+ text: prompt
43
+ },
44
+ ...fileParts
45
+ ]
46
+ }
47
+ ];
48
+ }
49
+ export default buildGeneratePrompt;
@@ -0,0 +1,80 @@
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
+ const COMBINATORS = [
17
+ {
18
+ keyword: 'oneOf',
19
+ quantifier: 'exactly one of',
20
+ joiner: ' or '
21
+ },
22
+ {
23
+ keyword: 'anyOf',
24
+ quantifier: 'at least one of',
25
+ joiner: ' or '
26
+ },
27
+ {
28
+ keyword: 'allOf',
29
+ quantifier: 'all of',
30
+ joiner: ' and '
31
+ }
32
+ ];
33
+ function describeBranch(branch) {
34
+ if (type.isArray(branch?.required) && branch.required.length > 0) {
35
+ return `(${branch.required.join(', ')})`;
36
+ }
37
+ return JSON.stringify(branch);
38
+ }
39
+ // Anthropic (and OpenAI) refuse a tool whose input schema has oneOf, anyOf or allOf at the top
40
+ // level, and fail the whole request. The model gets the schema without them, the constraint as a
41
+ // line at the head of the description, and the properties the branches define. The endpoint still
42
+ // validates the payload against the full payloadSchema, so a payload that breaks the constraint
43
+ // comes back to the model as an error to correct.
44
+ function buildToolInputSchema({ schema, description }) {
45
+ const inputSchema = {
46
+ ...schema
47
+ };
48
+ const constraints = [];
49
+ for (const { keyword, quantifier, joiner } of COMBINATORS){
50
+ const branches = inputSchema[keyword];
51
+ if (type.isUndefined(branches)) continue;
52
+ delete inputSchema[keyword];
53
+ const properties = {
54
+ ...inputSchema.properties ?? {}
55
+ };
56
+ for (const branch of branches){
57
+ for (const [name, property] of Object.entries(branch?.properties ?? {})){
58
+ properties[name] = properties[name] ?? property;
59
+ }
60
+ }
61
+ if (Object.keys(properties).length > 0) {
62
+ inputSchema.properties = properties;
63
+ }
64
+ constraints.push(`Input constraint: Provide parameters for ${quantifier}: ${branches.map(describeBranch).join(joiner)}.`);
65
+ }
66
+ if (constraints.length === 0) {
67
+ return {
68
+ inputSchema,
69
+ description
70
+ };
71
+ }
72
+ return {
73
+ inputSchema,
74
+ description: [
75
+ ...constraints,
76
+ description
77
+ ].filter((line)=>!type.isNone(line)).join('\n\n')
78
+ };
79
+ }
80
+ export default buildToolInputSchema;
@@ -0,0 +1,63 @@
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
+ import buildCallLimits from './buildCallLimits.js';
17
+ import decide from './decide.js';
18
+ import decideSchema from './DecideSchema.js';
19
+ // Builds the Decide request resolver for an AI connection: typed questions
20
+ // about a state in, typed answers with a confidence out
21
+ // (designs/10x #9 — AI decisions as typed config). One interface, two
22
+ // backends; `backends` lists what the connection offers, the first being
23
+ // the default:
24
+ // evaluation provider.evaluationModel(id) — the AI Gateway's
25
+ // evaluation models (TypeSafe's Jev);
26
+ // structured-output provider(id) — any language model.
27
+ function createDecide({ createProvider, backends = [
28
+ 'structured-output'
29
+ ] }) {
30
+ async function Decide({ connection, request, signal }) {
31
+ const provider = createProvider({
32
+ connection
33
+ });
34
+ const backend = request.backend ?? backends[0];
35
+ const options = buildCallLimits({
36
+ connection,
37
+ request,
38
+ signal
39
+ });
40
+ if (!type.isNone(request.maxRetries)) options.maxRetries = request.maxRetries;
41
+ if (!type.isNone(request.providerOptions)) options.providerOptions = request.providerOptions;
42
+ const { answers, usage } = await decide({
43
+ model: backend === 'evaluation' ? provider.evaluationModel(request.model) : provider(request.model),
44
+ backend,
45
+ state: request.state,
46
+ questions: request.questions,
47
+ options
48
+ });
49
+ return {
50
+ ...answers,
51
+ usage
52
+ };
53
+ }
54
+ Decide.schema = decideSchema({
55
+ backends
56
+ });
57
+ Decide.meta = {
58
+ checkRead: false,
59
+ checkWrite: false
60
+ };
61
+ return Decide;
62
+ }
63
+ export default createDecide;
@@ -12,20 +12,27 @@
12
12
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
13
  See the License for the specific language governing permissions and
14
14
  limitations under the License.
15
- */ import handleGenerateObject from './handleGenerateObject.js';
15
+ */ import buildCallLimits from './buildCallLimits.js';
16
+ import handleGenerateObject from './handleGenerateObject.js';
16
17
  import schema from './GenerateObjectSchema.js';
17
18
  // Builds the GenerateObject request resolver for an AI provider connection.
18
19
  // createProvider is the only provider-specific piece — request resolvers
19
20
  // receive evaluated connection properties (not a provider instance) from the
20
21
  // request interface layer, so the resolver constructs the provider itself.
21
22
  function createGenerateObject({ createProvider }) {
22
- async function GenerateObject({ connection, request }) {
23
+ async function GenerateObject({ connection, request, signal }) {
23
24
  const provider = createProvider({
24
25
  connection
25
26
  });
26
27
  return handleGenerateObject({
27
28
  model: provider(request.model),
28
- request
29
+ request,
30
+ limits: buildCallLimits({
31
+ connection,
32
+ request,
33
+ signal
34
+ }),
35
+ signal
29
36
  });
30
37
  }
31
38
  GenerateObject.schema = schema;
@@ -12,20 +12,27 @@
12
12
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
13
  See the License for the specific language governing permissions and
14
14
  limitations under the License.
15
- */ import handleGenerateText from './handleGenerateText.js';
15
+ */ import buildCallLimits from './buildCallLimits.js';
16
+ import handleGenerateText from './handleGenerateText.js';
16
17
  import schema from './GenerateTextSchema.js';
17
18
  // Builds the GenerateText request resolver for an AI provider connection.
18
19
  // createProvider is the only provider-specific piece — request resolvers
19
20
  // receive evaluated connection properties (not a provider instance) from the
20
21
  // request interface layer, so the resolver constructs the provider itself.
21
22
  function createGenerateText({ createProvider }) {
22
- async function GenerateText({ connection, request }) {
23
+ async function GenerateText({ connection, request, signal }) {
23
24
  const provider = createProvider({
24
25
  connection
25
26
  });
26
27
  return handleGenerateText({
27
28
  model: provider(request.model),
28
- request
29
+ request,
30
+ limits: buildCallLimits({
31
+ connection,
32
+ request,
33
+ signal
34
+ }),
35
+ signal
29
36
  });
30
37
  }
31
38
  GenerateText.schema = schema;
@@ -12,10 +12,12 @@
12
12
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
13
  See the License for the specific language governing permissions and
14
14
  limitations under the License.
15
- */ import { ToolLoopAgent, stepCountIs, hasToolCall } from 'ai';
15
+ */ import { ToolLoopAgent, isStepCount, hasToolCall } from 'ai';
16
16
  import buildAgentTools from './buildAgentTools.js';
17
17
  import buildPrepareStep from './buildPrepareStep.js';
18
18
  import buildUpdatePageStateTool from './buildUpdatePageStateTool.js';
19
+ import createFileDownload from './fileDownload/createFileDownload.js';
20
+ import nameAttachedFiles from './nameAttachedFiles.js';
19
21
  // Strip non-serializable fields from agent-level hook events before sending as payload.
20
22
  // messages excluded here — the stream-level onFinish sends UIMessage[] directly.
21
23
  function cleanHookEvent(event) {
@@ -32,14 +34,16 @@ function cleanHookEvent(event) {
32
34
  // onFinish is intentionally excluded — it is handled by the callers (at the stream
33
35
  // level in handleAgentChat, after generate in handleAgentGenerate) so that hooks
34
36
  // are awaited.
37
+ // The YAML names are Lowdefy's public hook API and stay as they are; ai v7
38
+ // dropped the experimental_ prefixes and renamed tool-call/finish callbacks.
35
39
  const hookMapping = {
36
- onStart: 'experimental_onStart',
37
- onStepStart: 'experimental_onStepStart',
38
- onToolCallStart: 'experimental_onToolCallStart',
39
- onToolCallFinish: 'experimental_onToolCallFinish',
40
- onStepFinish: 'onStepFinish'
40
+ onStart: 'onStart',
41
+ onStepStart: 'onStepStart',
42
+ onToolCallStart: 'onToolExecutionStart',
43
+ onToolCallFinish: 'onToolExecutionEnd',
44
+ onStepFinish: 'onStepEnd'
41
45
  };
42
- function createHookCallbacks({ hooks, callEndpoint, locale }) {
46
+ function createHookCallbacks({ callEndpoint, hooks, locale, logger }) {
43
47
  if (!hooks) return {};
44
48
  const callbacks = {};
45
49
  for (const [yamlKey, sdkKey] of Object.entries(hookMapping)){
@@ -53,7 +57,10 @@ function createHookCallbacks({ hooks, callEndpoint, locale }) {
53
57
  for (const endpointId of endpointIds){
54
58
  callEndpoint(endpointId, {
55
59
  payload
56
- }).catch(()=>{});
60
+ }).catch((error)=>logger.warn({
61
+ err: error,
62
+ endpointId
63
+ }, 'Agent hook endpoint failed.'));
57
64
  }
58
65
  };
59
66
  }
@@ -63,24 +70,27 @@ function createHookCallbacks({ hooks, callEndpoint, locale }) {
63
70
  // path: tools, model, hook callbacks, instructions, stop conditions, and the
64
71
  // ToolLoopAgent instance.
65
72
  async function createToolLoopAgent({ connection, agent, context, autoApprove = false }) {
66
- const { tools, mcpClients } = await buildAgentTools({
73
+ const { tools, mcpClients, toolApproval } = await buildAgentTools({
67
74
  agent,
68
75
  context,
69
76
  autoApprove
70
77
  });
71
- const sharedState = context.agentContext?.sharedState;
72
- const updatePageStateTool = buildUpdatePageStateTool({
73
- sharedState
74
- });
75
- if (updatePageStateTool) {
76
- tools['update-page-state'] = updatePageStateTool;
78
+ const { sharedState, sharedStateReadOnly } = context.agentContext ?? {};
79
+ if (!sharedStateReadOnly) {
80
+ const updatePageStateTool = buildUpdatePageStateTool({
81
+ sharedState
82
+ });
83
+ if (updatePageStateTool) {
84
+ tools['update-page-state'] = updatePageStateTool;
85
+ }
77
86
  }
78
87
  const model = connection.provider(agent.properties.model);
79
88
  const locale = context.i18n?.active;
80
89
  const hookCallbacks = createHookCallbacks({
81
- hooks: agent.hooks,
82
90
  callEndpoint: context.callEndpoint,
83
- locale
91
+ hooks: agent.hooks,
92
+ locale,
93
+ logger: context.logger
84
94
  });
85
95
  // Prepend page context to instructions when pageContext is enabled
86
96
  let instructions = agent.properties.instructions;
@@ -95,6 +105,9 @@ async function createToolLoopAgent({ connection, agent, context, autoApprove = f
95
105
  if (ctx.urlQuery && Object.keys(ctx.urlQuery).length > 0) {
96
106
  contextLines.push(` urlQuery: ${JSON.stringify(ctx.urlQuery)}`);
97
107
  }
108
+ if (ctx.pathParams && Object.keys(ctx.pathParams).length > 0) {
109
+ contextLines.push(` pathParams: ${JSON.stringify(ctx.pathParams)}`);
110
+ }
98
111
  if (ctx.sharedState && Object.keys(ctx.sharedState).length > 0) {
99
112
  contextLines.push(` sharedState: ${JSON.stringify(ctx.sharedState)}`);
100
113
  }
@@ -103,7 +116,7 @@ async function createToolLoopAgent({ connection, agent, context, autoApprove = f
103
116
  }
104
117
  // Build stop conditions
105
118
  const stopConditions = [
106
- stepCountIs(agent.properties.maxSteps ?? 10)
119
+ isStepCount(agent.properties.maxSteps ?? 10)
107
120
  ];
108
121
  const stopOnToolCall = agent.properties.stopOnToolCall;
109
122
  if (stopOnToolCall) {
@@ -118,8 +131,9 @@ async function createToolLoopAgent({ connection, agent, context, autoApprove = f
118
131
  model,
119
132
  instructions,
120
133
  tools,
134
+ toolApproval,
121
135
  stopWhen: stopConditions.length === 1 ? stopConditions[0] : stopConditions,
122
- maxOutputTokens: agent.properties.maxOutputTokens,
136
+ maxOutputTokens: agent.properties.maxOutputTokens ?? connection.maxOutputTokens,
123
137
  temperature: agent.properties.temperature,
124
138
  toolChoice: agent.properties.toolChoice ?? 'auto',
125
139
  providerOptions: agent.properties.providerOptions,
@@ -134,17 +148,27 @@ async function createToolLoopAgent({ connection, agent, context, autoApprove = f
134
148
  ...agent.properties.prepareStep ? {
135
149
  prepareStep: buildPrepareStep(agent.properties.prepareStep)
136
150
  } : {},
151
+ prepareCall: (callArgs)=>({
152
+ ...callArgs,
153
+ prompt: nameAttachedFiles(callArgs.prompt)
154
+ }),
155
+ experimental_download: createFileDownload({
156
+ ...agent.properties.fileDownload,
157
+ signal: context.signal
158
+ }),
137
159
  ...hookCallbacks,
138
160
  ...agent.properties.repairToolCall ? {
139
- experimental_repairToolCall: async ({ toolCall })=>{
161
+ repairToolCall: async ({ toolCall })=>{
140
162
  return {
141
163
  ...toolCall
142
164
  };
143
165
  }
144
166
  } : {}
145
167
  });
146
- const timeoutConfig = agent.properties.timeout != null ? {
147
- timeout: agent.properties.timeout
168
+ // The agent's own timeout, else the connection's default for every call on it.
169
+ const timeout = agent.properties.timeout ?? connection.timeout;
170
+ const timeoutConfig = timeout != null ? {
171
+ timeout
148
172
  } : {};
149
173
  return {
150
174
  agentInstance,
package/dist/decide.js ADDED
@@ -0,0 +1,44 @@
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 decideWithEvaluation from './decideWithEvaluation.js';
16
+ import decideWithStructuredOutput from './decideWithStructuredOutput.js';
17
+ // Typed questions about a state in, typed answers with a confidence out, on
18
+ // a model the caller already holds. The Decide request resolver runs this
19
+ // with its connection's provider; code with no connection or request calls it
20
+ // with a model of its own.
21
+ // evaluation an evaluation model (provider.evaluationModel(id));
22
+ // structured-output any language model (provider(id)).
23
+ // providerMetadata is the AI SDK result's, which carries gateway.cost when
24
+ // the AI Gateway reports it.
25
+ async function decide({ model, backend, state, questions, options = {} }) {
26
+ if (backend === 'evaluation') {
27
+ return decideWithEvaluation({
28
+ model,
29
+ state,
30
+ questions,
31
+ options
32
+ });
33
+ }
34
+ if (backend === 'structured-output') {
35
+ return decideWithStructuredOutput({
36
+ model,
37
+ state,
38
+ questions,
39
+ options
40
+ });
41
+ }
42
+ throw new Error(`decide backend should be "evaluation" or "structured-output". Received ${JSON.stringify(backend)}.`);
43
+ }
44
+ export default decide;