@lowdefy/docs-content 0.0.0-experimental-20260928120643 → 6.1.0

package/content/connections/aigateway.md

@@ -1,368 +0,0 @@
-# AI Gateway
-
-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.
-
-> The AIGateway connection is provided by the `@lowdefy/connection-ai-gateway` package, which is included by default.
-
-## Connections
-
-### AIGateway
-
-#### Properties
-- `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.
-- `baseURL: string`: Optional base URL for the AI Gateway API.
-- `headers: object`: Optional custom headers to include in gateway requests.
-- `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.
-- `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.
-
-Model ids name the creator and the model, e.g. `anthropic/claude-sonnet-5`, `google/gemini-3.8-flash` or `typesafe-ai/jev`.
-
-###### Connection example:
-```yaml
-connections:
-  - id: gateway
-    type: AIGateway
-    properties:
-      apiKey:
-        _secret: AI_GATEWAY_API_KEY
-```
-
-## Agent Types
-
-### AIGatewayAgent
-
-The `AIGatewayAgent` supports all [common agent properties](/agents-introduction) plus the gateway's routing options:
-
-| Property | Type | Description |
-| --- | --- | --- |
-| `order` | string[] | Provider slugs to try in order (e.g. `["vertex", "anthropic"]`). The gateway tries each until one succeeds. |
-| `only` | string[] | Restrict routing to these provider slugs. |
-| `fallbackModels` | string[] | Model ids tried in order when the primary model fails. |
-| `user` | string | End-user identifier for spend attribution in gateway analytics. |
-| `tags` | string[] | Tags to categorize and filter usage in gateway reports. |
-
-###### Agent with a fallback model:
-```yaml
-agents:
-  - id: support_agent
-    type: AIGatewayAgent
-    connectionId: gateway
-    properties:
-      model: anthropic/claude-sonnet-5
-      fallbackModels:
-        - google/gemini-3.8-flash
-      instructions: |
-        You are a customer support agent. Search the knowledge
-        base before answering questions.
-      maxSteps: 5
-    tools:
-      - search-knowledge-base
-```
-
-## Evaluation models
-
-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.
-
-## Requests
-
-Request types:
-
-- GenerateText
-- GenerateObject
-- Decide
-
-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`.
-
-For multi-step tool use, see [agents](/agents-introduction) instead.
-
-### Limits and cancellation
-
-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:
-
-- `maxOutputTokens` caps the tokens one call generates. Without it, the provider's default applies.
-- `timeout` cancels a call, retries included, that runs longer than this many milliseconds. The request fails with a `ServiceError`.
-
-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:
-
-- 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.
-- 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).
-- 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.
-- 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.
-
-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.
-
-### GenerateText
-
-Generates text from a prompt.
-
-#### Properties
-
-- `model: string`: **Required** - Model id to generate with.
-- `prompt: string`: Text prompt. Use either `prompt` or `messages`, not both.
-- `messages: object[]`: Model messages (`{ role, content }`). Use either `prompt` or `messages`, not both.
-- `system: string`: System prompt.
-- `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.
-- `maxOutputTokens: number`: Maximum number of tokens to generate. Defaults to the connection's `maxOutputTokens`.
-- `timeout: number`: Milliseconds the model call may take, retries included, before it is cancelled. Defaults to the connection's `timeout`.
-- `temperature: number`: Sampling temperature (0 to 2).
-- `topP: number`: Nucleus sampling.
-- `topK: number`: Only sample from the top K options for each subsequent token.
-- `frequencyPenalty: number`: Penalize repeated tokens by frequency.
-- `presencePenalty: number`: Penalize tokens that have already appeared.
-- `seed: number`: Seed for deterministic sampling, if supported by the model.
-- `stopSequences: string[]`: Sequences that stop generation.
-- `maxRetries: number`: Maximum number of retries. Defaults to 2.
-- `providerOptions: object`: Provider-specific options, keyed by provider (e.g. `anthropic`, `openai`, `google`).
-
-#### Response
-
-```yaml
-text: string # The generated text.
-reasoningText: string # Reasoning text, when the model produced any.
-finishReason: string # 'stop', 'length', 'content-filter', ...
-usage: object # Token usage ({ inputTokens, outputTokens, totalTokens, ... }).
-providerMetadata: object # Provider-specific metadata, when returned.
-warnings: array # Call warnings from the provider, when returned.
-```
-
-#### Examples
-
-###### Summarize text in an API endpoint routine:
-
-```yaml
-api:
-  - id: summarize-text
-    type: Api
-    routine:
-      - id: summarize
-        type: GenerateText
-        connectionId: claude
-        properties:
-          model: claude-haiku-4-5
-          system: You are a concise summarizer.
-          prompt:
-            _payload: text
-      - ':return':
-          summary:
-            _step: summarize.text
-```
-
-###### Text generation as a page request:
-
-```yaml
-requests:
-  - id: generate_reply
-    type: GenerateText
-    connectionId: claude
-    payload:
-      message:
-        _state: customer_message
-    properties:
-      model: claude-haiku-4-5
-      system: Draft a friendly reply to the customer message.
-      prompt:
-        _payload: message
-```
-
-### GenerateObject
-
-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.
-
-#### Properties
-
-Takes the same properties as `GenerateText`, except `stopSequences`, plus:
-
-- `schema: object`: **Required** - JSON Schema describing the object the model must generate.
-- `schemaName: string`: Optional name for the output schema, passed to the model.
-- `schemaDescription: string`: Optional description of the output schema, passed to the model.
-
-#### Response
-
-```yaml
-object: object # The generated object, matching the schema.
-reasoningText: string # Reasoning text, when the model produced any.
-finishReason: string # 'stop', 'length', 'content-filter', ...
-usage: object # Token usage ({ inputTokens, outputTokens, totalTokens, ... }).
-providerMetadata: object # Provider-specific metadata, when returned.
-warnings: array # Call warnings from the provider, when returned.
-```
-
-#### Examples
-
-###### Classify then route in an API endpoint routine:
-
-```yaml
-api:
-  - id: triage-ticket
-    type: Api
-    routine:
-      - id: classify
-        type: GenerateObject
-        connectionId: claude
-        properties:
-          model: claude-haiku-4-5
-          prompt:
-            _payload: ticket_text
-          schema:
-            type: object
-            properties:
-              category:
-                type: string
-                enum:
-                  - billing
-                  - technical
-                  - other
-              urgent:
-                type: boolean
-      - ':if':
-          _eq:
-            - _step: classify.object.urgent
-            - true
-        ':then':
-          - id: escalate
-            type: CallApi
-            properties:
-              endpointId: escalate-ticket
-              payload:
-                category:
-                  _step: classify.object.category
-```
-
-### Decide
-
-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.
-
-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.
-
-`Decide` has two backends behind the same interface:
-
-- `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.
-- `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.
-
-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.
-
-#### Properties
-
-- `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.
-- `state: string | object | array`: **Required** - What the questions are about.
-- `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:
-  - `{ choice: string, options: object }` - Pick exactly one option. `options` maps option names (2 to 255) to what each one means (`null` for no description).
-  - `{ yesno: string, criteria?: { yes: string, no: string } }` - Judge a statement true or false. `criteria` optionally says what counts as yes and as no.
-  - `{ score: string, levels: string[] }` - Place the state on 2 to 10 ordered levels, lowest first.
-- `backend: enum`: `evaluation` or `structured-output`. Defaults to `evaluation` on `AIGateway` and `structured-output` elsewhere.
-- `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`.
-- `timeout: number`: Milliseconds the model call may take, retries included, before it is cancelled. Defaults to the connection's `timeout`.
-- `maxRetries: number`: Maximum number of retries. Defaults to 2.
-- `providerOptions: object`: Provider-specific options, keyed by provider (e.g. `gateway: { zeroDataRetention: true }`).
-
-#### Response
-
-One key per question, plus `usage`:
-
-```yaml
-<choice question>:
-  choice: string # The chosen option.
-  confidence: number # 0 to 1.
-  probabilities: object # Probability per option (evaluation backend), else null.
-<yesno question>:
-  answer: boolean # true when the statement holds.
-  probability: number # Probability that it holds.
-  confidence: number # Probability of the given answer.
-<score question>:
-  level: string # The most likely level.
-  index: number # Its position, from 0.
-  score: number # Fractional position on the scale (evaluation backend).
-  confidence: number # 0 to 1.
-  probabilities: object # Probability per level (evaluation backend), else null.
-usage: object # Token usage ({ inputTokens, outputTokens, totalTokens }).
-```
-
-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.
-
-#### Examples
-
-###### Route a support ticket, and queue uncertain ones for a person:
-
-```yaml
-api:
-  - id: triage-ticket
-    type: Api
-    routine:
-      - id: triage
-        type: Decide
-        connectionId: gateway
-        properties:
-          model: typesafe-ai/jev
-          state:
-            subject:
-              _payload: subject
-            body:
-              _payload: body
-          questions:
-            team:
-              choice: Which team handles this ticket
-              options:
-                billing: Invoices, charges and refunds
-                tech: Outages and bugs
-                sales: Plans and quotes
-            down:
-              yesno: The customer says the service is down
-          providerOptions:
-            gateway:
-              zeroDataRetention: true
-      - ':if':
-          _lt:
-            - _step: triage.team.confidence
-            - 0.7
-        ':then':
-          - id: queue_review
-            type: MongoDBInsertOne
-            connectionId: review_queue
-            properties:
-              doc:
-                subject:
-                  _payload: subject
-                suggested_team:
-                  _step: triage.team.choice
-          - ':return':
-              status: review
-      - ':if':
-          _eq:
-            - _step: triage.team.choice
-            - billing
-        ':then':
-          - id: open_billing_case
-            type: CallApi
-            properties:
-              endpointId: open-billing-case
-      - ':return':
-          team:
-            _step: triage.team.choice
-          urgent:
-            _step: triage.down.answer
-```
-
-###### The same decision with any language model:
-
-```yaml
-requests:
-  - id: rate_review
-    type: Decide
-    connectionId: claude
-    payload:
-      review:
-        _state: review_text
-    properties:
-      model: claude-haiku-4-5
-      state:
-        _payload: review
-      questions:
-        sentiment:
-          score: How positive is this review
-          levels:
-            - Very negative
-            - Negative
-            - Neutral
-            - Positive
-            - Very positive
-```

package/content/connections/axioshttp.md

@@ -1,181 +0,0 @@
-# AxiosHttp
-
-The `AxiosHttp` connection is used to connect to APIs and web servers using HTTP or HTTPS.
-
-It uses the [axios](https://github.com/axios/axios) library.
-
-The same properties can be set on both connections and requests. The properties will be merged, with the request properties overwriting connection properties. This allows properties like authentication headers and the baseURL to be set on the connection, with request specific properties like the request.
-
->Secrets like authentication headers and API keys should be stored using the [`_secret`](_secret) operator.
-
-## Connections
-
-Connection types:
-  - AxiosHttp
-
-## Requests
-
-Request types:
-  - AxiosHttp
-
-### AxiosHttp
-
-#### Properties
-
-- `url: string`: The server URL that will be used for the request.
-- `method: enum`: Default: `'get'` - The request method to be used when making the request. Options are:
-  - `'get'`
-  - `'delete'`
-  - `'head'`
-  - `'options'`
-  - `'post'`
-  - `'put'`
-  - `'patch'`
-- `baseURL: string`: `baseURL` will be prepended to `url` unless `url` is absolute. It can be convenient to set `baseURL` for an axios connection to pass relative URLs to requests or mutations using that connection.
-- `headers: object`: An object with custom headers to be sent sent with the request. The object keys should be header names, and the values should be the string header values.
-- `params: object`: An object with URL parameters to be sent with the request.
-- `data: string | object | array`: The data to be sent as the request body. Only applicable for request methods `'put'`, `'post'`, and `'patch'`. Can be an object, array or a string in the format `'Country=Brasil&City=Belo Horizonte'`.
-- `auth: object`: Indicates that HTTP Basic authorization should be used, and supplies credentials. This will set an `Authorization` header, overwriting any existing `Authorization` custom headers you have set using `headers`. Only HTTP Basic auth is configurable through this parameter, for Bearer tokens and such, use `Authorization` custom headers instead. The `auth` object should have the following fields:
-  - `username: string`
-  - `password: string`
-- `httpAgentOptions: object`: Options to pass to the Node.js [`http.Agent`](https://nodejs.org/api/http.html#http_class_http_agent) class.
-- `httpsAgentOptions: object`: Options to pass to the Node.js [`https.Agent`](https://nodejs.org/api/http.html#http_class_http_agent) class.
-- `maxContentLength: number`: Defines the max size of the http response content allowed in bytes.
-- `maxRedirects: number`: Defines the maximum number of redirects to follow. If set to 0, no redirects will be followed.
-- `proxy: object`: Defines the hostname and port of the proxy server. The `proxy` object should have the following fields:
-  - `host: string`: Host IP address (eg. `'127.0.0.1'`).
-  - `port: number`: Port number.
-  - `auth: object`: Object with username and password.
-- `responseType: enum`: Default: `'json'` - The type of data that the server will respond with. Options are:
-  - `'document'`
-  - `'json'`
-  - `'text'`
-- `responseEncoding: string`: Default: `'utf8'` - Indicates encoding to use for decoding responses.
-- `timeout: number`: Default: `0` (no timeout) - The number of milliseconds before the request times out. If the request takes longer than `timeout`, the request will be aborted. Set to `0` for no timeout.
-- `transformRequest: function`: A function to transform the request data before it is sent. Receives `data` and `headers` as arguments and should return the data to be sent.
-- `transformResponse: function`: A function to transform the received data. Receives `data` as an argument and should return the transformed data.
-- `validateStatus: function`: A function to validate whether the response should complete successfully given a status code. Receives `status` as an argument and should `true` if the status code is valid.
-
-
-#### Examples
-
-Properties for a AxiosHttp can be set on either the connection, the request, or both. However, both a connection and request need to be defined.
-
-###### A basic full example requesting data from https://jsonplaceholder.typicode.com
-
-```yaml
-lowdefy: 6.0.0
-name: Lowdefy starter
-connections:
-  - id: my_api
-    type: AxiosHttp
-    properties:
-      baseURL: https://jsonplaceholder.typicode.com
-pages:
-  - id: welcome
-    type: PageHeaderMenu
-    requests:
-      - id: get_posts
-        type: AxiosHttp
-        connectionId: my_api
-        properties:
-          url: /posts
-    events:
-      onInit:
-        - id: fetch_get_posts
-          type: Request
-          params: get_posts
-    blocks:
-      - id: rest_data
-        type: Markdown
-        properties:
-          content:
-            _string.concat:
-              - |
-                ```yaml
-              - _custom_yaml_stringify:
-                  - _request: get_posts
-              - |
-                ```
-```
-
-###### Using the connection to set baseURL and authorization, and handle specific requests as requests.
-```yaml
-connections:
-  - id: app_api
-    type: AxiosHttp
-    properties:
-      baseURL: app.com/api
-      auth:
-        username: api_user
-        password:
-          _secret: API_PASSWORD
-# ...
-requests:
-  - id: get_orders
-    type: AxiosHttp
-    connectionId: app_api
-    properties:
-      url: /orders
-  - id: update_order
-    type: AxiosHttp
-    connectionId: app_api
-    payload:
-      order_id:
-        _state: order_id
-      data:
-        _state: true
-    properties:
-      url:
-        _nunjucks:
-          template: /orders/{{ order_id }}
-          on:
-            order_id:
-              _payload: order_id
-      method: post
-      data:
-        _payload: data
-```
-
-
-###### Setting properties on only the connection:
-```yaml
-connections:
-  - id: get_count
-    type: AxiosHttp
-    properties:
-      url: myapp.com/api/count
-      headers:
-        X-Api-Key:
-          _secret: API_KEY
-# ...
-requests:
-  - id: get_count
-    type: AxiosHttp
-    connectionId: get_count
-```
-
-###### Setting properties on only the request, and using a generic connection:
-```yaml
-connections:
-  - id: axios
-    type: AxiosHttp
-# ...
-requests:
-  - id: get_api_1
-    type: AxiosHttp
-    connectionId: axios
-    properties:
-      url: app1.com/api/things
-  - id: post_to_api_2
-    type: AxiosHttp
-    connectionId: axios
-    payload:
-      data:
-        _state: true
-    properties:
-      url: api.otherapp.org/other/thing
-      method: post
-      data:
-        _payload: data
-```

package/content/controls/while.md

@@ -1,46 +0,0 @@
-# :while
-
-```
-({:while: boolean, :do: routine}): void
-```
-
-The `:while` control implements a while loop within a routine. The routine defined in the `:do` key will be repeated as long as the test defined using the `:while` key is true.
-
-#### Keys
-
-- `:while: boolean`: __Required__ - The test that will determine whether or not the defined routine should execute again.
-- `:do: routine`: __Required__ - The routine to run while the test condition holds.
-
-The `:while` condition is evaluated fresh before every iteration, against the routine's current `state` and `steps`. This is how the loop terminates - the routine in `:do` changes the state or step results that the condition reads.
-
-Unlike `:for`, a `:while` loop does not index the step results of its body. A `:while` has no item to index by, so each iteration overwrites the previous iteration's step results, and `_step: my_step` inside or after the loop reads the value from the latest iteration.
-
-There is no iteration cap and no timeout. A condition that the routine in `:do` never falsifies loops forever, exactly as it would in JavaScript.
-
-#### Examples
-
-###### Simple Example
-```
-- :set_state:
-    count: 0
-- :while:
-    _lt:
-      - _state: count
-      - 5
-  :do:
-    - :log:
-        _state: count
-    - :set_state:
-        count:
-          _sum:
-            - _state: count
-            - 1
-```
-Logs:
-```
-0
-1
-2
-3
-4
-```