.. index:: Builder, Pipeline Builder, bio-pype-builder

.. _builder:

Pipeline Builder
================

`bio-pype-builder <https://codeberg.org/bio-pype/bio-pype-builder>`_ is an
interactive web-based UI for building and editing bio-pype pipelines. It provides
a visual interface to browse available snippets, inspect their arguments, and
construct pipeline YAML files — without needing to write YAML by hand.

.. note::

   bio-pype-builder is a separate package. Install it independently from bio-pype::

       pip install bio-pype-builder

Once ``PYPE_MODULES`` is set to a workflow directory (e.g., via ``pype registry path``),
bio-pype-builder reads the available snippets and pipelines from that directory
and exposes them through the UI.

Starting the Builder
--------------------

After activating a workflow module::

    export PYPE_MODULES=$(pype registry path somatic==2026.03.11-1)

Start the builder::

    bio-pype-builder

Or with custom host/port::

    bio-pype-builder --host 0.0.0.0 --port 8000

Then open your browser at ``http://localhost:8000``.

What the Builder Provides
--------------------------

- **Snippet browser** — view all available snippets, their arguments, requirements,
  and expected results
- **Pipeline editor** — load existing pipeline YAML files, edit arguments and step
  definitions, and save back to disk
- **Dry-run** — execute a dry-run to preview the DAG (execution graph) of a pipeline
  before actually running it
- **Argument inspection** — all argument metadata (types, defaults, choices, nargs)
  is displayed directly in the UI, derived from the snippet's argparse definitions

The builder uses ``PYPE_PIPELINES`` (from ``PYPE_MODULES``) to discover and edit
pipeline YAML files, and ``PYPE_SNIPPETS`` to populate the snippet browser.

Refreshing Snippets
-------------------

If you add or modify snippets while the builder is running, use the refresh
endpoint (or button in the UI) to reload the snippet cache without restarting
the server.