Skip to content

The assistant

How the app's AI assistant works: what it reads, what goes to your AI provider, and how your keys are kept. Its settings and controls: AI.

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 link docs.search gave.

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.

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).