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 Settings > AI. Your AI provider can also write pages.
Settings > AI¶
Route /settings/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; Settings > 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 Settings > 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. - The conversation lives in the open panel: New, closing the panel 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 Settings > AI; no model for <name>:
choose one in Settings > AI; provider answered 401: … (a wrong key); <name>: base URL
must be https.
Privacy¶
- Keys are sealed on the app server (AES-256-GCM, under a key derived from the
server's session key) and kept in the context's state store at
cfg.ai.provider.<USER>, where<USER>is a UUID derived from your sign-in subject (never the subject itself). The browser only ever gets the last 4 characters. Rotating the server's session key (VIRTUFIN_APP_SESSION_KEY) makes the saved keys unreadable: everyone enters them again. - What the provider sees: your questions, the assistant's system prompt (the context name, the view's route, whether you may write), the tool schemas, and the results of the tools it calls — i.e. platform data (worker lists, state values, events) goes to the provider you chose. Pick a provider whose data terms fit the context.
- The relay runs on the app server with your key; your browser never calls the provider directly. Signed-out requests are refused (401), and requests from another origin (403).
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.
What the assistant knows¶
Besides its tools, the assistant reads the Virtufin documentation: every docs site — the platform (docs.virtufin.com, the specs), the api and WorkManager, the worker-devkit and lib, the domain devkits and their workers, the examples, the TUI and this site with the app's API. Two operations give it the docs, for every user (they only read):
docs.search({query, limit?}): the best matching sections, each with its site, title, link and a snippet;docs.read({url}): a section's full text, by a linkdocs.searchgave.
It is told to search the docs before answering a question about how Virtufin or the app works
(terms, configuration, APIs, scripts), to read a section when the snippet is not enough, to link
the pages it used, and to say when the docs do not cover it. Scripts can call the same
operations (vf.docs.search({query: "feed preset"})); AI-generated pages may look things up
too (they get these two tools and no others).
The app server indexes the sites from what each one publishes for its search box
(<site>/search/search_index.json), in memory, reloaded once a day; a site that cannot be
loaded keeps its last index and is named in the answer's problems. Which sites:
VIRTUFIN_APP_AI_DOCS_SITES (comma-separated base URLs), by default all of them. The server
fetches only those sites; it never fetches a URL from a request.