Gateway scripts: raylux.ai

A gateway script can ask Iris one question and use the answer: classify a free-text maintenance note, summarize yesterday's alarms for a shift report, turn a table of numbers into a sentence. It is off until an administrator turns it on, and it can never change the plant.

You need the license module aiCore and the Allow gateway scripts to call Iris switch on, under Security › Iris AI › Gateway scripts (Turning Iris on).

raylux.ai.ask

import raylux

try:
    text = raylux.ai.ask(
        "Summarize these readings in one sentence for the shift log.",
        data={"tank1_level": 42.5, "pump2_running": True},
        max_tokens=200,
    )
except raylux.ai.AiError as e:
    text = "(no summary: %s)" % e.code

Argument	Meaning
prompt	What to ask. 1 to 16 KB.
data	Optional: a dict, list or string. It is sent as untrusted data, redacted, and cut at 32 KB.
system	Optional extra instruction, up to 4 KB.
max_tokens	1 to 4096, default 512.
timeout	Seconds, 1 to 60, default 20.

It returns the reply as text. The model gets no tools: it cannot look anything up, so it knows only what you put in the prompt and data. And it never writes: there is nothing in the call that could.

It makes the script wait for the model, so it may be called only in a Startup, Scheduled or Tag Change script. In any other script (a transform, a binding, a component event, a report data source) it raises AiError with code CONTEXT. While a script waits, the wait does not count against the script's time limit.

Errors

raylux.ai.AiError has a .code and a .message:

.code	Means
DISABLED	The switch is off, or there is no provider.
NOT_LICENSED	The license lacks aiCore.
BUDGET	The scripts' token budget is used up.
RATE	The scripts' call rate is exceeded, or too many are waiting.
TIMEOUT	The model did not answer in time.
PROVIDER	The model failed or was unreachable.
CONTEXT	Called from a script type that may not wait.
INVALID	An argument is out of range or data cannot be turned into JSON.
UNAVAILABLE	Iris is not running.

Handle them. A script that lets an AiError escape simply fails that run, like any other error.

raylux.ai.propose_tag_write

proposal_id = raylux.ai.propose_tag_write("[DEFAULT]Tank1/Level", 10.0, "Level is high after the batch.")

It files a proposal to write a tag and returns its number. Nothing is written. A person approves it under Iris Proposals (Approvals). It is refused unless AI may propose tag writes is on, and tools that file proposals exist only while tag access is restricted. The proposer is shown as script:gateway/<script name>.

Limits and records

• All gateway scripts share one identity, script:gateway, with its own budget: 30 calls a minute by default, and a token limit you can set.
• At most two calls wait at once. A third is refused with RATE, not queued, so a few waiting scripts cannot take the whole script pool.
• Every call writes an audit row (AI_SCRIPT_ASK) and a transcript, both naming the script.
• What you pass in data leaves the gateway if the model is in the cloud. Do not put in anything you would not send there.