Skip to content

Frontends in CLABE

A frontend is the single boundary between CLABE and the person running an experiment. It owns all user-facing presentation (status messages, headers, live activity) and all interactive input (picking from a list, yes/no questions, free text, numbers). It is deliberately decoupled from logging: a logger is a durable diagnostic record, while a frontend is how a human is informed and prompted. See Logging for the other side of that split.

Everything downstream — the launcher, the stores, library notify() calls — talks to the Frontend protocol and never knows which implementation is behind it. Adding a new way to interact with CLABE means writing one class, not touching the rest of the codebase.

The ones we have

Frontend Class What it is When it's used
Console ConsoleFrontend A rich-styled, line-based console. On a real terminal it offers an arrow-key picker and a type-to-filter autocomplete; piped/CI it degrades to plain numbered prompts and input(). frontend = "console", or auto when not attached to a terminal
TUI TextualFrontend A persistent full-screen Textual app with four panes — Session (messages + answered prompts), Processes (live activity spinners), Input (the current prompt), Logs. frontend = "tui", or auto on a terminal (the default)
Web (not a frontend class) The TUI served in a browser via textual-serve. Not a separate implementation — it runs the TextualFrontend in a subprocess and proxies it to the browser. clabe serve … (see below)

Choosing one

The launcher's frontend setting selects the backend:

clabe run my_experiment.py                      # auto (TUI on a terminal)
clabe run my_experiment.py --frontend tui       # force the TUI
clabe run my_experiment.py --frontend console   # force the rich console
Value Result
auto (default) TUI when attached to a terminal, otherwise the console
tui Always the Textual TUI
console Always the rich console (also the safe choice for piping/CI)

In code, build one with the factory:

from clabe.ui import make_frontend, default_frontend

frontend = make_frontend("auto")  # or "tui" / "console"
frontend = default_frontend()  # the auto choice directly

A Launcher does this for you from settings.frontend and registers the result process-wide so library code can reach it.

Talking to the active frontend

clabe.ui mirrors every Frontend method as a module-level function that goes to whichever frontend is registered, so library code — stores, SessionBuilder, modifiers — never has to be handed one:

from clabe import ui

ui.notify("Transferring data…", ui.MessageLevel.INFO)
choice = ui.prompt_pick(ui.PickRequest(label="Choose a rig:", options=paths))

The two halves behave differently when nothing is registered:

  • Output — notify, header, activity — is a no-op, so it is always safe to call from library code used standalone.
  • Prompts — every prompt_* — raise NoFrontendError. A prompt has to return an answer, and failing loudly beats hanging on a rig.

ui.cancel_prompt() is the exception among the non-output calls: it aborts whatever prompt is currently waiting and is a no-op when nothing is registered (see Cancelling a prompt).

ui.require_frontend() gets the registered frontend directly, with the same error. Tests use ui.use_frontend(fake) as a context manager, which restores whatever was registered before.

MessageLevel (INFO, SUCCESS, WARNING, ERROR) expresses presentation intent; like the console, the Session pane only renders at/above the current verbosity threshold (warnings and above by default), while everything is still recorded to the transcript. See Logging for notify() vs logger.

Cancelling a prompt

frontend.cancel_prompt() (or ui.cancel_prompt()) aborts the prompt that is currently waiting for the user. It is safe to call from any thread; the blocked prompt_* call raises PromptCancelledError. Calling it when no prompt is waiting does nothing, so a cancel that races ahead of a prompt is simply dropped; retry until the prompt returns if you need to be sure.

import threading

from clabe import ui

threading.Timer(30, ui.cancel_prompt).start()
try:
    notes = ui.prompt_text(ui.TextRequest(label="Notes (30 s)"))
except ui.PromptCancelledError:
    notes = ""

In the TUI, cancelling also closes any open dialog (acknowledge, table, form, path picker). The console reads the keyboard key by key on a real terminal so its prompts can be cancelled too; when stdin or stdout is not a terminal it falls back to input(), which cannot be interrupted, and cancelling has no effect.

The exit prompt

When an experiment finishes, the launcher waits at Press Enter to exit... so the last messages (and any error) stay on screen. exit_prompt_timeout controls that wait:

Value Result
unset (default) Wait until Enter is pressed
0 Exit immediately, without prompting
N Wait up to N seconds, then exit on its own

Set it per run with --exit-prompt-timeout 60, or per machine as a top-level key in clabe.yml, e.g. on rigs that must not stay blocked between sessions:

exit_prompt_timeout: 60

The timeout relies on cancel_prompt, so it has no effect on a frontend that cannot cancel its prompts.

TUI shortcuts and clickable paths

The Textual TUI shows a persistent header (with the CLABE version and, once known, the running experiment) and a footer listing the active shortcuts:

Key Action
Ctrl+C Exit the launcher
Ctrl+S Save an SVG screenshot of the window
F2 Toggle the Logs pane to reclaim vertical space

Ctrl+S renders the whole window to an SVG in the OS temp directory and notes the (clickable) path in the Session pane — terminal-independent, and a reliable way to capture a run to share. Existing paths in the Session and Logs panes are rendered as file:// hyperlinks — Ctrl/⌘-click opens them in terminals that support OSC 8 (e.g. Windows Terminal, iTerm2); elsewhere they render as ordinary underlined text.

Writing a new frontend

Subclass FrontendBase and implement the rendering/asking primitives; the base class handles the transcript bridge, the validation/retry loop, and the number-prompt loop for you:

from clabe.ui import FrontendBase


class MyFrontend(FrontendBase):
    def _render(self, message, level): ...
    def _ask_text(self, request): ...
    def _ask_pick(self, request): ...
    def _ask_confirm(self, request): ...
    def _ask_autocomplete(self, request): ...
    def _ask_path(self, request): ...
    def _ask_acknowledge(self, request): ...

Optional hooks: _render_header, _on_answer, set_min_level, close (for frontends that own a resource, like the TUI's background app), and cancel_prompt (abort the waiting prompt from another thread by making it raise PromptCancelledError; the base class leaves it a no-op).

Serving the TUI over the web

clabe serve runs the TUI in a browser via textual-serve, so a launcher can be driven remotely without building a separate web UI:

clabe serve my_experiment.py --port 8080
  • It binds localhost only. For remote access, forward the port over SSH rather than exposing it to the network:
ssh -L 8080:localhost:8080 <rig-host>     # then open http://localhost:8080
  • Single session is enforced. Each browser connection spawns its own launcher subprocess, so clabe serve passes --single-session: a stray second connection refuses to start (via an OS file lock) rather than fighting the live session over the rig.
  • The "Session ended" screen has a Finish button (next to Restart) that shuts the server down and frees the port.
  • --open-browser opens the page automatically once the server is ready (leave it off on headless/remote hosts).

In code, the same is available as clabe.web.serve(command, …). Serving requires the optional web extra:

pip install "aind-clabe[web]"