AI¶
The app has an AI assistant: a panel on every view that answers questions about the active context and does things on it, acting only through the operation catalog — the same operations scripts use, with the same checks and the same write gate. It talks to an OpenAI-compatible Chat Completions provider of your choice, set up in Config > AI. Your AI provider can also write pages.
What the assistant knows and what your provider sees: The assistant.
Config > AI¶
Route /config/ai. Your providers on the active context, kept for you only (other
users never see them, and each context keeps its own). Saving here changes nothing on the
platform, so it needs no admin role and does not pass the write gate. Any
OpenAI-compatible endpoint works. The page has two sections.
Provider keys¶
A table of your providers: Name, Base URL, API key, and ✕ to remove a row.
-
Add OpenAI, Add Anthropic, Add OpenRouter, Add Mistral add a row with the provider's name and base URL filled in:
Preset Name Base URL OpenAI openaihttps://api.openai.com/v1Anthropic anthropichttps://api.anthropic.com/v1OpenRouter openrouterhttps://openrouter.ai/api/v1Mistral mistralhttps://api.mistral.ai/v1 -
Add other adds an empty row for any OpenAI-compatible base URL.
- Save keys saves the table. A key you type goes to the app server once and is kept there sealed; the page never sees it again: afterwards the key field says set (…abcd); type to replace (the last 4 characters). Leave it empty to keep the saved key.
Rules the server checks on save (the error names the provider):
- a name, unique, and not
org(reserved for the org provider); at most 10 providers; - the base URL must be
https://, carry no credentials, and resolve to a public address (not a private, loopback or link-local one): the server calls it, and must not be made to call into the cluster.
Model¶
The models your keyed providers list (the provider's GET <base URL>/models, at most 2000
each), and the org provider's model if the app has one, in a table: Provider,
Model, Input / 1M, Output / 1M (USD per million tokens), Context (the
context window), and Use.
- Use makes that provider your default with that model; the line above the table says
Using
<provider>·<model>— $… in · $… out per 1M tokens · …k context. The row shows In use. - Filter models narrows the table by words; Reload lists the models again.
- Below the table, pick a provider and or type a model id, then Use, for a model the provider does not list.
- A provider whose list fails is named with its error; the others still show.
Prices come from LiteLLM's published price list (model_prices_and_context_window.json,
MIT), loaded by the app server — nothing of LiteLLM runs, the list is data. The server
loads it from VIRTUFIN_APP_LLM_PRICES_URL (default
https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json),
keeps it a day, and after a failed load keeps the last list and tries again after
10 minutes; without any list the page says Prices unavailable: … and shows –. A model id
is looked up as given, as openrouter/<id>, without its vendor prefix, and with dots as
dashes (claude-sonnet-4.5 → claude-sonnet-4-5); a model the list does not name shows
–.
The org provider¶
The deployment may configure one provider for everyone: VIRTUFIN_APP_AI_BASE_URL,
VIRTUFIN_APP_AI_MODEL and VIRTUFIN_APP_AI_API_KEY on the app server (all three). It is
called org; Config > AI says The app also has an org provider (model …) and lists its
model, which you can Use. Without a provider of your own, the assistant uses it.
The assistant panel¶
AI in the header (shown once a context is active) opens the panel on the right; it stays open while you move between views and knows the context and the view you are on.
- Header: Assistant, the context, settings (to Config > AI), New (start over), ✕ (close).
- Type a question and press
Enter(or Send);Shift+Entermakes a new line. Examples: Which workers are stopped?, Is any scenario halted?, What do the last order book events of BTC_USDT say? - Each tool call is shown as it happens: ✓ or ✗, the operation (e.g.
workers.list), its input, and the error of a failed one; then the answer. - Each context has its own conversation, kept for this visit: closing the panel keeps it (a question still running finishes into it), switching context shows that context's. New or reloading the page starts over.
How it works. Each question runs a bounded loop (src/ai/agent.ts): the app server
relays the conversation to your default provider's <base URL>/chat/completions
(POST /ai/<context>/chat, at most 120 s per turn); when the model calls tools, your
browser runs them through the operation catalog and sends the results back; at most
8 provider turns per question (then (stopped after 8 rounds of tool calls)). A tool result
longer than 20 000 characters is cut, with a note. A failed tool call goes back to the model
as {ok: false, error}.
Tools = the operation catalog. Every operation of the
catalog is a tool (named with __
for the dot: workers__list), with its description and input schema:
- Reads (e.g.
workers.list,scenarios.list,state.get,topics.read) run at once. - Writes (e.g.
workers.start,triggers.schedule,scenarios.halt) are offered only to admins, and each one passes the write gate as a button would: on a protected context the dialog asks first; a No goes back to the model as declined. Every write lands in Changes. - Read-only users get the read tools only; the model is told so.
- People-only operations (the kill switch) are never offered.
Errors you may see: no AI provider: add one in Config > AI; no model for <name>:
choose one in Config > AI; provider answered 401: … (a wrong key); <name>: base URL
must be https.
AI-generated pages¶
On Config > Pages, Generate… has your AI provider write a new page from a description (e.g. the stopped workers and the lifecycle events), and Change with AI… changes the page you are on (e.g. show only running workers). The model is told the page envelope, the catalog with each component's props schema, the source rules, the naming library's live entities and the readable WorkManager methods — all taken from the code that validates pages — and gets no tools. An answer that does not validate goes back with its errors, at most twice (Fixing errors (attempt 2 of 3)…); the last answer is kept as a draft either way.
- A generated page is a new page of yours in this browser; sharing it stays an admin write.
- A change is shown next to the page until Keep or Discard; it keeps the page's name.
See Make a page.