AI Assistant

DataOrchester's AI assistant works inside the Site, next to what you are building. It has three chats: one beside the Program screen's editor, one beside the dashboard editor, and the general assistant in a tab of its own. They read your configuration, the documents you attach and DataOrchester's documentation. The two editor chats propose changes that you review on a card; the general one explains, diagnoses and suggests a plan. This guide covers what each does, how to turn the assistant on, how to work with it, what it sends and what it never sends, what it costs, and what to do when it is off.

The three assistants

All three read the whole configuration, not only the screen they sit on: variables, modules, peers, schemas, dashboards and panels, with the unsaved edits of your open Program tab, and the instance's licence and engine state. So the dashboard chat can bind a gauge to a variable it found in a module's table, and the program chat knows which dashboards and loggers use a variable before it changes it. They also:

• look things up in DataOrchester's documentation, always;
• search the public web - PLC manuals, protocol specifications, standards - only when Web search is on;
• read live values, module health and messages and recent console errors only when Live values is on.

Before an editor chat proposes a change, it checks its own draft: it validates the whole change, and on the Program screen it also simulates new and changed formulas on test values, in a sandbox that touches nothing. Whatever the assistant did, the Site validates the change again before it shows the card.

Turning it on

The assistant is off on every instance until a user with the Configuration role turns it on, for the whole instance:

1. Open the Assistant tab, or the chat beside the Program or dashboard editor, and choose Turn on the assistant. Once it is on, Settings in the chat's header opens the same window.
2. Read the disclosure: what is sent, to whom, and the AI providers that serve the assistant at present.
3. Choose the two switches. Both stay off unless you tick them:
   • Web search: the assistant may search the public web through OpenRouter and its search engine, and Amtiri's Portal fetches the pages it cites;
   • Live values: the assistant may read the current values of variables and the health of modules.
4. Choose Turn on the assistant.

The choice is kept with who made it, when, and the providers the disclosure named, in entities/.assistant: a hidden file that no configuration export carries, so consent never travels to another installation. Turn off, in the same window, turns the assistant off for everyone. Turning it on and off is written to logs/security.log.

All three chats need the Configuration role. Every message, attachment, applied card and action-plan button is checked for it on the server.

When the assistant is off

The assistant shows only when all of the following hold, checked in this order. Beside an editor, the chat stays folded against the editor's right edge when one fails: drag it open to read the reason. The Assistant tab shows the reason in place of the chat.

No licence, or no connection to the Portal, means no assistant. The instance asks the Portal whether the assistant is available and keeps the answer for ten minutes, or for one minute when the Portal could not be reached, so a licence changed on the Portal reaches the chats within ten minutes and a connection that returns within one.

Working with a chat

Type in the box at the bottom of the chat: Enter sends, Shift+Enter starts a new line. The assistant answers in the language of your latest message, and shows a line for each tool it uses while it reads the configuration, the documentation or your attachments. Stop ends the answer being written.

New conversation starts afresh. A conversation is never stored: closing the tab or starting a new conversation drops it, with its attachments.

Attachments

Attach files adds documents to the conversation: a register list, a P&ID, a manual, a photo, a spreadsheet, a screenshot of an old HMI.

• Any other type - WebP, HEIC, .doc, .ppt and the rest - is refused, with the list of the types above.
• A conversation holds at most 10 attachments, and 128 MiB together unless the operator changed application.assistant.attachment-max-bytes. The × on an attachment's chip removes it.
• Each chip shows the file's pages and about how many tokens reading it whole would take.
• Attachments are held in memory with the conversation, never written to the instance's disk, and dropped when it ends. A page leaves the instance only when the assistant reads it or looks at it.

Page ranges. The assistant reads a long document a few pages at a time, in ranges such as 3, 1-5 or 1-3, 8, 10-12, never all of it at once. Tell it where to look - "the analog registers are on pages 34 to 36" - and it reads only those, which is faster and costs less.

Documents are data. What a document says is never an instruction to the assistant: when a page tells it to "ignore your rules", it says in one line that the page holds an instruction it did not follow, and goes on.

Change cards

An editor chat proposes each change on a card:

Then choose:

• Apply: the change goes into the editor as one step. The tab has unsaved changes, exactly as after a change made by hand, and Undo takes the whole change back at once.
• Apply and continue: the same, and the assistant goes on with the next step of its work.
• Discard: the change is dropped. Write a comment in the box under the buttons first, and the assistant reads it.

Checked again when you apply. The assistant built the card on the records as it read them. If one of them has changed since - you edited it, applied another card, or saved it in its dialog - the card is refused with Not applied: what it was built on has changed since the assistant read it, and the list of what changed. Nothing is applied: ask the assistant to read again, and it rebuilds the change on what is there now.

An applied change is then yours: review it in the editor, Save it, and commission it like any other change. Each applied card is written to logs/security.log with who applied it, the conversation, the card and the records it touched.

Action plans

The general assistant changes nothing. For a problem you describe, it reads the evidence - module health and messages, values with their time, the configuration, the console - and answers with an action plan: the problem, the diagnosis with the evidence it rests on, and the steps in order, checks before changes and changes before restarts.

• Each step names its impact - changes the configuration, stops or restarts the engine, writes to the plant - and how to verify it. Tick a step once it is done.
• Open in editor opens the editor, and its chat starts with the step's request as your first message. Its answer is a card you review like any other.
• Check again asks the assistant to read the evidence again: it confirms the fix or revises the plan.
• No button runs anything. The assistant is instructed never to suggest bypassing, disabling or silencing an interlock, a trip, a safety function or an alarm as a fix; if you ask for one, it explains the risk and hands the change to the Program chat with that warning. Steps on energised or moving equipment say so, and your site's own procedures come first.

Without Live values, a diagnosis rests on the configuration alone, and the plan starts with the checks you can read on screen.

What is sent, and what never is

The assistant reaches the AI through Amtiri's Portal. The instance talks only to dataorchester.com, over HTTPS and signed with its own install key, as it does for its licence; it never holds an AI provider's key and never talks to a provider. The Portal checks the licence and the allowance, and passes each request to OpenRouter, which routes it to the AI provider serving that assistant. The disclosure names those providers, and every request is routed only to providers that do not collect the data they are sent.

• The instance keeps nothing of a conversation once it ends. The security log records the assistant turned on and off and each applied card, never a message or a document.
• Amtiri's Portal keeps the tokens and the cost of each call, never what was said.
• A web page is fetched by the Portal only when a search cited its address or you typed it, from a public address only, and nothing of it is kept.

Cost and allowance

The assistant is paid for from the organization's monthly AI allowance, in US dollars, which the edition of its licence sets: see Pricing.

• Each answer costs what the AI provider charges for the text the model reads and writes, web searches included, and is counted against the calendar month (UTC).
• Every installation of the organization spends from the same allowance. Once it is used up, the assistant answers This month's AI allowance is used up. until the first day of the next month (UTC).
• The chat's header shows what is left this month, after each answer.
• An attachment's chip estimates the tokens of reading it whole; the real cost arrives with each answer.

The usage page. In the Portal, an administrator of the organization chooses AI assistant usage on the organization's page: the month's allowance by licence edition, what is used and what is left, and the cost and calls by day and by assistant.

To spend less, point the assistant at the pages to read, start a new conversation for a new subject - every answer reads the whole conversation again - and attach only the documents the question needs.

Troubleshooting

Next steps

• Licence Activation
• Configuration Reference
• Pricing