AI tab¶
The AI tab is a chat assistant that operates the control plane for you. Type a request in natural language and it calls the right operations on your behalf -- scheduling triggers, starting workers, connecting feeds, reading state and events -- the same calls the panes make, and the same tools the web app's assistant has.
In the default layout it is Config › AI (4). Step by step:
Set up AI; how the tools relate to the shared operation catalog:
The TUI's API.
Quick start¶
-
The
openaiSDK is bundled with the base install — no extra step needed. If you're on an older version,uv pip install 'virtufin-tui[ai]'is the legacy install; current installs just needuv pip install virtufin-tui. -
Set an API key for one of the shipped providers (any one):
- Open the AI tab, type a command, press
Enter:
If no provider is configured yet, the tab shows a "configure" hint and the input is disabled.
Keybindings¶
| Key | Action |
|---|---|
Enter |
Send the typed message |
Ctrl+L |
Clear the transcript and start a fresh conversation |
P |
Open the provider picker (switch the active LLM provider) |
Providers (llm_providers.toml)¶
The provider catalog lives at ~/.config/virtufin/tui/llm_providers.toml
(seeded from the shipped default on first run; edit your copy freely). Every
entry is an OpenAI-compatible Chat Completions endpoint -- the openai SDK
is used for all of them, so only base_url / api_key / model differ.
[providers.openai]
base_url = "https://api.openai.com/v1"
api_key_env = "OPENAI_API_KEY"
model = "gpt-4o-mini"
[providers.deepseek]
base_url = "https://api.deepseek.com"
api_key_env = "DEEPSEEK_API_KEY"
model = "deepseek-v4-flash"
[providers.minimax]
base_url = "https://api.minimax.io/v1"
api_key_env = "MINIMAX_API_KEY"
model = "MiniMax-M3"
[providers.ollama] # local server, no key
base_url = "http://localhost:11434/v1"
model = "llama3.1"
API key resolution¶
For each provider, in order:
api_keyset inline in the toml (optional, discouraged for secrets).- The env var named by
api_key_env-- defaults to<NAME>_API_KEY, soDEEPSEEK_API_KEY,MINIMAX_API_KEY, andOPENAI_API_KEYwork with no extra config. - The global
VIRTUFIN_TUI_AI_API_KEYoverride.
Providers with no key (e.g. local Ollama) simply omit api_key / api_key_env.
Which provider is active¶
Resolution order:
VIRTUFIN_TUI_AI_PROVIDERenv var (explicit session override).- The runtime choice you picked with
P-- this is state, persisted to~/.local/state/virtufin/tui/state.json(default_llm_provider), not the catalog file. The catalog holds only definitions. - The first provider in the catalog (file order) that has a resolvable key.
- None -- the tab shows its "configure" state.
Other env overrides:
VIRTUFIN_TUI_AI_MODEL-- override the model id for the active provider.VIRTUFIN_TUI_AI_API_KEY-- override the key for the active provider.
Adding a custom provider¶
Add another [providers.<name>] table -- e.g. an internal gateway or a
different hosted model:
[providers.mygateway]
base_url = "https://llm.internal.example.com/v1"
api_key_env = "MY_GATEWAY_KEY"
model = "our-finetune"
Then press P in the AI tab to select it (or set VIRTUFIN_TUI_AI_PROVIDER=mygateway).
What it can do¶
The tools are the operation catalog (openspec operations): the document
virtufin-domain-devkit ships, which the web app implements too. Each operation is
one tool, named <group>__<action> (workers__list, triggers__schedule,
feeds__connect, ...) with the document's input schema, and runs as the TUI's
implementation of that operation (virtufin_tui.operations), over the calls the
panes make -- the assistant has no privileged path:
| Group | Operations |
|---|---|
| Workers | workers.list, .start, .stop, .delete, .tag, .create (from the worker registry), .upgrade; registry.list |
| Feeds | feeds.list, .save, .connect, .disconnect (the shared feed definitions) |
| Triggers | triggers.list, .schedule, .delete |
| Scenarios | scenarios.list, .add, .setStatus, .halt, .resume, .delete |
| Strategies | strategies.list, .compose |
| State and topics | state.get, state.keys, topics.list, topics.read (the next events on topics) |
The kill switch is for people only: it is no tool. Every write asks first: a confirmation dialog names the operation and its input, and the call runs only on yes; a declined call is reported to the model as not confirmed. An input that does not fit the operation's schema is refused before anything is sent, and the model is told which field is wrong.
Each turn, the assistant is given a small state snapshot (active scenario, current triggers/topics/workers) so it can use real ids and names instead of guessing. If a model replies with text instead of calling a tool, it is nudged once; if it still doesn't act, its text is shown as a normal chat reply (so models that only half-support tool-calling still work).
Example commands:
create trigger firing every minute publishing to trigger.everyminuteshow me the next 5 events on sys.workmanager.worker.lifecyclestop worker abc123connect the binance_top10 feed
Privacy¶
Each turn sends your message plus the state snapshot (active scenario and summaries of current triggers, topics, and workers) to the configured LLM provider. No secrets (API keys, connection credentials) are included in the snapshot. Be aware of this before pointing the tab at a third-party endpoint -- run a local model (Ollama entry) if the control plane's state must not leave the host.
Implementation notes¶
- Agent logic is Textual-free under
src/virtufin_tui/ai/(config.py,llm_client.py,tools.py,agent.py) so it is unit-tested without a Pilot harness. - The
openaidependency is bundled (a core dependency in the base install). - Anthropic-native and streaming token rendering are not yet supported; any OpenAI-compatible endpoint (including local servers) works today.