Skip to content

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 openai SDK 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

  1. Export the key in the shell you start the TUI from. The TUI reads it from its own environment at start:

    export DEEPSEEK_API_KEY=...      # or OPENAI_API_KEY / MINIMAX_API_KEY
    virtufin-tui
    

    The variable name is the provider's api_key_env in ~/.config/virtufin/tui/llm_providers.toml (default <NAME>_API_KEY). VIRTUFIN_TUI_AI_API_KEY overrides the key of whichever provider is active.

  2. 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 has base_url, api_key_env (or api_key inline, discouraged) and model. Restart the TUI after editing: the catalog is read at start.

  3. Open the AI tab: Config top tab (→ until it is selected), then 4 (AI) in the default layout — or ctrl+p, type AI, Enter.

  4. Pick the provider: press P. The picker lists every provider of the catalog and whether its key resolves. The choice is saved as default_llm_provider in ~/.local/state/virtufin/tui/state.json and survives restarts. Without a choice, the first provider (file order) with a key is used.

  5. Ask something: type in the input at the bottom, press Enter, e.g.

    list the workers that are not running
    
  6. 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/.