@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/connections/mssql.md

@@ -0,0 +1,191 @@
+# Microsoft SQL Server
+
+The [Knex](/Knex) connection can be used to connect to [Microsoft SQL Server](https://www.microsoft.com/en-us/sql-server/sql-server-2019).
+
+## Connections
+
+Connection types:
+  - Knex
+
+### Knex
+
+#### Properties
+- `client: enum`: __Required__ - Should be `mssql` to connect to Microsoft SQL Server.
+- `connection: object | string `: __Required__ - Connection object or string to pass to the [`tedious`](https://www.npmjs.com/package/tedious) database client (knex's `mssql` dialect uses tedious internally).
+- `useNullAsDefault: boolean`: If true, undefined keys are replaced with NULL instead of DEFAULT.
+
+#### Examples
+
+###### Connection object:
+```yaml
+connections:
+  - id: mssql
+    type: Knex
+    properties:
+      client: mssql
+      connection:
+        host:
+          _secret: MSSQL_HOST
+        database:
+          _secret: MSSQL_DB
+        user:
+          _secret: MSSQL_USER
+        password:
+          _secret: MSSQL_PASSWORD
+```
+Environment variables:
+```
+LOWDEFY_SECRET_MSSQL_HOST = database.server.com
+LOWDEFY_SECRET_MSSQL_DB = db
+LOWDEFY_SECRET_MSSQL_USER = user
+LOWDEFY_SECRET_MSSQL_PASSWORD = password
+```
+
+###### Secret connection string:
+```yaml
+connections:
+  - id: mssql
+    type: Knex
+    properties:
+      client: mssql
+      connection:
+        _secret: MSSQL_CONNECTION_STRING
+```
+Environment variables:
+```
+LOWDEFY_SECRET_MSSQL_CONNECTION_STRING = mssql://user:password@database.server.com:1433/db
+```
+
+## 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/mysql.md

@@ -0,0 +1,192 @@
+# MySQL
+
+The [Knex](/Knex) connection can be used to connect to a [MySQL](https://www.mysql.com) database.
+
+## Connections
+
+Connection types:
+  - Knex
+
+### Knex
+
+#### Properties
+- `client: enum`: __Required__ - Should be `mysql2` to connect to MySQL. MySQL uses the [`mysql2`](https://www.npmjs.com/package/mysql2) driver.
+- `connection: object | string `: __Required__ - Connection object or string to pass to the database client.
+- `version: string`:  Set database version.
+- `useNullAsDefault: boolean`: If true, undefined keys are replaced with NULL instead of DEFAULT.
+
+#### Examples
+
+###### Connection Object:
+```yaml
+connections:
+  - id: mysql
+    type: Knex
+    properties:
+      client: mysql2
+      connection:
+        host:
+          _secret: MYSQL_HOST
+        user:
+          _secret: MYSQL_USER
+        database:
+          _secret: MYSQL_DB
+        password:
+          _secret: MYSQL_PASSWORD
+```
+Environment variables:
+```
+LOWDEFY_SECRET_MYSQL_HOST = database.server.com
+LOWDEFY_SECRET_MYSQL_DB = db
+LOWDEFY_SECRET_MYSQL_USER = user
+LOWDEFY_SECRET_MYSQL_PASSWORD = password
+```
+
+###### Connection string:
+```yaml
+connections:
+  - id: mysql
+    type: Knex
+    properties:
+      client: mysql2
+      connection:
+        _secret: MYSQL_CONNECTION_STRING
+```
+Environment variables:
+```
+LOWDEFY_SECRET_MYSQL_CONNECTION_STRING = mysql://user:password@database.server.com/db
+```
+
+## 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/openai-connection.md

@@ -0,0 +1,228 @@
+# OpenAI
+
+The OpenAI connection connects to the [OpenAI API](https://platform.openai.com/docs/) and provides the `OpenAIAgent` agent type for use with [Lowdefy agents](/agents-introduction).
+
+> The OpenAI connection is provided by the `@lowdefy/connection-openai` package, which is included by default.
+
+## Connections
+
+### OpenAI
+
+#### Properties
+- `apiKey: string`: __Required__ - OpenAI API key. Use [`_secret`](/_secret) to reference this securely.
+- `baseURL: string`: Optional base URL. Use this to connect to Azure OpenAI or any OpenAI-compatible endpoint.
+
+###### Connection example:
+```yaml
+connections:
+  - id: openai
+    type: OpenAI
+    properties:
+      apiKey:
+        _secret: OPENAI_API_KEY
+```
+
+###### Azure OpenAI:
+```yaml
+connections:
+  - id: azure_openai
+    type: OpenAI
+    properties:
+      apiKey:
+        _secret: AZURE_OPENAI_API_KEY
+      baseURL: https://my-resource.openai.azure.com/openai/deployments/my-deployment
+```
+
+## Agent Types
+
+### OpenAIAgent
+
+The `OpenAIAgent` supports all [common agent properties](/agents-introduction) plus the following:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `reasoningEffort` | string | Reasoning effort for reasoning models (o3, o4-mini): `'none'`, `'minimal'`, `'low'`, `'medium'`, `'high'`, or `'xhigh'`. |
+| `reasoningSummary` | string | Reasoning summary mode: `'auto'` or `'detailed'`. |
+
+> `reasoningEffort` and `reasoningSummary` only apply to OpenAI reasoning models (o3, o4-mini). They are ignored for standard models like gpt-4o.
+
+###### Standard model:
+```yaml
+agents:
+  - id: assistant
+    type: OpenAIAgent
+    connectionId: openai
+    properties:
+      model: gpt-4o
+      instructions: |
+        You are a helpful assistant for our internal tools.
+        Search the documentation when users ask questions.
+      maxSteps: 5
+    tools:
+      - search-docs
+      - get-user-permissions
+```
+
+###### Reasoning model for complex analysis:
+```yaml
+agents:
+  - id: code_reviewer
+    type: OpenAIAgent
+    connectionId: openai
+    properties:
+      model: o4-mini
+      reasoningEffort: high
+      reasoningSummary: detailed
+      instructions: |
+        You review code changes for bugs, security issues, and
+        performance problems. Be thorough and specific.
+    tools:
+      - get-pull-request
+      - get-file-contents
+```
+
+## 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
+```