******************* palaestrAI Web UI ******************* About ----- The palaestrAI Web UI is a browser-based front-end to manage the full experiment lifecycle without touching the command line. It runs inside the same process as ``palaestrai serve`` — there is no separate service to install or configure. Under the hood it uses the REST API described in :doc:`serve`; anything the UI does can also be automated through ``curl`` or any HTTP client, and the two views always stay in sync. The UI is styled with `Pico.css`_ and uses `HTMX`_ for its interactive partial updates. YAML editing happens in an in-browser `CodeMirror`_ editor with folding, tab-to-spaces, and dark-mode support. Everything is served from Python — no separate Node.js/webpack build step and no external CDN dependency at runtime. .. _Pico.css: https://picocss.com/ .. _HTMX: https://htmx.org/ .. _CodeMirror: https://codemirror.net/ .. contents:: :local: :depth: 2 Quickstart ---------- Start the server the same way you would to expose only the REST API:: palaestrai serve Then open the Web UI in your browser: * http://localhost:4247/ui — landing page (redirects to Status) The service binds to all interfaces on TCP port ``4247`` by default; see :doc:`serve` for how to change host and port. To make the UI reachable from another machine, publish port ``4247`` and browse to ``http://:4247/ui``. The service stays online until it receives ``SIGINT`` or ``SIGTERM`` (e.g., ``Ctrl+C``). All four pages share a common navigation bar in the top-left corner: * **Status** — currently running and scheduled experiment-run instances, with a Cancel button per instance. * **Templates** — reusable snippets of experiment YAML that other pages can drop in with one click. * **Experiments** — arsenAI experiment documents; edit, generate runs from them, and schedule those runs. * **Experiment Runs** — individual experiment run documents; edit, save, or schedule. .. note:: The Web UI writes to the same database as the CLI. Anything you save here (experiments, runs, templates) is visible to ``palaestrai experiment-start`` and vice versa. Started runs record the operating-system user name they were launched under (``experiment_run_instances.user``); UI-initiated runs record the user the ``palaestrai serve`` process is running as. The pages --------- Status ^^^^^^ The Status page lists every experiment-run instance whose lifecycle status is ``RUNNING`` or ``SCHEDULED``; ``FINISHED`` and ``ERROR`` rows are intentionally hidden so the page stays focused on actionable state. Each row shows * the instance UID, * the parent experiment run, * the parent experiment, * the user that launched it (``NULL`` for programmatic runs), * the current status, and * the wall-clock start time. The **Cancel** button on each row issues ``DELETE /experiment_run_instances/{uid}``, which asks the executor to shut the underlying run governor down gracefully. Cancellation is asynchronous and best-effort: by the time the request reaches the executor the instance may already have terminated, and there is no dedicated ``CANCELLED`` status — cancelled instances end up ``FINISHED`` (if they were queued) or as whatever the RunGovernor's exit code maps to. The row list auto-refreshes at a short interval via HTMX; there is no manual refresh button. Templates ^^^^^^^^^ Templates are reusable YAML snippets — the recurring blocks that you'd otherwise copy-paste between experiment or run documents. They live in a dedicated ``templates`` database table and are typed by ``TemplateType`` (e.g. environment, agent, schedule phase); the type drives how the other pages surface them. From the Templates page you can * **create** a new template by name and type, * **edit** an existing template in the CodeMirror YAML editor, * **rename** or **copy** a template via *Save as…*, and * **delete** a template. The editor persists changes to the database on **Apply**. There is a dark-mode toggle in the editor toolbar. Experiments ^^^^^^^^^^^ The Experiments page lets you work with arsenAI experiment documents — the design-of-experiments layer that expands one document into many concrete experiment runs. For each experiment you can * **edit** the document in the YAML editor (with folding, section navigation, and snippet insertion from the Templates page); * **generate** the resulting experiment runs. ``POST /experiments/{name}/generate`` runs arsenAI's generator in-process, writes the produced run documents to the database, and returns their UIDs. No files are written to disk. * **schedule** one or several of the generated runs: pick them in the right-pane list (multi-select) and click *Schedule*. Each scheduled run is queued through the same executor path as ``palaestrai experiment-start``. Generation errors surface as ``HTTP 422`` responses with the underlying arsenAI diagnostic, so a malformed experiment document does not become a 500 in the UI. Experiment Runs ^^^^^^^^^^^^^^^ The Experiment Runs page mirrors the Experiments page, but at the finer granularity of individual experiment run documents (the artefacts that ``palaestrai experiment-start`` and the REST API's ``PUT /experiment_runs`` operate on). For each run you can * **edit** the run document in the YAML editor; * **save** — either in place (Apply), or under a new name (*Save as…*), which stores a copy without overwriting the original; * **schedule** the run, optionally as a multi-select from the right pane. Scheduled runs appear on the Status page as soon as the executor picks them up. Editing conventions ------------------- The YAML editor is the same widget on every page and behaves the same way: * **Tab** inserts two spaces. * **Ctrl+/** toggles a line comment. * The gutter shows fold markers for every YAML block. * Section-level edits are cursor-based: the editor detects which top-level block your cursor is in and highlights matching lines, which makes surgical edits (e.g. changing a single phase) easy. * **Save as…** always makes a *copy*; use **Apply** to overwrite the document you are editing. Under the hood: REST API ------------------------ The Web UI is a thin HTMX layer over the REST API. Every action you perform in the UI maps to one of the endpoints in :doc:`serve`, augmented by the following additions: * ``GET /experiment_run_instances`` — list all *active* instances (``RUNNING`` + ``SCHEDULED``), ordered by creation time. Used by the Status page. * ``DELETE /experiment_run_instances/{uid}`` — cancel a running or scheduled instance. Sends an :class:`~palaestrai.core.protocol.ExperimentRunCancelRequest` to the executor. * ``GET|PUT|POST|DELETE /templates`` and ``GET|POST|DELETE /templates/{template_id}`` — full CRUD for reusable YAML snippets. * ``POST /experiments/{name}/generate`` — run arsenAI's generator in-process against a stored experiment document and persist the resulting runs. Returns their UIDs. Every mutating action from the UI hits an endpoint under the same authentication scope as the REST API, so if you already secure ``palaestrai serve`` behind a reverse proxy (TLS, HTTP basic auth, an identity-aware proxy, …) the Web UI inherits that same protection automatically. Deployment notes ---------------- * The Web UI ships as part of ``palaestrai`` and requires no extra install step. All static assets (Pico.css, HTMX, CodeMirror) are bundled under ``src/palaestrai/api/static/`` and served from Python. * Runtime dependencies (`FastAPI`, `Jinja2`, `uvicorn`) are already pulled in by ``palaestrai serve``; no additional packages are needed for the UI. * The Web UI writes to the same SQLite/PostgreSQL database configured in :doc:`runtime-config`. Any Alembic migrations required by new UI features (e.g. the ``experiment_run_instances.user`` column, the ``templates`` table) are applied on server start. * When running behind a reverse proxy, make sure the proxy forwards the ``Upgrade``/``Connection`` headers on ``/ui`` if you use its auto-refreshing partials — HTMX itself is plain HTTP, but some proxies interfere with long-lived request patterns.