Create the .mltree/ store (pipeline.yaml, mltree.db, runs/) in the project root. Safe to call again.

Register a pipeline step (a node on the map), or update it if the name already exists.

Draw a directed edge source -> target. Both steps must exist; cycles are rejected.

Return the whole map: nodes (with params, script and latest run status), edges and a topological order.

Record one execution of a step: params, metrics, artifacts and its parent run in the experiment tree. The versions (SHA-256) of the step's input and output files are recorded too, so later runs can tell when the data changed.

Data versions: the current SHA-256 of every step's input and output files, what the step's latest run used, and which inputs changed since (so the step is stale and should be re-run). Reads files only; runs nothing.

Compare runs: params that differ (baseline -> each run), metrics side by side, data versions used, and a unified diff of the script snapshots of the first two runs.

Add a note to a step or a run, e.g. why a run failed, what a step assumes, or a conclusion from a comparison. Notes show in the viewer (where the user can edit them), in get_pipeline / list_runs and in the HTML export.

Add or remove tags on a run (e.g. 'baseline', 'best', 'final'). The tree can highlight runs by tag.

GNN view of a step: the model architecture read statically from its script and imported project modules (conv layer types and counts, hidden sizes, heads, pooling, head, forward order; nothing is imported or run), dataset classes it constructs (TUDataset, MoleculeNet, QM9, OGB, DGL ...), and cached dataset stats (graphs, nodes/edges per graph, feature dims, classes or target range, self loops, isolated nodes).

Create a sweep (an HPO study / grid search) that groups trial runs. Pass its sweep_id to log_run for each trial; the map shows the sweep as one collapsible fan with the best trial highlighted. Use run_sweep instead to have mltree launch a grid itself.

Mark a sweep finished and return its summary (trial counts and the best trial).

Execute a step's script as a subprocess and record it as a run automatically.

Params are passed as CLI flags when the script uses argparse/click (or positionally for sys.argv scripts, or key=value for hydra), and always as $MLTREE_PARAMS (JSON). Records params, script snapshot, command, exit status, duration, log (.mltree/runs//log.txt) and metrics from MLTREE_METRIC name=value stdout lines or a JSON file written to $MLTREE_METRICS_FILE / a declared metrics*.json output. Returns the run and the end of its log.

Run a grid search: one sweep run plus one child run per combination, executed one after another.

Return the status and the last lines of a run's log (live while it runs).

Stop a run (SIGTERM, then SIGKILL after 5 s) or a whole sweep started from this session.

List runs, newest first.

Find the best succeeded run by a metric.

Return the URL of the mltree map viewer (and start it if needed). Give the URL to the user.

Build the map of an EXISTING project by static analysis (ast only; user code is never executed).

Detects data reads/writes, argparse/click params, local imports, docstrings and step kinds, links steps whose output paths match other steps' inputs (falling back to file numbering and imports), and imports existing results as runs tagged 'imported'. Idempotent: re-scans update scanner-owned fields, add new steps, never delete, and keep edits made with add_step. Review the returned summary and fix it with connect_steps / add_step.

Write a single self-contained HTML file of the map (steps, code, runs, experiment tree, compare).

It opens offline in any browser, read-only, with no server, so the user can email it, post it in Slack or host it on GitHub Pages / a gist. Returns the file path and size. It contains the scripts unless include_scripts=false: tell the user that before they share it.