Skip to content
Version 2026.25

Scripts: raylux.ai ​

Any 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 scripts to call Iris switch on, under Security › Iris AI › Scripts (Turning Iris on). That is all: which scripts call Iris is the designer's decision. A component script an operator presses does not need the separate operator-chat license.

raylux.ai.ask ​

python
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
ArgumentMeaning
promptWhat to ask. 1 to 16 KB.
dataOptional: a dict, list or string. It is sent as untrusted data, redacted, and cut at 32 KB.
systemOptional extra instruction, up to 4 KB.
max_tokens1 to 4096, default 512.
timeoutSeconds, 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 works in every kind of script: gateway scripts of every type (Shutdown included), component event scripts and message handlers, transforms and script bindings, report data sources, alarm-pipeline Script nodes, and project scripts called from them. It makes the script wait for the model; the wait does not count against the script's time limit, so a transform's 5 seconds still apply once the answer is back. A binding waits as long as the model takes, so for a value many screens show, ask in a Scheduled script and write the answer to a tag. A Shutdown script's call must finish within the 30 seconds Shutdown scripts get; after that Iris stops and the call ends.

Errors ​

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

.codeMeans
DISABLEDThe switch is off, or there is no provider.
NOT_LICENSEDThe license lacks aiCore.
BUDGETThe scripts' token budget is used up.
RATEThe scripts' call rate is exceeded, or too many are waiting (two Iris calls, or half the gateway's script threads on any outbound call).
TIMEOUTThe model did not answer in time.
PROVIDERThe model failed or was unreachable.
CONTEXTCalled outside a script run: from a strict-sandbox tool, or from a thread the script started itself.
INVALIDAn argument is out of range or data cannot be turned into JSON.
UNAVAILABLEIris 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 ​

python
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> for a gateway script;
  • script:gateway-run/alarm pipeline script (or report data source) for other work the gateway does on its own;
  • script:user/<user>/<kind> when a person triggered the script, for example script:user/operator/component event script.

Each proposer has its own limit on pending proposals.

Limits and records ​

  • Every script draws from one shared AI budget. All scripts, whatever their type, call as one identity, script:gateway: 30 calls a minute by default, and a token limit you can set. A binding on a busy screen or a button pressed often spends the same budget as your gateway scripts.
  • 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, or for a script a person triggered its kind and that person.
  • 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.