@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/concepts/selectors.md

@@ -0,0 +1,143 @@
+# Driving Selectors
+
+Selector blocks — `Selector`, `MultipleSelector`, `ButtonSelector`, `RadioSelector`,
+`CheckboxSelector`, `SegmentedSelector` and the list-style `ListSelector` — can be driven
+two ways. Both produce the same kind of value in [`state`](/page-and-app-state); pick the
+one that fits where your data comes from.
+
+## Way 1 — `options` (label / value pairs)
+
+Provide an array of primitives, or `{ label, value }` objects. The `value` is stored in
+state and the `label` is shown to the user. This is ideal when you write the options by
+hand, but when the data comes from a [request](/connections-and-requests) you usually have
+to build the `label` and `value` fields in the query first.
+
+```yaml
+id: plan
+type: Selector
+properties:
+  options:
+    - label: Starter
+      value: 1
+    - label: Pro
+      value: 2
+    - label: Enterprise
+      value: 3
+```
+
+## Way 2 — `data` + `html`
+
+Pass the raw rows in `data` and render each option's label with an `html`
+[Nunjucks](/custom-html) template. There's no need to reshape the data into label/value
+pairs — point the selector straight at a request's results.
+
+- **`html`** — the template for each option label. The context exposes `item` (the row)
+  and `index`.
+- **`valueKey`** — the field stored as the value when an option is selected. Omit it to
+  store the whole row.
+- **`primaryKey`** — the field used to match the current value back to an option for
+  highlighting. Defaults to `valueKey`; set it when you store the whole row but a single
+  field (such as `id`) uniquely identifies it.
+
+```yaml
+id: plan
+type: Selector
+properties:
+  data:
+    - id: 1
+      name: Starter
+    - id: 2
+      name: Pro
+    - id: 3
+      name: Enterprise
+  html: '{{ item.name }}'
+  valueKey: id
+```
+
+With `valueKey: id`, selecting "Pro" sets `state.plan` to `2`.
+
+## Tree selectors
+
+`TreeSelector` (single) and `TreeMultipleSelector` (multiple) are searchable dropdowns that
+present the options as a tree. They use the same model plus a **`parentKey`**: build a flat
+`data`/`options` array where each row has a `primaryKey` (its own id) and a `parentKey`
+whose value equals the parent row's `primaryKey`. Rows whose `parentKey` is empty or points
+at no row become tree roots. `valueKey` is still the stored value; `primaryKey`/`parentKey`
+only build the hierarchy.
+
+```yaml
+id: category
+type: TreeSelector
+properties:
+  primaryKey: id
+  parentKey: parentId
+  valueKey: id
+  html: '{{ item.label }}'
+  data:
+    - { id: 1, label: Electronics }
+    - { id: 2, label: Phones, parentId: 1 }
+    - { id: 3, label: Laptops, parentId: 1 }
+```
+
+(The `TreeInput` block is a different, inline antd `Tree` — not a dropdown.)
+
+## Controlling the selection from state
+
+Because the value lives in state under the block's id, you can drive the selection with
+[`SetState`](/SetState). The selector highlights the option whose `primaryKey` (or
+`valueKey`) matches the value you set.
+
+```yaml
+id: select_pro
+type: Button
+events:
+  onClick:
+    - id: select_pro
+      type: SetState
+      params:
+        plan: 2 # highlights the "Pro" option
+```
+
+For the multi-value selectors (`MultipleSelector`, `CheckboxSelector`) the value is an
+array of keys, so `SetState` with `[1, 3]` selects those two options.
+
+## Large datasets — the `setData` method
+
+Anything placed in a block's `properties` (including `data` and `options`) is re-parsed
+and re-serialized by the engine on **every** update cycle — once per keystroke, anywhere
+on the page. For a few hundred rows that's fine, but a selector holding tens of thousands
+of rows in `properties` makes the whole page feel sluggish.
+
+Every selector exposes a **`setData`** method instead. Call it with
+[`CallMethod`](/CallMethod) from the block's **`onMount`** event — after a request has
+loaded the rows — to push the dataset straight into the block. The data is held inside the
+block and never enters `properties`, so the engine has nothing large to parse or
+serialize: other inputs on the page stay responsive no matter how big the list is.
+`ListSelector` additionally virtualises its rows, so only the visible cards are ever in
+the DOM.
+
+Use the block's `onMount` (not the page's `onInit`): `onInit` runs before any block has
+mounted, so the `setData` method does not exist yet.
+
+```yaml
+id: people
+type: ListSelector
+properties:
+  valueKey: id
+  html: '{{ item.name }}'
+events:
+  onMount:
+    - id: load_rows
+      type: Request
+      params: get_rows
+    - id: fill
+      type: CallMethod
+      params:
+        blockId: people
+        method: setData
+        args:
+          - _request: get_rows
+```
+
+The selector still falls back to `properties.data` / `properties.options` until `setData`
+is called, so small lists need no extra wiring.

package/content/connections/amazonredshift.md

@@ -0,0 +1,176 @@
+# Amazon Redshift
+
+The [Knex](/Knex) connection can be used to connect to a [Amazon Redshift](https://aws.amazon.com/redshift) database.
+
+## Connections
+
+Connection types:
+  - Knex
+
+### Knex
+
+#### Properties
+- `client: enum`: __Required__ - Should be `redshift` to connect to Amazon Redshift.
+- `connection: object | string`: __Required__ - Connection string or object to pass to the [`pg`](https://www.npmjs.com/package/pg) database client.
+- `useNullAsDefault: boolean`: If true, undefined keys are replaced with NULL instead of DEFAULT.
+
+#### Examples
+
+###### Connection object:
+```yaml
+connections:
+  - id: redshift
+    type: Knex
+    properties:
+      client: redshift
+      connection:
+        host:
+          _secret: REDSHIFT_HOST
+        database:
+          _secret: REDSHIFT_DB
+        user:
+          _secret: REDSHIFT_USER
+        password:
+          _secret: REDSHIFT_PASSWORD
+```
+Environment variables:
+```
+LOWDEFY_SECRET_REDSHIFT_HOST = examplecluster.XXXXXXXXXXXX.us-west-2.redshift.amazonaws.com
+LOWDEFY_SECRET_REDSHIFT_REDSHIFT_DB = db
+LOWDEFY_SECRET_REDSHIFT_USER = user
+LOWDEFY_SECRET_REDSHIFT_PASSWORD = password
+```
+
+## Requests
+
+Request types:
+
+- KnexBuilder
+- KnexRaw
+
+### KnexBuilder
+
+#### Properties
+
+- `query: object[]`: **Required** - SQL query builder array. An array of objects, with a single key which is the name of the knex builder function. The value should be an array of arguments to pass to the builder function.
+- `tableName: string | object`: The name of the table to query from.
+
+#### Examples
+
+###### Build a query:
+
+```yaml
+id: knexBuilder
+type: KnexBuilder
+connectionId: knex
+payload:
+  name:
+    _state: name
+properties:
+  query:
+    - select:
+        - '*'
+    - from:
+        - users
+    - where:
+        - name
+        - _payload: name
+```
+
+###### Using `tableName`:
+
+```yaml
+id: knexBuilder
+type: KnexBuilder
+connectionId: knex
+payload:
+  name:
+    _state: name
+properties:
+  tableName: users
+  query:
+    - select:
+        - '*'
+    - where:
+        - name
+        - _payload: name
+```
+
+###### Aliases:
+
+```yaml
+id: knexBuilder
+type: KnexBuilder
+connectionId: knex
+properties:
+  tableName:
+    a: tableA
+    b: tableB
+  query:
+    - select:
+        - aField: 'a.field'
+        - bField: 'b.field'
+    - limit:
+        - 1
+```
+
+### KnexRaw
+
+#### Properties
+
+- `query: string`: **Required** - SQL query string.
+- `parameters: string | number | array | object`: SQL query parameters.
+
+#### Examples
+
+###### Simple raw query:
+
+```yaml
+id: knexRaw
+type: KnexRaw
+connectionId: knex
+properties:
+  query: SELECT * FROM "my_table";
+```
+
+###### Query with named parameters:
+
+```yaml
+id: knexRaw
+type: KnexRaw
+connectionId: knex
+payload:
+  selected_name:
+    _state: selected_name
+properties:
+  query: select * from users where name = :name
+  parameters:
+    name:
+      _payload: selected_name
+```
+
+###### Query with positional parameters:
+
+```yaml
+id: knexRaw
+type: KnexRaw
+connectionId: knex
+payload:
+  selected_name:
+    _state: selected_name
+properties:
+  query: select * from users where name = ?
+  parameters:
+    - _payload: selected_name
+```
+
+###### Reference a `.sql` file:
+
+```yaml
+id: knexRaw
+type: KnexRaw
+connectionId: knex
+properties:
+  query:
+    _ref: my_query.sql
+```

package/content/connections/anthropic.md

@@ -0,0 +1,232 @@
+# Anthropic
+
+The Anthropic connection connects to the [Anthropic API](https://docs.anthropic.com/) and provides the `ClaudeAgent` agent type for use with [Lowdefy agents](/agents-introduction).
+
+> The Anthropic connection is provided by the `@lowdefy/connection-anthropic` package, which is included by default.
+
+## Connections
+
+### Anthropic
+
+#### Properties
+- `apiKey: string`: __Required__ - Anthropic API key. Use [`_secret`](/_secret) to reference this securely.
+- `baseURL: string`: Optional base URL for the Anthropic API. Use this to connect to a proxy or compatible endpoint.
+
+###### Connection example:
+```yaml
+connections:
+  - id: anthropic
+    type: Anthropic
+    properties:
+      apiKey:
+        _secret: ANTHROPIC_API_KEY
+```
+
+## Agent Types
+
+### ClaudeAgent
+
+The `ClaudeAgent` supports all [common agent properties](/agents-introduction) plus the following:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `thinking` | object | Extended thinking configuration. The model shows its reasoning before responding. |
+| `thinking.type` | string | Set to `'enabled'` to turn on extended thinking. |
+| `thinking.budgetTokens` | integer | Maximum tokens the model can use for thinking. |
+| `effort` | string | Thinking effort level: `'low'`, `'medium'`, or `'high'`. Simpler alternative to `thinking`. |
+
+> Use `effort` for a simple control or `thinking` for fine-grained token budget control — not both at the same time.
+
+###### Agent with extended thinking:
+```yaml
+connections:
+  - id: anthropic
+    type: Anthropic
+    properties:
+      apiKey:
+        _secret: ANTHROPIC_API_KEY
+
+agents:
+  - id: analyst
+    type: ClaudeAgent
+    connectionId: anthropic
+    properties:
+      model: claude-sonnet-4-20250514
+      thinking:
+        type: enabled
+        budgetTokens: 10000
+      instructions: |
+        You are a data analyst. Think carefully through each
+        question before answering. Show your reasoning.
+      maxSteps: 8
+    tools:
+      - query-analytics
+      - get-dashboard-data
+```
+
+###### Agent with effort level:
+```yaml
+agents:
+  - id: support_agent
+    type: ClaudeAgent
+    connectionId: anthropic
+    properties:
+      model: claude-sonnet-4-20250514
+      effort: high
+      instructions: |
+        You are a customer support agent. Search the knowledge
+        base before answering questions. Be concise and friendly.
+      maxSteps: 5
+      temperature: 0.3
+    tools:
+      - search-knowledge-base
+      - get-account-info
+      - endpointId: create-ticket
+        confirm: true
+```
+
+## Requests
+
+Request types:
+
+- GenerateText
+- GenerateObject
+
+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.
+
+For multi-step tool use, see [agents](/agents-introduction) instead.
+
+### 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.
+- `maxOutputTokens: number`: Maximum number of tokens to generate.
+- `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
+```