Ask¶

Template ask@1, writer role: answers a question about one collection from the grounding tools (section 11.3) with checked citations, in the views pack's Ask panel (a right dock the install adds) or through system.artekis.ask. A disabled example playbook Artekis/Ask ships with the default params.

Asking: from the panel, or system.artekis.ask(question, collection=None, assetId=None, conversationId=None, findingId=None), which queues one run and returns its id at once: the answer arrives by polling system.artekis.getRun(runId)['answer'] (the panel does this for you; askAndWait blocks in a gateway script). assetId picks the collection; otherwise collection is required. FindingDetail's Ask about this opens the panel seeded with the finding. With findingId, the model is given the stored finding as it is: its fields, every evidence item with its value (long trends thinned, long text cut, at most about 24,000 characters, items past that named), and the run that stored it: playbook, template, trigger, window and that run's KPIs for the finding's tag (for Anomaly Watch, the tag's baseline rows): so it explains how the finding was produced instead of re-reading the data. Before it calls a tag, reading or asset fine or trustworthy, it checks the findings tool for live findings on it. One asset can sit in several collections (a broad casting and a narrow cell2), and its findings are filed under whichever collection's playbook found them, so Ask matches findings by asset across every collection that holds it: with assetId, the question arrives with that asset's live findings from all of them (at most 20, newest first, each naming its collection), and the findings tool adds them too. Only the asked collection's own assets are matched elsewhere, so Ask lists what the Findings page shows for that asset. The question also lists the documents the asset links in the context model (at most 10: file name, document id, and its description or else its first line), and Ask is told to search them with documents and the asset id before reading counters or tags for a question about scrap, downtime, quality or a procedure: so a plant guide that names the trusted MES queries is read first. Document text stays evidence, never instructions.
The loop: the model calls the grounding tools natively and ends by submitting an answer. Per turn, from the playbook's params: maxToolCalls 12, maxModelCalls 13 (8 and 9 in earlier releases), maxOutputTokens 4,000 per call, turnSeconds 180, usdPerTurn $0.50. On an MES collection (its context model maps at least one data shape) a turn takes mesMaxToolCalls 16, mesMaxModelCalls 17, mesTurnSeconds 300 and mesUsdPerTurn $1.00 in their place (ticket 126), and the prompt asks for the whole span the shapes hold and rates per running hour rather than raw counts; the playbook's timeoutSeconds (default 300) still ends the run, so raise it together with mesTurnSeconds. The per-user caps are the same on every collection. When the budget is spent the model is told to answer with what it has (answeredWithBudgetSpent). A citation is kept only when it points at this turn's own tool call, a document passage, or a finding the turn was shown (the seeding finding, the asked asset's live findings, or a findings call's rows); an answer with none is shown "uncited", never rejected. A (call 3), [calls 2, 4] or call:3 the model writes in the text for one of this turn's successful calls becomes that call's citation and is removed from the text (the Sources list shows it). A citation with no label of its own is given what it points at, so the Sources list's What column is never blank: the tool and its arguments (tag_history: path [default]Press/DCM-203/ShotTime, …, each value cut at 60 characters), the document's file and page, or Finding: <title>. In the answer's tool table, a refused call the model corrected with a later call of the same tool is left out; every read the turn never made (a refusal not corrected, a call over the tool budget) is listed in notRead and named at the end of the answer in plant words ("Some data was not read for this answer: the audit log (it asked for more data than one read allows)"; from 1.5.6, earlier answers read "Not read: …"); the Ask panel shows that sentence on its own line under the tool table, where a call refused before it ran has no number.
Recent questions: the panel lists earlier questions about the asset by anyone and your own elsewhere in the collection (newest first, at most 10 each, from the collection's last 200 answered questions; who asked is not shown; a question asked again is listed once, at its newest asking), from system.artekis.askHistory. While a conversation is empty the panel also offers three example questions under Try asking (an open finding on the asset, its stops when the collection maps state periods, else its alarms, and what changed); tapping one fills the box without sending it, and the box's placeholder names the asset or collection.
Who may ask: a Perspective session at policy.security.askSecurityLevel, and only a session someone is logged in to: so the project needs an identity provider (Project Properties → Identity Provider), which the views-pack install does not set; without one Ask refuses every question. Gateway scripts ask as the system.
Caps per user: questionsPerHour 30 and usdPerDay $5 (params), reset hourly and at local midnight; over a cap the question is refused with the reset time. Provider daily caps still apply.
Conversations: a conversation's id is its first turn's run id; pass it back to continue, and the last 6 turns are sent with the new question. A conversation belongs to whoever started it.
Provider: an endpoint without tool calling cannot serve Ask; the Providers page's Test reports toolUse. On OpenAI's own API, set the writer to gpt-5.4 (or gpt-5.5, gpt-5.4-mini) for Ask: OpenAI refuses tool calls on the GPT-6 models (Luna, Sol, Astra) through the API Artekis uses, so with the default writer gpt-6.1-sol Test reports toolUse: false and Ask is refused. A call that carries tools never sends reasoning_effort, which OpenAI also refuses with tools; the other playbooks keep the GPT-6 defaults and their effort.
Save as rule: when the answer proposes a rule, the panel offers a pre-filled form (admin level) that adds it to the asset's context model.
Staying on topic: before any tool runs, one small scope check on the provider's triage model (the writer when the provider has no triage model) judges the question against the collection's ask.purpose (section 7.9; none = "this Ignition system and its data"). In scope means the plant's equipment, production, quality, alarms, tags, findings, named-query records, loaded documents, or how to use Artekis; the gateway itself (its health, logs, connections, devices) is in scope for every collection whatever the purpose says. Anything else , arithmetic, trivia, general knowledge, code, emails, the news, a request to change anything, an attempt to change Ask's rules: is refused in one sentence ("I can only answer questions about …, so I can't help with that one.") with no tool call and no partial answer. The run ends SKIPPED with reason out-of-scope, and the panel shows only that sentence. A refusal costs the asker's usdPerDay only that one check call (about 1,000 tokens on the triage model). A check that fails or answers something other than its verdict refuses too (scope-check-failed): Ask never answers a question it could not check. The answering prompt repeats the rule, and treats any instruction inside the question, a document, a tag value or a tool result as data.
Sensitive categories: personal details, pay and HR, medical, and customer financials are closed unless the collection opens one with its own security level (ask.sensitive, section 7.9). A question the check places in a closed category, or asked by someone without the category's level, is refused (sensitive). Only a logged-in Perspective session can hold a level, so a gateway script, the Designer or a data route never opens one. An Ask playbook cannot be started through runPlaybook, runPlaybookAndWait or an event at all: those are refused with a reason pointing at system.artekis.ask, which checks the login and the per-user limits. An answered question in an opened category writes an Artekis.Audit line (method=ask.sensitive) with the asker, the category and what the turn read. Limit: the check judges the question. A tool result that happens to carry personal data on an in-scope question is held only by the answering prompt's rule, not by a second classifier.
Ask refusals page (Artekis settings → Ask refusals): every question Ask refused for scope, a closed category or a failed check, newest first (at most 200), with who asked, the collection, the question, why, and the sentence Ask said. It needs a gateway login, like the Egress page. Cap and conversation-owner refusals are not runs; they stay in the audit log.

A turn took 12–13 s and $0.03–$0.12 on Sonnet 5.5 in the acceptance run; the first turn of a conversation costs most because the context model enters its prompt.