▶️ EXECUTE
=========

.. toctree::
   :hidden:

Introduction
------------
Execute walks through the lifecycle required to ship and operate an AGILab
application. It generates ready-to-run snippets, streams logs back into the UI
and keeps ``app_settings.toml`` synchronised so that installs, distribution
checks and runs are reproducible.

Sidebar
-------
- Project selector that keeps the page in lockstep with the active app.
- ``Verbosity level`` changes the ``verbose`` flag injected into every generated
  snippet (0–3) and is persisted under ``[cluster].verbose``.

Main Content Area
-----------------
- ``System settings`` groups the cluster configuration. Toggle support for
  ``pool``, ``cython`` and ``rapids``, enable the Dask scheduler and provide IP
  definitions for workers. The calculated mode hint clarifies how the chosen
  combination will execute and the settings are written back to
  ``app_settings.toml``.
- ``Install`` renders the install snippet that provisions the project's virtual
  environments. ``INSTALL`` streams stdout/stderr into ``Install logs`` so you
  know when the worker is ready. A successful install automatically enables the
  ``Run`` section.
- ``Distribute`` is split into two parts:

  * ``<module> args``: edit the run arguments managed in ``app_args.py``. You can
    toggle between the generated form UI and the custom Streamlit snippet saved
    in ``app_args_form.py``. Saved values update ``[args]`` in
    ``app_settings.toml``.
  * ``Distribute details``: generates the ``AGI.get_distrib`` snippet and the
    ``CHECK DISTRIBUTE`` action. When the command succeeds the ``Distribution
    tree`` expander plots the resulting work plan (DAG or tree) and ``Workplan``
    lets you reassign partitions to different workers before saving the
    modified plan.

- ``Run`` exposes the ``AGI.run`` snippet together with a ``Benchmark all
  modes`` toggle if you want to iterate through every execution path. ``RUN``
  streams logs into the ``Run logs`` expander and stores the output timings in
  ``benchmark.json``, which is summarised under ``Benchmark results``.
- ``LOAD DATA`` fetches the latest dataframe path configured for the project and
  shows an in-place preview. The preview is available even after a rerun.
- ``Prepare Data for Experiment and Explore`` creates (or updates) the CSV that
  powers the Experiment and Explore pages. Use the column selector with
  ``Select all`` support to decide which fields are persisted to
  ``${AGILAB_EXPORT_ABS}/<module>/export.csv``.

Regenerate Documentation
------------------------

After updating this guide (or any docs surfaced in the IDE), rebuild the
generated site so teammates and CI consume the same content:

.. code-block:: bash

   ./docs/gen_docs.sh

The wrapper guarantees ``uv`` runs ``docs/gen-docs.py`` with the extra build
dependencies required for Sphinx and stub generation.

.. literalinclude:: ../gen_docs.sh
   :language: bash
   :caption: ``docs/gen_docs.sh``