Set up AI¶
Goal: chat with the AI tab, which runs the platform's operations (workers, feeds, triggers, scenarios, strategies, state, topics) for you.
Prerequisites
- virtufin-tui installed and connected to a context (Getting started).
The
openaiSDK the tab uses is part of the base install. - An API key for an OpenAI-compatible Chat Completions endpoint: OpenAI, DeepSeek or MiniMax (shipped entries), or a local server such as Ollama (no key).
Steps¶
-
Export the key in the shell you start the TUI from. The TUI reads it from its own environment at start:
The variable name is the provider's
api_key_envin~/.config/virtufin/tui/llm_providers.toml(default<NAME>_API_KEY).VIRTUFIN_TUI_AI_API_KEYoverrides the key of whichever provider is active. -
Optional: add or change a provider. Edit
~/.config/virtufin/tui/llm_providers.toml(seeded from the shipped file on first run). Each[providers.<name>]table hasbase_url,api_key_env(orapi_keyinline, discouraged) andmodel. Restart the TUI after editing: the catalog is read at start. -
Open the AI tab: Config top tab (
→until it is selected), then4(AI) in the default layout — orctrl+p, typeAI,Enter. -
Pick the provider: press
P. The picker lists every provider of the catalog and whether its key resolves. The choice is saved asdefault_llm_providerin~/.local/state/virtufin/tui/state.jsonand survives restarts. Without a choice, the first provider (file order) with a key is used. -
Ask something: type in the input at the bottom, press
Enter, e.g. -
Confirm writes. A request that changes something (start a worker, schedule a trigger, ...) opens a dialog naming the operation and its input, e.g.
triggers.schedule {"name": ..., ...}?. Nothing is sent until you answer yes.
Ctrl+L clears the transcript and starts a fresh conversation.
What you should see¶
- The status line above the transcript:
AI provider: <name>, with(busy...)while a turn runs. - Each tool the assistant calls, then its answer, in the transcript.
Troubleshooting¶
| Symptom | Cause and fix |
|---|---|
No LLM provider configured. Set an API key ... and a disabled input |
No provider has a key. Export the variable before starting the TUI, or set VIRTUFIN_TUI_AI_PROVIDER / pick with P. |
AI provider: none configured (press P) |
As above; P shows which providers are ready. |
No providers configured. Edit ~/.config/virtufin/tui/llm_providers.toml. |
The catalog is empty or unreadable: restore the entries shown in AI tab. |
| The model answers in text instead of acting | It is nudged once to call a tool; if it still does not, its text is shown as a normal reply. Use a model with reliable tool calling. |
| A write you expected did not happen | You declined the confirmation (the model is told "not confirmed"), or the input did not fit the operation's schema (refused before anything was sent; the model is told which field). |
| A change on a protected context asks twice | The protected-context guard asks too (Contexts). |
Each turn sends your message and a small state snapshot (active scenario, triggers, topics, workers) to the provider; no secrets. Use the Ollama entry if that state must not leave the host. Full reference: AI tab; the tools: The TUI's API. The web app's equivalent: https://app.docs.virtufin.com/.