@lowdefy/docs-content 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.
Files changed (285) hide show
  1. package/README.md +1 -0
  2. package/content/actions/downloadcsv.md +1 -1
  3. package/content/actions/emailotpsend.md +58 -0
  4. package/content/actions/emailotpverify.md +79 -0
  5. package/content/actions/getlocalstorage.md +43 -0
  6. package/content/actions/link.md +47 -1
  7. package/content/actions/login.md +25 -5
  8. package/content/actions/logout.md +7 -5
  9. package/content/actions/magiclinkverify.md +117 -0
  10. package/content/actions/pdfmake.md +2 -2
  11. package/content/actions/posthogalias.md +29 -0
  12. package/content/actions/posthogcapture.md +49 -0
  13. package/content/actions/posthogcapturepageleave.md +38 -0
  14. package/content/actions/posthogfeatureflag.md +50 -0
  15. package/content/actions/posthoggroup.md +37 -0
  16. package/content/actions/posthogidentify.md +54 -0
  17. package/content/actions/posthoginit.md +96 -0
  18. package/content/actions/posthogoptin.md +29 -0
  19. package/content/actions/posthogoptout.md +29 -0
  20. package/content/actions/posthogpageview.md +37 -0
  21. package/content/actions/posthogreloadfeatureflags.md +47 -0
  22. package/content/actions/posthogreset.md +28 -0
  23. package/content/actions/posthogsetpersonproperties.md +36 -0
  24. package/content/actions/removelocalstorage.md +28 -0
  25. package/content/actions/resetvalidation.md +5 -3
  26. package/content/actions/setdarkmode.md +3 -3
  27. package/content/actions/setglobal.md +2 -0
  28. package/content/actions/setlocale.md +1 -1
  29. package/content/actions/setlocalstorage.md +34 -0
  30. package/content/actions/setstate.md +2 -0
  31. package/content/actions/validate.md +7 -4
  32. package/content/adapter-reference/mongodbauthadapter.md +46 -0
  33. package/content/agents/agent-endpoint-tools.md +24 -0
  34. package/content/agents/agent-properties.md +13 -3
  35. package/content/agents/agent-server-hooks.md +1 -1
  36. package/content/agents/agentchat.md +43 -7
  37. package/content/agents/agentconversations.md +42 -8
  38. package/content/agents/agents-introduction.md +107 -0
  39. package/content/callback-reference/auth0logoutcallback.md +54 -0
  40. package/content/concepts/ai-agent-docs.md +455 -106
  41. package/content/concepts/blocks.md +150 -0
  42. package/content/concepts/connections-and-requests.md +402 -0
  43. package/content/concepts/custom-html.md +42 -0
  44. package/content/concepts/custom-styling.md +50 -5
  45. package/content/concepts/dynamic-page-content.md +309 -0
  46. package/content/concepts/events-and-actions.md +154 -2
  47. package/content/concepts/four-primitives.md +31 -0
  48. package/content/concepts/html-attributes.md +293 -0
  49. package/content/concepts/i18n.md +8 -3
  50. package/content/concepts/keyboard-shortcuts.md +2 -2
  51. package/content/concepts/layout-overview.md +1 -1
  52. package/content/concepts/logger.md +99 -0
  53. package/content/concepts/lowdefy-api.md +1319 -0
  54. package/content/concepts/lowdefy-schema.md +136 -3
  55. package/content/concepts/menus.md +8 -7
  56. package/content/concepts/module-authoring.md +76 -5
  57. package/content/concepts/modules.md +3 -1
  58. package/content/concepts/notifications.md +180 -0
  59. package/content/concepts/operators.md +7 -0
  60. package/content/concepts/page-and-app-state.md +252 -0
  61. package/content/concepts/page-paths.md +209 -0
  62. package/content/concepts/theming.md +582 -0
  63. package/content/connections/aigateway.md +375 -0
  64. package/content/connections/anthropic.md +169 -2
  65. package/content/connections/awss3.md +178 -2
  66. package/content/connections/axioshttp.md +181 -0
  67. package/content/connections/google.md +169 -2
  68. package/content/connections/mongodb.md +1014 -3
  69. package/content/connections/openai-connection.md +169 -2
  70. package/content/connections/sendgridmail.md +2 -0
  71. package/content/connections/smtp.md +3 -1
  72. package/content/connections/treg.md +329 -0
  73. package/content/container-blocks/affix.md +47 -7
  74. package/content/container-blocks/alert.md +76 -24
  75. package/content/container-blocks/badge.md +100 -24
  76. package/content/container-blocks/box.md +9 -9
  77. package/content/container-blocks/card.md +132 -27
  78. package/content/container-blocks/carousel.md +60 -7
  79. package/content/container-blocks/collapse.md +153 -9
  80. package/content/container-blocks/configprovider.md +35 -13
  81. package/content/container-blocks/confirmmodal.md +69 -23
  82. package/content/container-blocks/content.md +62 -98
  83. package/content/container-blocks/descriptions.md +45 -4
  84. package/content/container-blocks/drawer.md +139 -28
  85. package/content/container-blocks/dropdownmenu.md +119 -31
  86. package/content/container-blocks/flex.md +40 -62
  87. package/content/container-blocks/footer.md +15 -11
  88. package/content/container-blocks/googlemapsheatmap.md +1 -1
  89. package/content/container-blocks/googlemapsscript.md +2 -2
  90. package/content/container-blocks/header.md +71 -36
  91. package/content/container-blocks/label.md +34 -7
  92. package/content/container-blocks/layout.md +52 -34
  93. package/content/container-blocks/masonry.md +17 -71
  94. package/content/container-blocks/mobilemenu.md +131 -88
  95. package/content/container-blocks/modal.md +161 -26
  96. package/content/container-blocks/pageheadermenu.md +138 -31
  97. package/content/container-blocks/pagesidebarlayout.md +230 -27
  98. package/content/container-blocks/pagesidermenu.md +153 -43
  99. package/content/container-blocks/popover.md +34 -31
  100. package/content/container-blocks/result.md +32 -21
  101. package/content/container-blocks/sider.md +85 -122
  102. package/content/container-blocks/span.md +7 -7
  103. package/content/container-blocks/spinner.md +3 -3
  104. package/content/container-blocks/splitter.md +150 -68
  105. package/content/container-blocks/tabs.md +64 -12
  106. package/content/container-blocks/tooltip.md +22 -46
  107. package/content/container-blocks/watermark.md +22 -4
  108. package/content/controls/parallel_for.md +21 -2
  109. package/content/controls/reject.md +24 -3
  110. package/content/controls/return.md +17 -1
  111. package/content/controls/throw.md +1 -0
  112. package/content/controls/try.md +4 -2
  113. package/content/controls/while.md +46 -0
  114. package/content/deployment/deployment-environments.md +10 -7
  115. package/content/deployment/docker.md +22 -7
  116. package/content/deployment/node-server.md +4 -0
  117. package/content/deployment/vercel.md +17 -6
  118. package/content/display-blocks/aggrid.md +33 -16
  119. package/content/display-blocks/anchor.md +16 -15
  120. package/content/display-blocks/avatar.md +57 -37
  121. package/content/display-blocks/breadcrumb.md +70 -21
  122. package/content/display-blocks/button.md +93 -19
  123. package/content/display-blocks/calendar.md +12 -0
  124. package/content/display-blocks/clickablehtml.md +239 -0
  125. package/content/display-blocks/dangeroushtml.md +1 -1
  126. package/content/display-blocks/difflist.md +1 -1
  127. package/content/display-blocks/difftimeline.md +1 -1
  128. package/content/display-blocks/divider.md +64 -3
  129. package/content/display-blocks/dropdownbutton.md +81 -30
  130. package/content/display-blocks/echart.md +35 -1
  131. package/content/display-blocks/eventlog.md +363 -0
  132. package/content/display-blocks/floatbutton.md +129 -42
  133. package/content/display-blocks/html.md +61 -1
  134. package/content/display-blocks/icon.md +250 -67
  135. package/content/display-blocks/img.md +2 -2
  136. package/content/display-blocks/menu.md +146 -73
  137. package/content/display-blocks/message.md +38 -124
  138. package/content/display-blocks/notification.md +94 -222
  139. package/content/display-blocks/paragraph.md +59 -9
  140. package/content/display-blocks/pollingtimer.md +263 -0
  141. package/content/display-blocks/progress.md +96 -17
  142. package/content/display-blocks/qrcode.md +19 -4
  143. package/content/display-blocks/s3download.md +1 -1
  144. package/content/display-blocks/search.md +19 -9
  145. package/content/display-blocks/skeletonbutton.md +1 -0
  146. package/content/display-blocks/skeletoninput.md +1 -0
  147. package/content/display-blocks/statistic.md +75 -17
  148. package/content/display-blocks/steps.md +58 -25
  149. package/content/display-blocks/table.md +2527 -0
  150. package/content/display-blocks/tablelight.md +621 -0
  151. package/content/display-blocks/tag.md +102 -17
  152. package/content/display-blocks/title.md +50 -11
  153. package/content/display-blocks/tour.md +33 -23
  154. package/content/input-blocks/autocomplete.md +81 -9
  155. package/content/input-blocks/buttonselector.md +45 -8
  156. package/content/input-blocks/captcha.md +40 -0
  157. package/content/input-blocks/checkboxselector.md +97 -7
  158. package/content/input-blocks/checkboxswitch.md +33 -3
  159. package/content/input-blocks/colorselector.md +63 -14
  160. package/content/input-blocks/daterangeselector.md +165 -45
  161. package/content/input-blocks/dateselector.md +139 -41
  162. package/content/input-blocks/datetimeselector.md +158 -49
  163. package/content/input-blocks/inputgallery.md +3 -3
  164. package/content/input-blocks/intentinput.md +207 -0
  165. package/content/input-blocks/monthselector.md +120 -52
  166. package/content/input-blocks/multipleselector.md +150 -39
  167. package/content/input-blocks/numberinput.md +98 -12
  168. package/content/input-blocks/pagination.md +70 -14
  169. package/content/input-blocks/paragraphinput.md +51 -37
  170. package/content/input-blocks/passwordinput.md +60 -6
  171. package/content/input-blocks/phonenumberinput.md +59 -26
  172. package/content/input-blocks/placesautocomplete.md +319 -0
  173. package/content/input-blocks/radioselector.md +83 -7
  174. package/content/input-blocks/ratingslider.md +57 -26
  175. package/content/input-blocks/s3uploadbutton.md +24 -24
  176. package/content/input-blocks/s3uploaddragger.md +3 -3
  177. package/content/input-blocks/s3uploadphoto.md +5 -5
  178. package/content/input-blocks/segmentedselector.md +72 -32
  179. package/content/input-blocks/selector.md +109 -21
  180. package/content/input-blocks/switch.md +65 -17
  181. package/content/input-blocks/tableinput.md +445 -0
  182. package/content/input-blocks/tagmultipleselector.md +114 -0
  183. package/content/input-blocks/tagselector.md +114 -0
  184. package/content/input-blocks/textarea.md +32 -3
  185. package/content/input-blocks/textinput.md +70 -29
  186. package/content/input-blocks/tiptapinput.md +1 -1
  187. package/content/input-blocks/tiptapmentioninput.md +2 -2
  188. package/content/input-blocks/titleinput.md +39 -12
  189. package/content/input-blocks/treeinput.md +49 -25
  190. package/content/input-blocks/treemultipleselector.md +127 -10
  191. package/content/input-blocks/treeselector.md +97 -9
  192. package/content/input-blocks/upload.md +64 -15
  193. package/content/input-blocks/uploaddragger.md +17 -1
  194. package/content/input-blocks/uploadphoto.md +18 -1
  195. package/content/input-blocks/weekselector.md +120 -55
  196. package/content/learn/introduction.md +27 -0
  197. package/content/learn/quickstart.md +53 -0
  198. package/content/learn/showcase.md +8 -0
  199. package/content/list-blocks/controlledlist.md +24 -15
  200. package/content/list-blocks/list.md +11 -11
  201. package/content/list-blocks/masonrylist.md +7 -34
  202. package/content/migration/auth-upgrade.md +337 -0
  203. package/content/migration/upgrade-guide.md +1 -0
  204. package/content/migration/v3-to-v4.md +417 -0
  205. package/content/migration/v6-to-v7.md +620 -0
  206. package/content/operators/_agent.md +155 -0
  207. package/content/operators/_app.md +2 -1
  208. package/content/operators/_array.md +122 -1
  209. package/content/operators/_build.md +1 -0
  210. package/content/operators/_credential.md +57 -0
  211. package/content/operators/_cron.md +292 -0
  212. package/content/operators/_date.md +2 -0
  213. package/content/operators/_error.md +24 -1
  214. package/content/operators/_get.md +6 -6
  215. package/content/operators/_hmac.md +78 -0
  216. package/content/operators/_js.md +2 -1
  217. package/content/operators/_location.md +1 -1
  218. package/content/operators/_media.md +13 -0
  219. package/content/operators/_module.md +56 -2
  220. package/content/operators/_operator.md +17 -3
  221. package/content/operators/_path_params.md +82 -0
  222. package/content/operators/_ref.md +258 -0
  223. package/content/operators/_request.md +1 -1
  224. package/content/operators/_request_details.md +6 -0
  225. package/content/operators/_type.md +14 -3
  226. package/content/operators/_url_query.md +2 -0
  227. package/content/operators/_user.md +3 -3
  228. package/content/plugins/plugins-actions.md +10 -0
  229. package/content/plugins/plugins-connections.md +25 -0
  230. package/content/plugins/plugins-dev.md +66 -0
  231. package/content/plugins/plugins-icon-sets.md +267 -0
  232. package/content/plugins/plugins-introduction.md +27 -1
  233. package/content/plugins/plugins.md +19 -0
  234. package/content/plugins/posthog.md +359 -0
  235. package/content/provider-reference/auth-js-providers.md +107 -0
  236. package/content/provider-reference/openidconnectprovider.md +44 -0
  237. package/content/recipes/recipes.md +16 -0
  238. package/content/reference/actions-reference.md +31 -0
  239. package/content/reference/blocks-reference.md +35 -0
  240. package/content/reference/cli.md +403 -0
  241. package/content/reference/connections-reference.md +23 -0
  242. package/content/reference/operators-reference.md +47 -0
  243. package/content/reference/reference.md +16 -0
  244. package/content/reference/schema-reference.md +12 -0
  245. package/content/testing/config-tests.md +677 -0
  246. package/content/testing/e2e-configuration.md +31 -1
  247. package/content/testing/e2e-getting-started.md +1 -1
  248. package/content/testing/e2e-introduction.md +1 -1
  249. package/content/testing/e2e-writing-tests.md +12 -1
  250. package/content/testing/explore-pull-request.md +136 -0
  251. package/content/testing/journey-data-sets.md +326 -0
  252. package/content/tutorial/tutorial-actions-operators.md +2 -2
  253. package/content/tutorial/tutorial-add-blocks.md +2 -2
  254. package/content/tutorial/tutorial-create-page.md +48 -2
  255. package/content/tutorial/tutorial-display-data-page.md +3 -3
  256. package/content/tutorial/tutorial-requests-api.md +155 -0
  257. package/content/tutorial/tutorial-requests-sql.md +153 -0
  258. package/content/tutorial/tutorial-start.md +66 -1
  259. package/content/user-authentication/auth-configuration.md +267 -0
  260. package/content/user-authentication/auth-providers.md +24 -0
  261. package/content/user-authentication/auth-steps.md +141 -0
  262. package/content/user-authentication/login-and-logout.md +160 -8
  263. package/content/user-authentication/mcp-oauth.md +424 -0
  264. package/content/user-authentication/organizations.md +246 -0
  265. package/content/user-authentication/protected-pages-apis.md +97 -0
  266. package/content/user-authentication/roles.md +49 -0
  267. package/content/user-authentication/two-factor.md +229 -0
  268. package/content/user-authentication/user-object.md +58 -0
  269. package/content/user-authentication/users-introduction.md +8 -0
  270. package/content/websockets/websocket-publish.md +105 -0
  271. package/content/websockets/websocket-subscriptions.md +136 -0
  272. package/content/websockets/websockets-introduction.md +101 -0
  273. package/hazards.json +56 -0
  274. package/index.json +3458 -14
  275. package/package.json +10 -1
  276. package/scripts/extractAgentDocs.js +41 -30
  277. package/scripts/hashDocSources.js +38 -0
  278. package/scripts/isRedirectPage.js +26 -0
  279. package/scripts/recordSourceHashes.js +97 -0
  280. package/scripts/resolvePageSections.js +42 -0
  281. package/scripts/sectionKind.js +27 -0
  282. package/content/concepts/cli.md +0 -223
  283. package/content/other/introduction.md +0 -39
  284. package/content/other/next-auth-providers.md +0 -3
  285. /package/content/{other → actions}/updatesession.md +0 -0
@@ -0,0 +1,375 @@
1
+ # AI Gateway
2
+
3
+ The AIGateway connection connects to the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway), one API for models from many providers. It provides the `AIGatewayAgent` agent type for use with [Lowdefy agents](/agents-introduction), the one-shot `GenerateText` and `GenerateObject` requests, and `Decide` on evaluation models such as TypeSafe's Jev.
4
+
5
+ > The AIGateway connection is provided by the `@lowdefy/connection-ai-gateway` package, which is included by default.
6
+
7
+ ## Connections
8
+
9
+ ### AIGateway
10
+
11
+ #### Properties
12
+ - `apiKey: string`: AI Gateway API key. Use [`_secret`](/_secret) to reference this securely. Optional — falls back to the `AI_GATEWAY_API_KEY` environment variable, or Vercel OIDC when deployed on Vercel.
13
+ - `baseURL: string`: Optional base URL for the AI Gateway API.
14
+ - `headers: object`: Optional custom headers to include in gateway requests.
15
+ - `maxOutputTokens: number`: Default maximum number of tokens a model call generates, for the requests and agents on this connection that do not set their own.
16
+ - `timeout: number`: Default milliseconds a model call may take, retries included, before it is cancelled, for the requests and agents on this connection that do not set their own. See _Limits and cancellation_ below.
17
+
18
+ Model ids name the creator and the model, e.g. `anthropic/claude-sonnet-5`, `google/gemini-3.8-flash` or `typesafe-ai/jev`.
19
+
20
+ ###### Connection example:
21
+ ```yaml
22
+ connections:
23
+ - id: gateway
24
+ type: AIGateway
25
+ properties:
26
+ apiKey:
27
+ _secret: AI_GATEWAY_API_KEY
28
+ ```
29
+
30
+ ## Agent Types
31
+
32
+ ### AIGatewayAgent
33
+
34
+ The `AIGatewayAgent` supports all [common agent properties](/agents-introduction) plus the gateway's routing options:
35
+
36
+ | Property | Type | Description |
37
+ | --- | --- | --- |
38
+ | `order` | string[] | Provider slugs to try in order (e.g. `["vertex", "anthropic"]`). The gateway tries each until one succeeds. |
39
+ | `only` | string[] | Restrict routing to these provider slugs. |
40
+ | `fallbackModels` | string[] | Model ids tried in order when the primary model fails. |
41
+ | `user` | string | End-user identifier for spend attribution in gateway analytics. |
42
+ | `tags` | string[] | Tags to categorize and filter usage in gateway reports. |
43
+
44
+ ###### Agent with a fallback model:
45
+ ```yaml
46
+ agents:
47
+ - id: support_agent
48
+ type: AIGatewayAgent
49
+ connectionId: gateway
50
+ properties:
51
+ model: anthropic/claude-sonnet-5
52
+ fallbackModels:
53
+ - google/gemini-3.8-flash
54
+ instructions: |
55
+ You are a customer support agent. Search the knowledge
56
+ base before answering questions.
57
+ maxSteps: 5
58
+ tools:
59
+ - search-knowledge-base
60
+ ```
61
+
62
+ ## Evaluation models
63
+
64
+ Evaluation models return typed decisions — choices, yes/no probabilities and scores — instead of text, answer every question in one pass, and bill input tokens only. On the AI Gateway, `Decide` asks an evaluation model by default (`backend: evaluation`); set `backend: structured-output` to ask a language model on the gateway instead. See [`Decide`](#decide) below.
65
+
66
+ ## Requests
67
+
68
+ Request types:
69
+
70
+ - GenerateText
71
+ - GenerateObject
72
+ - Decide
73
+
74
+ All AI provider connections (`Anthropic`, `OpenAI`, `Google`, `AIGateway`) provide the same `GenerateText`, `GenerateObject` and `Decide` request types — the `connectionId` selects the provider. These make a single, one-shot model call and return the result. They can be used as page requests, or as steps in [API endpoint routines](/api) — useful for classify, extract, summarize, or decide steps where the surrounding logic stays in your routine. For a closed-vocabulary decision — pick one of these options, yes or no, rate on this scale — use `Decide`.
75
+
76
+ For multi-step tool use, see [agents](/agents-introduction) instead.
77
+
78
+ ### Limits and cancellation
79
+
80
+ Two limits bound every AI request. Set them on the request, or on the connection as the default for every request and agent that uses it:
81
+
82
+ - `maxOutputTokens` caps the tokens one call generates. Without it, the provider's default applies.
83
+ - `timeout` cancels a call, retries included, that runs longer than this many milliseconds. The request fails with a `ServiceError`.
84
+
85
+ A call is also cancelled when the request that started it closes, so a provider call that nobody is waiting for stops instead of running, and billing, to its end:
86
+
87
+ - A page request, or an API endpoint called over HTTP, is cancelled when the server's request timeout (`config.requestTimeout`, default 30 seconds) answers first, which fails it with a `ServiceError`. On the Node server it is also cancelled when the client disconnects; that is logged as a warning, not an error.
88
+ - On [Vercel](/vercel), only the request timeout cancels a call: a client disconnect does not, and the call runs until it finishes, times out, or the function reaches `config.vercel.maxDuration`. Keep `config.requestTimeout` below `maxDuration`, or Vercel stops the function before the timeout can cancel anything (the build warns when it is not).
89
+ - Endpoints with `async: true`, `detached: true` calls, and scheduled runs answer at once and then run to their end: the closing request does not cancel them.
90
+ - An agent chat turn runs to its end after the client disconnects, so its `onFinish` hooks still save the conversation. Bound it with the agent's `timeout` and `maxSteps`. A `CallAgent` step is cancelled with the routine that runs it.
91
+
92
+ ### Files in messages
93
+
94
+ A file part in `messages` (`{ type: 'file', data: <link>, mediaType }`) goes to the model as a link when the provider takes that media type as a link (the main providers do for images and PDFs). Any other file, such as a CSV or text file, is downloaded by the server and sent as content, within the request's `fileDownload` limits. The server downloads only an `https:` link to a public address, checking the address on every redirect, and a failed download names the file's host, never its link, so a signed link stays out of the server log. `Decide` takes no files.
95
+
96
+ When a provider rate-limits a call (HTTP 429), the model client retries it (`maxRetries`), waiting as long as the provider's `Retry-After` asks, up to a minute. If the retries run out, the request fails with a `ServiceError`, as a 429 does on every connection, and the server log records the `Retry-After` value.
97
+
98
+ ### GenerateText
99
+
100
+ Generates text from a prompt.
101
+
102
+ #### Properties
103
+
104
+ - `model: string`: **Required** - Model id to generate with.
105
+ - `prompt: string`: Text prompt. Use either `prompt` or `messages`, not both.
106
+ - `messages: object[]`: Model messages (`{ role, content }`). Use either `prompt` or `messages`, not both.
107
+ - `system: string`: System prompt.
108
+ - `allowSystemInMessages: boolean`: Default: `false` - Allow `system` role messages in `messages`. A system message instructs the model as the app itself, so without this a request whose `messages` include one fails. Only set it when the messages come from the app, never from a user (for example a message list built from `_payload`). Use `system` for the system prompt.
109
+ - `maxOutputTokens: number`: Maximum number of tokens to generate. Defaults to the connection's `maxOutputTokens`.
110
+ - `timeout: number`: Milliseconds the model call may take, retries included, before it is cancelled. Defaults to the connection's `timeout`.
111
+ - `fileDownload: object`: Limits on a file in `messages` the server downloads (see [Files in messages](#files-in-messages)).
112
+ - `maxBytes: integer`: Default: `20971520` (20 MB) - Largest file the server downloads. A larger file fails the request.
113
+ - `timeout: integer`: Default: `30000` - Milliseconds a file download may take.
114
+ - `temperature: number`: Sampling temperature (0 to 2).
115
+ - `topP: number`: Nucleus sampling.
116
+ - `topK: number`: Only sample from the top K options for each subsequent token.
117
+ - `frequencyPenalty: number`: Penalize repeated tokens by frequency.
118
+ - `presencePenalty: number`: Penalize tokens that have already appeared.
119
+ - `seed: number`: Seed for deterministic sampling, if supported by the model.
120
+ - `stopSequences: string[]`: Sequences that stop generation.
121
+ - `maxRetries: number`: Maximum number of retries. Defaults to 2.
122
+ - `providerOptions: object`: Provider-specific options, keyed by provider (e.g. `anthropic`, `openai`, `google`).
123
+
124
+ #### Response
125
+
126
+ ```yaml
127
+ text: string # The generated text.
128
+ reasoningText: string # Reasoning text, when the model produced any.
129
+ finishReason: string # 'stop', 'length', 'content-filter', ...
130
+ usage: object # Token usage ({ inputTokens, outputTokens, totalTokens, ... }).
131
+ providerMetadata: object # Provider-specific metadata, when returned.
132
+ warnings: array # Call warnings from the provider, when returned.
133
+ ```
134
+
135
+ #### Examples
136
+
137
+ ###### Summarize text in an API endpoint routine:
138
+
139
+ ```yaml
140
+ api:
141
+ - id: summarize-text
142
+ type: Api
143
+ routine:
144
+ - id: summarize
145
+ type: GenerateText
146
+ connectionId: claude
147
+ properties:
148
+ model: claude-haiku-4-5
149
+ system: You are a concise summarizer.
150
+ prompt:
151
+ _payload: text
152
+ - ':return':
153
+ summary:
154
+ _step: summarize.text
155
+ ```
156
+
157
+ ###### Text generation as a page request:
158
+
159
+ ```yaml
160
+ requests:
161
+ - id: generate_reply
162
+ type: GenerateText
163
+ connectionId: claude
164
+ payload:
165
+ message:
166
+ _state: customer_message
167
+ properties:
168
+ model: claude-haiku-4-5
169
+ system: Draft a friendly reply to the customer message.
170
+ prompt:
171
+ _payload: message
172
+ ```
173
+
174
+ ### GenerateObject
175
+
176
+ Generates a structured object matching a JSON Schema. Ideal for classification, extraction, and routing decisions — the result lands in `_step` (or `_request`) as plain data your config can act on.
177
+
178
+ #### Properties
179
+
180
+ Takes the same properties as `GenerateText`, except `stopSequences`, plus:
181
+
182
+ - `schema: object`: **Required** - JSON Schema describing the object the model must generate.
183
+ - `schemaName: string`: Optional name for the output schema, passed to the model.
184
+ - `schemaDescription: string`: Optional description of the output schema, passed to the model.
185
+
186
+ #### Response
187
+
188
+ ```yaml
189
+ object: object # The generated object, matching the schema.
190
+ reasoningText: string # Reasoning text, when the model produced any.
191
+ finishReason: string # 'stop', 'length', 'content-filter', ...
192
+ usage: object # Token usage ({ inputTokens, outputTokens, totalTokens, ... }).
193
+ providerMetadata: object # Provider-specific metadata, when returned.
194
+ warnings: array # Call warnings from the provider, when returned.
195
+ ```
196
+
197
+ #### Examples
198
+
199
+ ###### Classify then route in an API endpoint routine:
200
+
201
+ ```yaml
202
+ api:
203
+ - id: triage-ticket
204
+ type: Api
205
+ routine:
206
+ - id: classify
207
+ type: GenerateObject
208
+ connectionId: claude
209
+ properties:
210
+ model: claude-haiku-4-5
211
+ prompt:
212
+ _payload: ticket_text
213
+ schema:
214
+ type: object
215
+ properties:
216
+ category:
217
+ type: string
218
+ enum:
219
+ - billing
220
+ - technical
221
+ - other
222
+ urgent:
223
+ type: boolean
224
+ - ':if':
225
+ _eq:
226
+ - _step: classify.object.urgent
227
+ - true
228
+ ':then':
229
+ - id: escalate
230
+ type: CallApi
231
+ properties:
232
+ endpointId: escalate-ticket
233
+ payload:
234
+ category:
235
+ _step: classify.object.category
236
+ ```
237
+
238
+ ### Decide
239
+
240
+ Makes typed decisions about a piece of state: pick one of a set of options, judge a statement true or false, or place something on an ordered scale. Every answer comes back in the shape you declared, with a confidence, so a routine can branch on it — and send a low-confidence answer to a person instead.
241
+
242
+ The build knows every option, so a routine branch that compares an answer with a name that is not one of its options — `_eq: [{ _step: triage.team.choice }, bil-ling]` — fails the build rather than silently never matching. A `_step` reference to a question the step does not ask, or to a field its answer does not have, fails the build the same way.
243
+
244
+ `Decide` has two backends behind the same interface:
245
+
246
+ - `evaluation` — an evaluation model, such as TypeSafe's Jev (`typesafe-ai/jev`) on the [AI Gateway](/AIGateway). It returns a probability for every option in one pass, in under a second, and bills input tokens only. The default, and only available, on the `AIGateway` connection.
247
+ - `structured-output` — any language model, asked for the answers as structured output that follows a schema of the questions. Providers do not all enforce the schema, so Lowdefy checks each answer against its question (see `null` answers below). Available on every AI connection, and the default on `Anthropic`, `OpenAI` and `Google`. Its confidence is the model's own estimate, not a calibrated probability.
248
+
249
+ Keep the state to what the questions need: an evaluation model reads the state literally, and accuracy drops as it grows. A `Decide` is never a security boundary — text in the state can argue for its own answer.
250
+
251
+ #### Properties
252
+
253
+ - `model: string`: **Required** - Model id to decide with, e.g. `typesafe-ai/jev`. Pin a version wherever a confidence threshold is tuned — a `latest` alias changes answers on release.
254
+ - `state: string | object | array`: **Required** - What the questions are about.
255
+ - `questions: object`: **Required** - Named questions, answered together against the state. Each question id becomes a key of the response (`usage` is reserved). A question is one of:
256
+ - `{ choice: string, options: object }` - Pick exactly one option. `options` maps option names (2 to 255) to what each one means (`null` for no description), or to an object with a `description` — its other keys are ignored, so one file can describe the options for `Decide` and for an [`IntentInput`](/IntentInput) block.
257
+ - `{ yesno: string, criteria?: { yes: string, no: string } }` - Judge a statement true or false. `criteria` optionally says what counts as yes and as no.
258
+ - `{ score: string, levels: string[] }` - Place the state on 2 to 10 ordered levels, lowest first.
259
+ - `backend: enum`: `evaluation` or `structured-output`. Defaults to `evaluation` on `AIGateway` and `structured-output` elsewhere.
260
+ - `maxOutputTokens: number`: Maximum number of tokens to generate, on the `structured-output` backend (an evaluation model generates no text). Defaults to the connection's `maxOutputTokens`.
261
+ - `timeout: number`: Milliseconds the model call may take, retries included, before it is cancelled. Defaults to the connection's `timeout`.
262
+ - `maxRetries: number`: Maximum number of retries. Defaults to 2.
263
+ - `providerOptions: object`: Provider-specific options, keyed by provider (e.g. `gateway: { zeroDataRetention: true }`).
264
+
265
+ #### Response
266
+
267
+ One key per question, plus `usage`:
268
+
269
+ ```yaml
270
+ <choice question>:
271
+ choice: string # The chosen option.
272
+ confidence: number # 0 to 1.
273
+ probabilities: object # Probability per option (evaluation backend), else null.
274
+ <yesno question>:
275
+ answer: boolean # true when the statement holds.
276
+ probability: number # Probability that it holds.
277
+ confidence: number # Probability of the given answer.
278
+ <score question>:
279
+ level: string # The most likely level.
280
+ index: number # Its position, from 0.
281
+ score: number # Fractional position on the scale (evaluation backend).
282
+ confidence: number # 0 to 1.
283
+ probabilities: object # Probability per level (evaluation backend), else null.
284
+ usage: object # Token usage ({ inputTokens, outputTokens, totalTokens }).
285
+ ```
286
+
287
+ An answer outside its question's terms (an option or level the question does not have, a yes/no that is not true or false, or no answer at all) comes back with every field `null`, its confidence included. `_lt` compares `null` below any number, so a confidence gate such as `_lt: [{ _step: triage.team.confidence }, 0.7]` holds it back like a low-confidence answer, and a branch on the choice matches none of the options.
288
+
289
+ #### Examples
290
+
291
+ ###### Route a support ticket, and queue uncertain ones for a person:
292
+
293
+ ```yaml
294
+ api:
295
+ - id: triage-ticket
296
+ type: Api
297
+ routine:
298
+ - id: triage
299
+ type: Decide
300
+ connectionId: gateway
301
+ properties:
302
+ model: typesafe-ai/jev
303
+ state:
304
+ subject:
305
+ _payload: subject
306
+ body:
307
+ _payload: body
308
+ questions:
309
+ team:
310
+ choice: Which team handles this ticket
311
+ options:
312
+ billing: Invoices, charges and refunds
313
+ tech: Outages and bugs
314
+ sales: Plans and quotes
315
+ down:
316
+ yesno: The customer says the service is down
317
+ providerOptions:
318
+ gateway:
319
+ zeroDataRetention: true
320
+ - ':if':
321
+ _lt:
322
+ - _step: triage.team.confidence
323
+ - 0.7
324
+ ':then':
325
+ - id: queue_review
326
+ type: MongoDBInsertOne
327
+ connectionId: review_queue
328
+ properties:
329
+ doc:
330
+ subject:
331
+ _payload: subject
332
+ suggested_team:
333
+ _step: triage.team.choice
334
+ - ':return':
335
+ status: review
336
+ - ':if':
337
+ _eq:
338
+ - _step: triage.team.choice
339
+ - billing
340
+ ':then':
341
+ - id: open_billing_case
342
+ type: CallApi
343
+ properties:
344
+ endpointId: open-billing-case
345
+ - ':return':
346
+ team:
347
+ _step: triage.team.choice
348
+ urgent:
349
+ _step: triage.down.answer
350
+ ```
351
+
352
+ ###### The same decision with any language model:
353
+
354
+ ```yaml
355
+ requests:
356
+ - id: rate_review
357
+ type: Decide
358
+ connectionId: claude
359
+ payload:
360
+ review:
361
+ _state: review_text
362
+ properties:
363
+ model: claude-haiku-4-5
364
+ state:
365
+ _payload: review
366
+ questions:
367
+ sentiment:
368
+ score: How positive is this review
369
+ levels:
370
+ - Very negative
371
+ - Negative
372
+ - Neutral
373
+ - Positive
374
+ - Very positive
375
+ ```
@@ -11,6 +11,8 @@ The Anthropic connection connects to the [Anthropic API](https://docs.anthropic.
11
11
  #### Properties
12
12
  - `apiKey: string`: __Required__ - Anthropic API key. Use [`_secret`](/_secret) to reference this securely.
13
13
  - `baseURL: string`: Optional base URL for the Anthropic API. Use this to connect to a proxy or compatible endpoint.
14
+ - `maxOutputTokens: number`: Default maximum number of tokens a model call generates, for the requests and agents on this connection that do not set their own.
15
+ - `timeout: number`: Default milliseconds a model call may take, retries included, before it is cancelled, for the requests and agents on this connection that do not set their own. See _Limits and cancellation_ below.
14
16
 
15
17
  ###### Connection example:
16
18
  ```yaml
@@ -91,11 +93,32 @@ Request types:
91
93
 
92
94
  - GenerateText
93
95
  - GenerateObject
96
+ - Decide
94
97
 
95
- All AI provider connections (`Anthropic`, `OpenAI`, `Google`, `AIGateway`) provide the same `GenerateText` and `GenerateObject` request types — the `connectionId` selects the provider. These make a single, one-shot model call and return the result. They can be used as page requests, or as steps in [API endpoint routines](/api) — useful for classify, extract, summarize, or decide steps where the surrounding logic stays in your routine.
98
+ All AI provider connections (`Anthropic`, `OpenAI`, `Google`, `AIGateway`) provide the same `GenerateText`, `GenerateObject` and `Decide` request types — the `connectionId` selects the provider. These make a single, one-shot model call and return the result. They can be used as page requests, or as steps in [API endpoint routines](/api) — useful for classify, extract, summarize, or decide steps where the surrounding logic stays in your routine. For a closed-vocabulary decision — pick one of these options, yes or no, rate on this scale — use `Decide`.
96
99
 
97
100
  For multi-step tool use, see [agents](/agents-introduction) instead.
98
101
 
102
+ ### Limits and cancellation
103
+
104
+ Two limits bound every AI request. Set them on the request, or on the connection as the default for every request and agent that uses it:
105
+
106
+ - `maxOutputTokens` caps the tokens one call generates. Without it, the provider's default applies.
107
+ - `timeout` cancels a call, retries included, that runs longer than this many milliseconds. The request fails with a `ServiceError`.
108
+
109
+ A call is also cancelled when the request that started it closes, so a provider call that nobody is waiting for stops instead of running, and billing, to its end:
110
+
111
+ - A page request, or an API endpoint called over HTTP, is cancelled when the server's request timeout (`config.requestTimeout`, default 30 seconds) answers first, which fails it with a `ServiceError`. On the Node server it is also cancelled when the client disconnects; that is logged as a warning, not an error.
112
+ - On [Vercel](/vercel), only the request timeout cancels a call: a client disconnect does not, and the call runs until it finishes, times out, or the function reaches `config.vercel.maxDuration`. Keep `config.requestTimeout` below `maxDuration`, or Vercel stops the function before the timeout can cancel anything (the build warns when it is not).
113
+ - Endpoints with `async: true`, `detached: true` calls, and scheduled runs answer at once and then run to their end: the closing request does not cancel them.
114
+ - An agent chat turn runs to its end after the client disconnects, so its `onFinish` hooks still save the conversation. Bound it with the agent's `timeout` and `maxSteps`. A `CallAgent` step is cancelled with the routine that runs it.
115
+
116
+ ### Files in messages
117
+
118
+ A file part in `messages` (`{ type: 'file', data: <link>, mediaType }`) goes to the model as a link when the provider takes that media type as a link (the main providers do for images and PDFs). Any other file, such as a CSV or text file, is downloaded by the server and sent as content, within the request's `fileDownload` limits. The server downloads only an `https:` link to a public address, checking the address on every redirect, and a failed download names the file's host, never its link, so a signed link stays out of the server log. `Decide` takes no files.
119
+
120
+ When a provider rate-limits a call (HTTP 429), the model client retries it (`maxRetries`), waiting as long as the provider's `Retry-After` asks, up to a minute. If the retries run out, the request fails with a `ServiceError`, as a 429 does on every connection, and the server log records the `Retry-After` value.
121
+
99
122
  ### GenerateText
100
123
 
101
124
  Generates text from a prompt.
@@ -106,7 +129,12 @@ Generates text from a prompt.
106
129
  - `prompt: string`: Text prompt. Use either `prompt` or `messages`, not both.
107
130
  - `messages: object[]`: Model messages (`{ role, content }`). Use either `prompt` or `messages`, not both.
108
131
  - `system: string`: System prompt.
109
- - `maxOutputTokens: number`: Maximum number of tokens to generate.
132
+ - `allowSystemInMessages: boolean`: Default: `false` - Allow `system` role messages in `messages`. A system message instructs the model as the app itself, so without this a request whose `messages` include one fails. Only set it when the messages come from the app, never from a user (for example a message list built from `_payload`). Use `system` for the system prompt.
133
+ - `maxOutputTokens: number`: Maximum number of tokens to generate. Defaults to the connection's `maxOutputTokens`.
134
+ - `timeout: number`: Milliseconds the model call may take, retries included, before it is cancelled. Defaults to the connection's `timeout`.
135
+ - `fileDownload: object`: Limits on a file in `messages` the server downloads (see [Files in messages](#files-in-messages)).
136
+ - `maxBytes: integer`: Default: `20971520` (20 MB) - Largest file the server downloads. A larger file fails the request.
137
+ - `timeout: integer`: Default: `30000` - Milliseconds a file download may take.
110
138
  - `temperature: number`: Sampling temperature (0 to 2).
111
139
  - `topP: number`: Nucleus sampling.
112
140
  - `topK: number`: Only sample from the top K options for each subsequent token.
@@ -230,3 +258,142 @@ api:
230
258
  category:
231
259
  _step: classify.object.category
232
260
  ```
261
+
262
+ ### Decide
263
+
264
+ Makes typed decisions about a piece of state: pick one of a set of options, judge a statement true or false, or place something on an ordered scale. Every answer comes back in the shape you declared, with a confidence, so a routine can branch on it — and send a low-confidence answer to a person instead.
265
+
266
+ The build knows every option, so a routine branch that compares an answer with a name that is not one of its options — `_eq: [{ _step: triage.team.choice }, bil-ling]` — fails the build rather than silently never matching. A `_step` reference to a question the step does not ask, or to a field its answer does not have, fails the build the same way.
267
+
268
+ `Decide` has two backends behind the same interface:
269
+
270
+ - `evaluation` — an evaluation model, such as TypeSafe's Jev (`typesafe-ai/jev`) on the [AI Gateway](/AIGateway). It returns a probability for every option in one pass, in under a second, and bills input tokens only. The default, and only available, on the `AIGateway` connection.
271
+ - `structured-output` — any language model, asked for the answers as structured output that follows a schema of the questions. Providers do not all enforce the schema, so Lowdefy checks each answer against its question (see `null` answers below). Available on every AI connection, and the default on `Anthropic`, `OpenAI` and `Google`. Its confidence is the model's own estimate, not a calibrated probability.
272
+
273
+ Keep the state to what the questions need: an evaluation model reads the state literally, and accuracy drops as it grows. A `Decide` is never a security boundary — text in the state can argue for its own answer.
274
+
275
+ #### Properties
276
+
277
+ - `model: string`: **Required** - Model id to decide with, e.g. `typesafe-ai/jev`. Pin a version wherever a confidence threshold is tuned — a `latest` alias changes answers on release.
278
+ - `state: string | object | array`: **Required** - What the questions are about.
279
+ - `questions: object`: **Required** - Named questions, answered together against the state. Each question id becomes a key of the response (`usage` is reserved). A question is one of:
280
+ - `{ choice: string, options: object }` - Pick exactly one option. `options` maps option names (2 to 255) to what each one means (`null` for no description), or to an object with a `description` — its other keys are ignored, so one file can describe the options for `Decide` and for an [`IntentInput`](/IntentInput) block.
281
+ - `{ yesno: string, criteria?: { yes: string, no: string } }` - Judge a statement true or false. `criteria` optionally says what counts as yes and as no.
282
+ - `{ score: string, levels: string[] }` - Place the state on 2 to 10 ordered levels, lowest first.
283
+ - `backend: enum`: `evaluation` or `structured-output`. Defaults to `evaluation` on `AIGateway` and `structured-output` elsewhere.
284
+ - `maxOutputTokens: number`: Maximum number of tokens to generate, on the `structured-output` backend (an evaluation model generates no text). Defaults to the connection's `maxOutputTokens`.
285
+ - `timeout: number`: Milliseconds the model call may take, retries included, before it is cancelled. Defaults to the connection's `timeout`.
286
+ - `maxRetries: number`: Maximum number of retries. Defaults to 2.
287
+ - `providerOptions: object`: Provider-specific options, keyed by provider (e.g. `gateway: { zeroDataRetention: true }`).
288
+
289
+ #### Response
290
+
291
+ One key per question, plus `usage`:
292
+
293
+ ```yaml
294
+ <choice question>:
295
+ choice: string # The chosen option.
296
+ confidence: number # 0 to 1.
297
+ probabilities: object # Probability per option (evaluation backend), else null.
298
+ <yesno question>:
299
+ answer: boolean # true when the statement holds.
300
+ probability: number # Probability that it holds.
301
+ confidence: number # Probability of the given answer.
302
+ <score question>:
303
+ level: string # The most likely level.
304
+ index: number # Its position, from 0.
305
+ score: number # Fractional position on the scale (evaluation backend).
306
+ confidence: number # 0 to 1.
307
+ probabilities: object # Probability per level (evaluation backend), else null.
308
+ usage: object # Token usage ({ inputTokens, outputTokens, totalTokens }).
309
+ ```
310
+
311
+ An answer outside its question's terms (an option or level the question does not have, a yes/no that is not true or false, or no answer at all) comes back with every field `null`, its confidence included. `_lt` compares `null` below any number, so a confidence gate such as `_lt: [{ _step: triage.team.confidence }, 0.7]` holds it back like a low-confidence answer, and a branch on the choice matches none of the options.
312
+
313
+ #### Examples
314
+
315
+ ###### Route a support ticket, and queue uncertain ones for a person:
316
+
317
+ ```yaml
318
+ api:
319
+ - id: triage-ticket
320
+ type: Api
321
+ routine:
322
+ - id: triage
323
+ type: Decide
324
+ connectionId: gateway
325
+ properties:
326
+ model: typesafe-ai/jev
327
+ state:
328
+ subject:
329
+ _payload: subject
330
+ body:
331
+ _payload: body
332
+ questions:
333
+ team:
334
+ choice: Which team handles this ticket
335
+ options:
336
+ billing: Invoices, charges and refunds
337
+ tech: Outages and bugs
338
+ sales: Plans and quotes
339
+ down:
340
+ yesno: The customer says the service is down
341
+ providerOptions:
342
+ gateway:
343
+ zeroDataRetention: true
344
+ - ':if':
345
+ _lt:
346
+ - _step: triage.team.confidence
347
+ - 0.7
348
+ ':then':
349
+ - id: queue_review
350
+ type: MongoDBInsertOne
351
+ connectionId: review_queue
352
+ properties:
353
+ doc:
354
+ subject:
355
+ _payload: subject
356
+ suggested_team:
357
+ _step: triage.team.choice
358
+ - ':return':
359
+ status: review
360
+ - ':if':
361
+ _eq:
362
+ - _step: triage.team.choice
363
+ - billing
364
+ ':then':
365
+ - id: open_billing_case
366
+ type: CallApi
367
+ properties:
368
+ endpointId: open-billing-case
369
+ - ':return':
370
+ team:
371
+ _step: triage.team.choice
372
+ urgent:
373
+ _step: triage.down.answer
374
+ ```
375
+
376
+ ###### The same decision with any language model:
377
+
378
+ ```yaml
379
+ requests:
380
+ - id: rate_review
381
+ type: Decide
382
+ connectionId: claude
383
+ payload:
384
+ review:
385
+ _state: review_text
386
+ properties:
387
+ model: claude-haiku-4-5
388
+ state:
389
+ _payload: review
390
+ questions:
391
+ sentiment:
392
+ score: How positive is this review
393
+ levels:
394
+ - Very negative
395
+ - Negative
396
+ - Neutral
397
+ - Positive
398
+ - Very positive
399
+ ```