Displays and local dashboard

Notebook and terminal

progress=True selects an anywidget notebook display when available, otherwise a Rich terminal display. Both show sampler phases, per-chain progress, variable-wise worst R-hat and ESS, and the controller’s checks and verdict. Install [notebook] for notebook rendering. Notebook stop messages use the widget comm channel and a shared RunControl; frontend responsiveness depends on the host notebook’s comm scheduling. For independent cancellation during a blocking cell, use the localhost dashboard or start().

Authenticated localhost

handle = monitor.start(model=model, dashboard=True, progress=False)
print(handle.dashboard_url)
try:
    idata = handle.wait()
    # The dashboard remains readable until close().
finally:
    handle.close()

Install the dashboard extra first. Dashboard(*, port=0, title="pymc-monitor", idle_timeout=300) binds a preallocated socket on 127.0.0.1. A per-instance token in the initial navigation path grants an HttpOnly SameSite cookie; the browser then removes the token from its history and reloads through a cookie-only URL. Treat the original URL as a credential. Non-browser API clients can send Authorization: Bearer <token>. Never put a token in query strings or expose this port publicly.

Every route requires authentication and validates Host and Origin. Stop is POST-only; unknown runs return 404, and finished or already-stopping runs return 409. The service does not enable cross-origin requests. Its HTML contains all its CSS and JavaScript (including vendored uPlot), with a hash-based Content Security Policy and no third-party scripts or analytics. All run-supplied names, errors and hints render as text, not executable HTML. Trace previews show at most 20 elements and 500 points per chain. They are diagnostic previews, not a replacement for posterior plots.

The server is local to the Python host. A notebook running remotely does not make that machine’s loopback URL accessible on your laptop. Do not expose the server publicly or publish its token. Remote transport belongs in a separate application.

Reusable presentation

A shared Dashboard() can serve several start(..., dashboard=dashboard) handles; each has an isolated run URL and stop control. overview_url() opens a token-free-cookie-redirected overview; authenticated GET /progress returns the shared {models, runs} manifest, and POST /stop stops active runs, or one run with ?model=<label>. Removing one handle retains the others, and the idle server shuts down after idle_timeout seconds with no runs. Close the shared instance explicitly when done.

DashboardState(completion_phase="sampling") is a lock-protected, transport-independent event reducer with update(event), show_phase, show_sampling, show_convergence, request_stop, finish(status), and snapshot(). Use completion_phase="downloading" to keep a cloud dashboard open after sampling ends; a RunFinished sampling verdict does not mark downloading complete. Snapshots are independent JSON-safe copies. render_dashboard_html(*, progress_url, stop_url, token, title="pymc-monitor") returns self-contained HTML with escaped JSON configuration and supports flat states or {models: [{label, name}], runs: {label: state}}. dashboard_csp(*, progress_url, stop_url=None) hashes the inline assets and restricts connections to validated API origins. A null stop URL hides controls. For remote hosts, serve the HTML with the returned CSP and allow CORS for the page’s origin at the explicit API endpoints; progress and stop requests pass nonempty tokens in query parameters without custom headers or bodies. dashboard_assets() returns the bundled source assets.

A consuming application owns authentication and transport. It can dispatch typed events to the reducer and serve these assets without importing any cloud dependency into pymc-monitor. The local HTTP service is only one adapter for that state.