AI

Work in progress

The AI operation is still in development. The schema (inputs, outputs, and properties) below reflects the current skeleton; the runtime implementation does not yet call any backend. Refer to this page for the shape of the node; behaviour will change as the backends land.

The AI operation calls a language model with a prompt and optional context inputs, and produces a response and usage metadata. A single node supports three interchangeable backends — a local model, a hosted API, or an existing personal subscription — selected via the Backend property.

Inputs

Port	Type	Required	Description
> (Gate)	Any	No	When connected, a false or Nil value stops the path. See Gate Inputs.
Prompt	String	No	Overrides the Prompt Template property when connected.
System	String	No	Overrides the System Prompt property when connected.
Context (dynamic, up to 10)	User-configurable	No	Additional context values referenced by {{inputN}} placeholders in the prompt template. Use the + / - buttons on the node to add or remove Context inputs. Accepted MessagePack types per port are set in the Node’s Settings panel — see Setting Port Types.

Outputs

Port	Type	Description
Response	String	The model’s free-text reply. Always populated on success.
Structured	User-configurable	Parsed JSON result when a Response Schema is configured; Nil otherwise. Accepted MessagePack types set in the Node’s Settings panel.
Usage	Map	Metadata about the call: {tokens_in, tokens_out, latency_ms, provider, model}.

Properties

Name	Type	Default	Description
Backend	StackedDataSet	Local	Selects one of three variants — Local, API, Subscription — each with its own fields (see below).
System Prompt	TextBox	""	Default system prompt. Overridden by the System input when connected.
Prompt Template	TextBox	""	Prompt template with {{input1}}, {{input2}}, … placeholders for Context inputs. Overridden by the Prompt input when connected.
Response Schema	TextBox	""	Optional JSON schema. When set, the structured output port is populated and the response is validated against it.
Temperature	Number	0.2	Sampling temperature. Lower values are more deterministic.
Max Tokens	Integer	1024	Upper bound on the response length.
Request Timeout	Duration (seconds)	30	Per-call HTTP timeout.
Cache	Boolean	false	When true, responses are cached by a hash of prompt + inputs + model, and cache hits skip the backend call.
On Error	Combo	Stop this branch	Per-op On Error verb (Stop this branch / Continue with the last value / Continue with the fallback). See the Error Handling guide.

Backend variants

The Backend property is a StackedDataSet — only the fields for the selected variant are shown and stored.

Local — HTTP call to a locally hosted model (Ollama, llama.cpp, LM Studio).

Field	Type	Description
Endpoint URL	TextLine	Base URL of the local model server.
Model	TextLine	Model identifier (e.g. llama3.1:8b).

API — HTTPS call to a hosted provider using an API key.

Field	Type	Description
Endpoint URL	TextLine	Provider endpoint. May be left empty to use the driver default.
Model	TextLine	Model identifier (e.g. claude-opus-4-6).
API Key	SecretValue	Provider API key. Stored as a secret; never written to the task file in plaintext.

Subscription — reuses an existing Claude or ChatGPT subscription via the same sign-in flow that tools like Claude Code / Codex CLI use.

Field	Type	Description
Endpoint URL	TextLine	Provider endpoint. Driver default if empty.
Model	TextLine	Model identifier.
User	TextLine	Account identifier.
Password	SecretValue	Account password. Stored as a secret.

On Error governs the answer

This Operation carries no failure setting of its own beyond the verb every Node carries. A call the backend refuses, and a reply that fails the Response Schema, is this Node’s failure: the failure is reported and the Node’s On Error verb resolves the branch — Stop this branch, Continue with the last value, or Continue with the fallback. See the Error Handling guide.

State on Reload

This operation does not persist task-lifecycle state across restarts. When Cache is enabled, responses are kept in the slot-scoped session cache (TTL-bounded) and survive the slot session; they do not persist across slot restarts.

---

How it will work

1. Gate check — If the Gate input is connected, a false or Nil value stops the execution path.

2. Prompt assembly — Combine the System Prompt (or System input if connected) and the Prompt Template (or Prompt input if connected), substituting {{inputN}} placeholders with the connected Context inputs.

3. Cache lookup — If caching is enabled, hash (prompt + inputs + model + backend) and return the cached response if one is present.

4. Backend call — Dispatch the completion request to the selected backend driver (Local / API / Subscription). The driver returns a normalised response.

5. Structured output — If a Response Schema is configured, parse the reply as JSON and validate against the schema. Invalid replies are a failed call, resolved by the Node’s On Error verb.

6. Emit outputs — Set the Response, Structured, and Usage outputs.

---

Use cases

The AI operation fits wherever a flow needs to read, classify, or generate text. The groups below are the ones worth trying first.

Scheduled batch analysis

• Daily telemetry digest — Sensors write to SQLite via MQTT. A Scheduler fires once a day, SQLiteStorage selects the last 24 h, AI summarises trends and anomalies, the reply goes out via email.
• Weekly narrative with continuity — As above, but the AI also reads its own prior weekly summaries so the new digest references trends ("pump 3 is worse than last week"). Exercises the Context inputs and long-context handling.
• Multi-source digest — SQLite + an MQTT-buffered log + a Notes field (human commentary) all feed the AI on separate Context inputs. Shows off dynamic input flexibility.

In-line classifier and router

• Anomaly triage — An MQTT message is fed to AI with a Response Schema of {severity, reason}. The Structured output port drives a Condition/Gate split: crit -> email alert + MQTT publish to alerts/, warn -> Logger, ok -> dropped. The case where AI replaces a brittle rules chain.
• Inbound ticket triage with write-back — A Scheduler polls a tickets table. AI extracts {priority, category, summary, assignee} and writes the classification back to SQLite; high-priority rows go out by email.
• Log-line severity upgrade — A free-text log line is reclassified into your existing severity taxonomy, and the Logger writes it at the corrected level.

Ask your data in plain English

• One-shot question to SQL to answer — AI #1 turns a plain-English question into SQL, SQLiteStorage executes it against a read-only handle, AI #2 narrates the result back in prose. Keep SQL generation validated — treat the generated SQL as untrusted input.
• Conversational — an MQTT question topic + answer topic, with per-conversation state kept in SQLite; each reply feeds back into the next turn via the Context inputs.

Enrichment

• Geocode / address normalisation for free-form location strings where the GPS Location node is not enough.
• Sensitive-data redaction — strip names, phone numbers, email addresses, and similar personal details before Logger / external publish.
• Translation — source language on an input, target language as a node property.

Drafting and generation

• Draft email replies — Incoming email body plus context produces a draft reply body that a human still sends (queue in SQLite first).
• Draft MQTT command payloads — Natural-language instruction produces a structured MQTT payload for downstream actuators. Powerful but risky; gate behind explicit confirmation.

Decision support

• Runbook lookup — Incoming alert plus a Notes-stored runbook produces a recommended action code for a human to approve, not to dispatch autonomously.
• Root-cause hint — Recent SQLite rows plus an alert produce one paragraph of “most likely cause” appended to the email alert.

Out of scope

Autonomous multi-step agents with tool calls, live token streaming to the UI, and model fine-tuning are not in scope for this operation. The AI operation stays single-call and synchronous from the task’s perspective.

---

Throughput & cost notes

Plan for latency

Model calls are typically 200 ms—10 s depending on backend and model. An AI node will be the slowest thing in any flow that contains it. Avoid wiring it directly to high-frequency triggers such as per-message MQTT streams — use Scheduler, On Change, Hysteresis, or a counter gate to batch or decimate.

Paid backends incur cost per call. The Usage output (tokens_in, tokens_out) can be routed into a Counter and a Condition to stop a task when a budget is exceeded. The Subscription backend incurs no per-call cost from the task’s perspective, but the provider’s rate limits on the underlying plan still apply.

---

Notes

• API keys and subscription passwords are SecretValue fields and are stored encrypted at rest. They are never placed in the task file in plaintext.
• Language models are non-deterministic by default. For reproducible behaviour, set Temperature to 0 and enable Cache, or persist the resulting Response into SQLite as part of the flow.
• Inputs embedded in prompts are untrusted from a security standpoint — treat generated SQL, shell commands, or structured payloads as user input and validate them downstream.