The TUI's API¶
The platform's user-level operations — list and start workers, connect feeds, schedule triggers, halt scenarios, read state and topics, ... — are one shared operation catalog (openspec operations), a document virtufin-domain-devkit ships. The TUI and the web app each implement every operation of it, so the same name with the same input does the same thing in both clients.
- The catalog itself (every operation, its input schema, read or write): https://domain-devkit.docs.virtufin.com/operations/
- How the web app exposes it: https://app.docs.virtufin.com/api/
This page says how the catalog is reached from the TUI. It does not repeat the catalog.
Where it is implemented¶
virtufin_tui.operations implements every operation over TuiClient, the same client
calls the panes make — there is no privileged path. Each input is validated against the
operation's JSON Schema (with its defaults) before anything is sent; a malformed input is
refused naming the field. Writes go through the client's write guard, so on a protected
context they ask first, and they are recorded on Infra › Changes.
tests/test_operations.py fails when an operation of the document is missing or its
schema differs, so the TUI and the catalog cannot drift apart.
Groups (see the catalog for inputs): workers.* and registry.list, feeds.*,
triggers.*, scenarios.*, killSwitch, strategies.*, state.*, topics.*.
From the AI tab¶
Each operation is one tool of the AI tab, named <group>__<action> — the
operation name with . replaced by __:
| Operation | Tool |
|---|---|
workers.list |
workers__list |
triggers.schedule |
triggers__schedule |
feeds.connect |
feeds__connect |
scenarios.setStatus |
scenarios__setStatus |
- Every write asks first: a dialog shows the operation and its input
(
triggers.schedule {"name": ...}?); it runs only on yes. A declined call is reported to the model as not confirmed. - People-only operations are not offered as tools:
killSwitchisKin the TUI only. - The model and its endpoint come from
~/.config/virtufin/tui/llm_providers.toml(OpenAI-compatible Chat Completions;Ppicks the provider). See Set up AI. - Each turn the model gets a small state snapshot (active scenario, triggers, topics, workers) so it uses real ids.
From a script¶
Scripts run as subprocesses with the active context in environment variables
(VIRTUFIN_TUI_API_HOST, VIRTUFIN_TUI_API_PORT, VIRTUFIN_TUI_API_TLS,
VIRTUFIN_TUI_API_KEY, ...; full table: Scripts › The env-var contract).
They run with the TUI's own Python, so virtufin_tui.operations imports:
import asyncio
import json
import os
from virtufin_tui.client import TuiClient
from virtufin_tui.operations import run_operation
async def run():
client = TuiClient(
os.environ.get("VIRTUFIN_TUI_API_HOST", "localhost"),
int(os.environ.get("VIRTUFIN_TUI_API_PORT", "5002")),
tls=os.environ.get("VIRTUFIN_TUI_API_TLS") == "true",
api_key=os.environ.get("VIRTUFIN_TUI_API_KEY") or None,
)
await client.connect()
try:
workers = await run_operation(client, "workers.list", {})
print(json.dumps(workers, indent=2, default=str))
finally:
await client.disconnect()
if __name__ == "__main__":
asyncio.run(run())
run_operation(client, "<group>.<action>", {...}) takes the operation's dotted name (not
the tool name) and validates the input first. Unlike in the TUI, a script's writes are
not confirmed on a protected context and not recorded on Changes: a script has its
own client. For calls outside the catalog, use _rpc.invoke() (any api RPC by service and
method, Scripts).
From the panes¶
Most pane actions do what an operation does, over the same client calls: e.g. a on
Infra › Triggers is triggers.schedule, C on Trading › Feeds is feeds.connect, h
on Trading › Scenario is scenarios.halt / scenarios.resume, u on Infra › Workers is
workers.upgrade. Some pane actions have no operation (a feed's start/stop publish, tag
undo, the view settings). See the How-tos and Keybindings.