ObjWorkflowSimulTUI is the real-time terminal dashboard for monitoring
ObjWorkflowSimul runs. It renders live progress, success rate, throughput, ETA, and
a scrolling table of recent GUID results — all without making any database calls.
Module: factory.workflow/package.tui/ObjWorkflowSimulTUI.py
Entry class: SimulTUI
Dependencies: rich, ObjTUI, ObjConstants.TuiConstants, ObjEnum.TuiLogLevel
The simulation workers update the shared class-level dict ObjWorkflowSimul._ACTIVE_SIM_STATE
on every GUID completion. SimulTUI polls that dict on each refresh cycle — no
database calls, no locks beyond the simulation's own _SIM_STATE_LOCK.
ObjWorkflowSimul workers
│ write
▼
_ACTIVE_SIM_STATE (class-level dict, protected by _SIM_STATE_LOCK)
│ poll (_poll_state every DASHBOARD_UPDATE_SLEEP)
▼
SimulTUI
│ renders
▼
Rich Live screen
┌─── header ────────────────────────────────────────────────────────┐
│ heartbeat ⚡ Axion Simulation Monitor | Workflow | Uptime | Time │
├─── sidebar ──────┬─── sim_status ─────────────────────────────────┤
│ Progress │ Progress bars (Completed / Failed / Success) │
│ Total │ Timing stats (avg / min / max ms) │
│ Completed │ Throughput (GUIDs/s) │
│ Failed ├─── recent_guids ───────────────────────────────┤
│ Success % │ Scrolling table: GUID | Elapsed ms | OK/FAIL │
│ Progress % │ │
│ Speed │ │
│ ETA │ │
│ Sim GUID │ │
├─── footer ────────────────────────────────────────────────────────┤
│ Status line + last N log messages │
└───────────────────────────────────────────────────────────────────┘
SimulTUIdashboard = SimulTUI(sim_class=ObjWorkflowSimul)
sim_class is the ObjWorkflowSimul class (not an instance) — the dashboard reads its
class-level _ACTIVE_SIM_STATE and _SIM_STATE_LOCK attributes.
dashboard.start() # redirects sys.stdout/sys.stderr, starts Live + polling thread
# ... simulation runs ...
dashboard.stop() # joins thread, stops Live, restores stdout/stderr
Always call stop() in a finally block so the terminal is restored on error or
Ctrl+C.
| Method | Description |
|---|---|
start() |
Start Live display and background poll thread |
stop() |
Stop display and restore terminal |
log(message, level) |
Append a timestamped entry to the footer log |
set_status(message) |
Update the footer status line |
RECENT_GUIDS_LIMITClass constant controlling how many GUID result rows are kept in the recent-GUIDs table
(default 15).
start() replaces sys.stdout and sys.stderr with ObjTUI.TuiStream instances that
route all print() and other raw writes into the footer log. This prevents the flicker
that would result from raw terminal writes mixing with the Rich Live screen.
Rich sends many small write() calls per refresh. Terminals render each one
immediately, producing visible intermediate states. SimulTUI wraps its Console in
an ObjTUI.AtomicWriter that buffers every write between begin() and end() and
flushes the complete frame in a single call, wrapped in DECSET 2026 synchronized-output
markers (TuiConstants.SYNC_START / TuiConstants.SYNC_END).
_ACTIVE_SIM_STATE)| Key | Type | Description |
|---|---|---|
workflow_name |
str |
Display name of the workflow being simulated |
simul_guid |
str |
Simulation run GUID |
total |
int |
Total GUIDs to process |
completed |
int |
GUIDs processed (success + failure) |
failed |
int |
GUIDs that returned a failure result |
start_time |
float |
time.time() at simulation start |
timing_list |
list[float] |
Per-GUID elapsed seconds (recent window) |
recent_guids |
list[dict] |
Recent GUID result dicts — see below |
Each entry in recent_guids:
| Key | Type | Description |
|---|---|---|
guid |
str |
Full GUID string |
elapsed |
float |
Processing time in seconds |
ok |
bool |
True if the GUID succeeded |
factory.workflow/ObjWorkflowSimul.py — simulation engine; populates _ACTIVE_SIM_STATEfactory.core/ObjTUI.py — TuiStream, AtomicWriter, TuiThemefactory.core/ObjConstants.py — TuiConstantsfactory.core/ObjEnum.py — TuiLogLevel