bio-pype-runtime-models 0.1.0__py3-none-any.whl

bio_pype_runtime_models-0.1.0.dist-info/METADATA

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: bio-pype-runtime-models
+Version: 0.1.0
+Summary: Learn per-workflow resource, timeline and power-curve models from bio-pype runtime dumps.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.23
+Provides-Extra: pype
+Requires-Dist: bio-pype; extra == "pype"
+
+# bio-pype-runtime-models
+
+Learn per-workflow **resource**, **timeline** and **power-curve** models from
+[Bio-Pype](https://bio-pype.readthedocs.io) runtime data, then use them to
+predict a new run's cost from a single input size, to grade a finished run
+against its own baseline, and to suggest better default requirements.
+
+Built to be imported into other projects ([compute.bio](https://compute.bio)
+trains and serves these models from its database). Pure `numpy`; models
+serialise to plain JSON — no pickle.
+
+> **Status: alpha.** The modelling choices and the JSON model format will
+> change between releases, and estimates from few runs are rough. Retrain
+> after upgrading rather than loading models written by an older version.
+
+The distribution is `bio-pype-runtime-models`; the import name and the command
+are `pype_runtime_models` / `pype-runtime-models`.
+
+## Install
+
+```bash
+pip install bio-pype-runtime-models
+```
+
+Requires Python >= 3.9 and `numpy`. Bio-Pype itself is not needed: the package
+only reads the runtime data Bio-Pype writes.
+
+## Input data
+
+One *run* is the content of a Bio-Pype `pipeline_runtime.yaml`: a mapping of
+job id to job record (command, status, timings, `requirements`,
+`resource_consumption`, `data_sizes`), plus run metadata and environment. It
+can come from:
+
+- a directory of `*.json` files, one per run ("dumps");
+- parsed `Run` objects, built with `Run.from_dict(mapping)`, when the runs live
+  somewhere else, such as a database.
+
+## What it does (mapped to the original goals)
+
+| Goal | Where |
+|------|-------|
+| Detect which workflow a runtime object is | `workflow.detect_workflow` — `pipeline_name`, else a snippet-set signature match |
+| One model per workflow, improving as more runs land | `train.train_models` rebuilds the whole registry each time; safe to schedule |
+| Per-step resource consumption, spot deviations | `StepModel` per snippet; `evaluate_run` flags per-step anomalies |
+| Predict timeline + resources of each step from input size | `predict.predict_run` |
+| Flag steps whose memory/CPU is driven by input size | `StepModel.input_sensitive` / `sensitivity_report` |
+| Recommend raising/lowering the default requirement | `StepModel.recommend` → increase / decrease / ok |
+| Post-hoc performance eval, overall and per-step | `evaluate.evaluate_run` |
+| Predict the power curve for a workflow | `predict.predict_power_curve` (experimental, see below) |
+
+## Workflow identity & provenance
+
+Snippets live in `$PYPE_MODULES/snippets` and are **shared by every pipeline in a
+module**, so the natural owner of a snippet's resource model is the module, not
+the individual pipeline. Identity is therefore pluggable (`--identity` on train,
+`identity_mode=` in the API):
+
+- **`module`** (default) — key models by the `PYPE_MODULES` basename, pooling
+  every pipeline in the module. Shared snippets like `mosdepth` train on all
+  their samples at once (e.g. n=116 across the 5 `ensemble_sv` pipelines instead
+  of split five ways). Resource models are pooled; each pipeline keeps its own
+  timeline view (snippet set + start offsets), so `predict <module> --pipeline X`
+  gives X's schedule against the pooled models.
+- **`pipeline`** — the older one-model-per-`pipeline_name` behaviour.
+- **`registry`** — key by a versioned `namespace/name:version` parsed from a
+  registry-style module path (e.g. `.../registry/sci-bioinformatics/somatic:20260701`).
+  This is the collision-proof, version-aware identity the module registry will
+  provide; it falls back to the module basename when no registry info is present.
+
+Every model records its provenance (`module_paths`, `namespaces`, `versions`,
+`pipeline_names`, `profiles`), so the day the registry lands, switching to
+version-aware keying — or sharing/federating models at the app level — is a
+config change, not a rewrite. `predict`/`evaluate` accept either an identity key
+or a `pipeline_name` (auto-resolved to its module).
+
+Provenance includes module paths, which often contain user or group names.
+Strip it before showing a model to anyone other than the people whose runs
+trained it.
+
+Caveat for `module` mode: two *unrelated* modules that happen to share a basename
+(your `somatic` vs a third party's) would be merged — the registry namespace is
+what ultimately disambiguates them.
+
+## Key modelling choices
+
+- **Canonical step identity** is the *snippet name* parsed from the job command
+  (`ingest.snippet_name_from_command`), not the `name` field — the latter carries
+  per-sample suffixes (`mosdepth_EGAD2585`) that would fragment the models.
+- **Driver size.** Each step is regressed against its own *driver size*:
+  `input_size_bytes`, or `output_size_bytes` when the input is 0 (generators /
+  aggregators). Because a caller supplies only one number at prediction time, we
+  also learn how each step's driver scales with the **run-level** driver
+  (`driver_scale`), so the whole chain is predictable from a single input size.
+  The run driver is the largest input among the earliest-submitted jobs — the
+  recorded `dependencies` are often partial in dumps, so we don't rely on a
+  strict topological root.
+- **Per-step fit** picks the best of `constant` / `linear` / `power` (power fit
+  and scored in log space for numerical stability) by **leave-one-out R²**, and
+  only beats the constant baseline if it generalises — noisy/sparse steps stay
+  constant instead of overfitting.
+- **Few samples means no size dependence.** A step needs at least 5 samples
+  with differing driver sizes before a size-dependent fit is even tried. Below
+  that the prediction is the median of what was seen, whatever the input size:
+  three runs of a workflow give the same expected duration for a small and a
+  large input.
+- **Robust throughout**: medians, MAD, and Spearman rank correlation, because
+  runtime telemetry is heavy-tailed. Predictions are capped at 50× the largest
+  observed value so queries far outside the training range can't blow up.
+
+## How a run is graded
+
+`evaluate_run` compares each completed step with the prediction for that
+step's own driver size:
+
+- A step is **flagged** when duration or peak memory is at least 3 robust
+  standard deviations above the prediction, or at least 2x the prediction.
+  Average CPU is reported for context and never flagged.
+- The spread used for the z-score has a floor of 5% of the predicted value, so
+  a step whose training runs happened to be almost identical does not flag
+  every normal variation.
+- Steps with no model are reported as `unmodelled`, not dropped.
+- The overall `performance_score` (0-100) and `verdict` come from the duration
+  z-scores. The verdict is `unknown` when no step's duration could be graded.
+
+## Requirement recommendations
+
+`StepModel.recommend` compares the default requirement recorded with the jobs
+to what the step used: predicted peak memory with 1.3x headroom, predicted
+duration with 1.5x headroom. It suggests lowering a requirement that is more
+than 3x above the 95th percentile of use. Check a suggestion against the
+underlying measurements before applying it; a bad measurement in the training
+runs produces a bad suggestion.
+
+## GPU steps
+
+Steps are also grouped by a vendor-neutral GPU class. Once a class has at
+least 3 samples the model learns a duration factor for it relative to the
+size-based prediction; `--gpu-class` / `gpu_class=` applies it, and omitting it
+predicts for the mix of cards seen in training.
+
+## Data hygiene (split runs & mis-measured inputs)
+
+These matter because of how runs are actually dumped, and are handled generally
+— **no per-snippet logic is hardcoded anywhere**:
+
+- **Split / partial runs are kept, not discarded.** A logical run is often
+  spread across several dump files: a failed run is dropped, a resumed run
+  completes the same file, and a *relaunched* run starts a fresh file missing
+  the steps that already succeeded. Every completed step in every file is a
+  valid per-step sample, so all of them train the per-step models. The
+  `quality` report shows how many runs per workflow are partial.
+- **Run-level input size is only trusted when it's actually present.** Each
+  workflow's input-tier ("entry") snippets are learned from the data (the steps
+  whose driver size is largest by a wide margin). A partial file that lacks an
+  entry step contributes its per-step samples but no run-level driver, so it
+  can't feed the chain-scaling model a misleading input size.
+- **Implausible driver sizes are dropped per step.** Some inputs are folders
+  historically mis-measured as a few bytes, or are overwritten in place with a
+  dummy value by convert/cleanup steps. A driver is dropped only when it is
+  *both* < 1 MB *and* > 10,000× smaller than that step's own largest driver —
+  a general statistical test that removes the bogus cluster while leaving
+  genuinely small-input steps (all a few KB) untouched. Steps left with no
+  size signal fall back to a constant (median) model, which is correct for
+  cleanup-style steps whose cost isn't driven by input size. Counts surface in
+  the `quality` report and per-step `n_driver_outliers`.
+
+```bash
+python -m pype_runtime_models quality models/     # partial runs, dropped outliers, entry snippets
+```
+
+## CLI
+
+```bash
+# train / retrain from a dumps directory
+pype-runtime-models train dumps/ --out models/
+
+# list what got trained
+pype-runtime-models workflows models/
+
+# predict per-step resources + timeline for a 50 GB input
+pype-runtime-models predict models/ ensemble_sv_TO --input-size 50gb --full
+
+# grade a finished run
+pype-runtime-models evaluate models/ dumps/<hash>.json
+
+# requirement changes worth making
+pype-runtime-models recommend models/ ensemble_sv_TO --changes-only
+
+# learned per-GPU-class duration factors
+pype-runtime-models gpu models/ ensemble_sv_TO
+
+# predict the power curve (30-min bins by default; experimental)
+pype-runtime-models power models/ ensemble_sv_TO --input-size 50gb --bin-minutes 60
+```
+
+`train` options: `--identity module|pipeline|registry` (default `module`),
+`--min-workflow-runs N` (skip identities seen in fewer runs, default 1) and
+`--min-step-samples N` (skip steps with fewer completed jobs, default 3).
+`python -m pype_runtime_models ...` is equivalent to the `pype-runtime-models`
+command.
+
+## Library
+
+```python
+from pype_runtime_models import (
+    Run, train_models, load_models, predict_run, evaluate_run,
+)
+
+reg = train_models("dumps/", "models/")          # or load_models("models/")
+pred = predict_run(reg, "ensemble_sv_TO", input_size_bytes=50 * 1024**3)
+report = evaluate_run(reg, "dumps/somehash.json")
+
+print(report["verdict"], report["performance_score"])
+for step in report["flagged_steps"]:
+    print(step["name"], step["flags"])
+```
+
+Without files, for runs held in a database or loaded from
+`pipeline_runtime.yaml`:
+
+```python
+runs = [Run.from_dict(mapping) for mapping in runtime_mappings]
+reg = train_models(runs, min_workflow_runs=3)    # nothing written to disk
+report = evaluate_run(reg, runs[0])
+
+for snippet, recs in reg.get("ensemble_sv").all_recommendations().items():
+    ...
+```
+
+`train_models` only writes to disk when given a models directory. A workflow
+model round-trips through `WorkflowModel.to_json()`.
+
+## Power curve (experimental)
+
+`predict_power_curve` turns a predicted run into a binned power curve with a
+copy of Bio-Pype's power estimate that is bundled with this package.
+
+**Known issue:** when Bio-Pype is importable in the same environment, the
+package tries to use Bio-Pype's own `pipeline_power_curve` instead, and with
+current Bio-Pype that call fails with a `TypeError`. Training, prediction of
+resources and timeline, evaluation and recommendations are not affected.
+
+## Recurrent retraining
+
+`train_models` is idempotent — point it at the growing dumps directory and it
+rebuilds every workflow model from the full corpus, so new runs simply sharpen
+the estimates. Schedule it every few hours, e.g. cron:
+
+```cron
+0 */4 * * * pype-runtime-models train /path/to/dumps --out /path/to/models \
+    >> /var/log/pype_models.log 2>&1
+```
+
+## Package layout
+
+```
+pype_runtime_models/
+  ingest.py      Run/Job parsing, snippet name parsing, driver sizes
+  units.py       memory / time requirement parsing
+  provenance.py  module/registry provenance + pluggable identity key
+  gpu.py         vendor-neutral GPU-class key + display name guess
+  workflow.py    identity detection (provenance + signature fallback)
+  features.py    per-step training samples, metric list
+  regression.py  numpy constant/linear/power fitting + driver cleaning
+  model.py       StepModel / WorkflowModel / PipelineView / ModelRegistry
+  train.py       train_models / load_models (module-level pooling)
+  predict.py     predict_run / predict_power_curve (GPU band, pipeline view)
+  evaluate.py    evaluate_run (per-step + overall, GPU-adjusted grading)
+  power.py       power estimate (bundled copy of Bio-Pype's, see Power curve)
+  cli.py         argparse entrypoint
+  tests/         self-contained smoke test (no pytest needed)
+```
+
+The smoke test is not part of the published package. From a source checkout,
+with a directory of runtime dumps:
+`python -m pype_runtime_models.tests.test_smoke dumps/`
+
+Source and issues: <https://codeberg.org/bio-pype/bio-pype-runtime-models>

bio_pype_runtime_models-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+pype_runtime_models/__init__.py,sha256=vIeLLymWIdcqolbunVP1Zx5W_LD8PUQwZvM5QUVh28M,1895
+pype_runtime_models/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+pype_runtime_models/cli.py,sha256=oKnzcFhKiIZEvi38974Lwj8hbWmoVJwe5Ybx6nykZ6s,7770
+pype_runtime_models/evaluate.py,sha256=c3PZIKUXwtcRI9kGbDIrbow8bCBfSBmetraOKeBulJg,8009
+pype_runtime_models/features.py,sha256=FYut4gHuo493zJkukloyR37t00gDZKaSn9w7oa1AFEs,4794
+pype_runtime_models/gpu.py,sha256=HI-e1hZhulKes_G5eLUMLlcPCjfs3fYXDUEIdPE8Vaw,4131
+pype_runtime_models/ingest.py,sha256=1k96l72LoGfcKYry7Lvp3MovVc54YrLLkaybArDJANE,9854
+pype_runtime_models/model.py,sha256=W9Pt1ZSIVn5dJjvEpJNeselchFwtZYcRrTllu7TsGBw,22111
+pype_runtime_models/power.py,sha256=1H0GpSuE3xENi-kHB7g6WJzRHn3KDfnFulNgGpcoJj4,5898
+pype_runtime_models/predict.py,sha256=WKiX1-thl6pBGNbw6vbxu66ua5aus9hyugovaTH4iIY,7848
+pype_runtime_models/provenance.py,sha256=nun0BMCsbqMtBNqgv0ja_VEjSyV21vAyGLWeK9Fimks,4109
+pype_runtime_models/regression.py,sha256=ELxrGItU2Nlj9T6wdOK1yPJCDbh-86ELQ2LVzhJau1Y,9098
+pype_runtime_models/train.py,sha256=qgF1Y56HdGBgH4FB24GRvgW4MA7n3T5f_wdks61wcno,7881
+pype_runtime_models/units.py,sha256=zmuQA_NMVhOJg76v5qLgBJ1zKE1QbOzGdHdJ0eFWZwI,2362
+pype_runtime_models/workflow.py,sha256=h4IXuE1jcZuRXSn91GV3qeba-8LzZ630LcgYWfkyilw,2816
+bio_pype_runtime_models-0.1.0.dist-info/METADATA,sha256=5JTdC80k4DURU7qwt-_j25V1-FweGTcgqW3jRS7LUKA,13610
+bio_pype_runtime_models-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+bio_pype_runtime_models-0.1.0.dist-info/entry_points.txt,sha256=Ky6vP0b1kbCCqDS3dHBQR6O8qh5beZxDQLfWJP9uDGA,69
+bio_pype_runtime_models-0.1.0.dist-info/top_level.txt,sha256=2A3h6AnHAQ7RPwRv75qrlKKpRtoFOKSmDG3E1BMasx8,20
+bio_pype_runtime_models-0.1.0.dist-info/RECORD,,

bio_pype_runtime_models-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bio_pype_runtime_models-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pype-runtime-models = pype_runtime_models.cli:main

bio_pype_runtime_models-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pype_runtime_models

pype_runtime_models/__init__.py

@@ -0,0 +1,57 @@
+"""pype_runtime_models — learn resource / timeline / power models from bio-pype runtime dumps.
+
+The package turns a directory of runtime-dump JSON files (one per pipeline run,
+as produced by dumping the runtime database) into per-workflow predictive models
+that can:
+
+* detect which workflow a runtime object belongs to,
+* predict per-step duration / memory / CPU and the run timeline from a single
+  input size,
+* flag steps whose resource use is driven by input size and recommend whether the
+  default ``requirements`` value should go up or down,
+* synthesise the pipeline power curve for a predicted run, and
+* evaluate a finished run (overall and per-step) against the learned baseline.
+
+Typical use::
+
+    from pype_runtime_models import train_models, load_models, predict_run, evaluate_run
+
+    reg = train_models("dumps/", "models/")          # recurrent retraining entrypoint
+    reg = load_models("models/")
+    pred = predict_run(reg, "ensemble_sv_TO", input_size_bytes=50e9)
+    report = evaluate_run(reg, "dumps/somerun.json")
+"""
+
+from __future__ import annotations
+
+from .ingest import Job, Run, iter_runs, load_run
+from .provenance import Provenance, extract_provenance, identity_key
+from .workflow import WorkflowSignature, detect_identity, detect_workflow
+from .model import StepModel, WorkflowModel, PipelineView, ModelRegistry
+from .train import train_models, load_models
+from .predict import predict_run, predict_power_curve
+from .evaluate import evaluate_run
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Job",
+    "Run",
+    "load_run",
+    "iter_runs",
+    "Provenance",
+    "extract_provenance",
+    "identity_key",
+    "WorkflowSignature",
+    "detect_identity",
+    "detect_workflow",
+    "StepModel",
+    "WorkflowModel",
+    "PipelineView",
+    "ModelRegistry",
+    "train_models",
+    "load_models",
+    "predict_run",
+    "predict_power_curve",
+    "evaluate_run",
+]

pype_runtime_models/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pype_runtime_models/cli.py

@@ -0,0 +1,214 @@
+"""Command-line interface.
+
+    python -m pype_runtime_models train    <dumps_dir> --out models/
+    python -m pype_runtime_models predict   models/ <workflow> --input-size 50gb
+    python -m pype_runtime_models power      models/ <workflow> --input-size 50gb
+    python -m pype_runtime_models evaluate   models/ <dump.json>
+    python -m pype_runtime_models recommend  models/ [<workflow>]
+    python -m pype_runtime_models workflows  models/
+    python -m pype_runtime_models quality    models/
+    python -m pype_runtime_models gpu        models/ [<workflow>]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Optional
+
+from .evaluate import evaluate_run
+from .predict import predict_power_curve, predict_run
+from .train import load_models, train_models
+from .units import parse_mem_bytes
+
+
+def _print_json(obj) -> None:
+    json.dump(obj, sys.stdout, indent=1, default=str)
+    sys.stdout.write("\n")
+
+
+def _parse_size(value: Optional[str]) -> Optional[float]:
+    if value is None:
+        return None
+    return parse_mem_bytes(value)
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="pype_runtime_models", description=__doc__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    t = sub.add_parser("train", help="fit/retrain models from a dumps directory")
+    t.add_argument("dumps_dir")
+    t.add_argument("--out", help="directory to write models into")
+    t.add_argument("--min-step-samples", type=int, default=3)
+    t.add_argument("--min-workflow-runs", type=int, default=1)
+    t.add_argument(
+        "--identity", choices=["module", "pipeline", "registry"], default="module",
+        help="grouping identity: module (default, pools shared snippets), pipeline, or registry",
+    )
+
+    pr = sub.add_parser("predict", help="predict per-step resources + timeline")
+    pr.add_argument("models_dir")
+    pr.add_argument("workflow", help="identity key (module) or a pipeline name")
+    pr.add_argument("--pipeline", help="pipeline timeline to use (module mode)")
+    pr.add_argument("--input-size", help="input size, e.g. 50gb or raw bytes")
+    pr.add_argument("--gpu-class", help="target GPU class (e.g. 700W); omit for a fleet band")
+    pr.add_argument("--full", action="store_true", help="include per-step detail")
+
+    pw = sub.add_parser("power", help="predict the pipeline power curve")
+    pw.add_argument("models_dir")
+    pw.add_argument("workflow")
+    pw.add_argument("--pipeline")
+    pw.add_argument("--input-size")
+    pw.add_argument("--gpu-class")
+    pw.add_argument("--bin-minutes", type=float, default=30.0)
+
+    gp = sub.add_parser("gpu", help="show learned per-GPU-class duration factors")
+    gp.add_argument("models_dir")
+    gp.add_argument("workflow", nargs="?")
+
+    ev = sub.add_parser("evaluate", help="grade a finished run against the baseline")
+    ev.add_argument("models_dir")
+    ev.add_argument("dump")
+    ev.add_argument("--full", action="store_true", help="include per-step detail")
+
+    rc = sub.add_parser("recommend", help="requirement recommendations per step")
+    rc.add_argument("models_dir")
+    rc.add_argument("workflow", nargs="?")
+    rc.add_argument("--changes-only", action="store_true")
+
+    wl = sub.add_parser("workflows", help="list trained workflows")
+    wl.add_argument("models_dir")
+
+    ql = sub.add_parser("quality", help="data-quality report (partial runs, dropped outliers)")
+    ql.add_argument("models_dir")
+
+    args = p.parse_args(argv)
+
+    if args.cmd == "train":
+        reg = train_models(
+            args.dumps_dir,
+            args.out,
+            min_step_samples=args.min_step_samples,
+            min_workflow_runs=args.min_workflow_runs,
+            identity_mode=args.identity,
+            verbose=True,
+        )
+        _print_json(
+            {
+                "trained_at": reg.trained_at,
+                "identity_mode": reg.identity_mode,
+                "workflows": {
+                    n: {"n_runs": w.n_runs, "steps": len(w.steps), "pipelines": list(w.pipelines)}
+                    for n, w in reg.workflows.items()
+                },
+                "saved_to": args.out,
+            }
+        )
+        return 0
+
+    if args.cmd == "workflows":
+        reg = load_models(args.models_dir)
+        _print_json(
+            {
+                n: {
+                    "n_runs": w.n_runs,
+                    "steps": len(w.steps),
+                    "identity_mode": w.identity_mode,
+                    "pipelines": {p: v.n_runs for p, v in w.pipelines.items()},
+                    "module_paths": w.provenance.get("module_paths", []),
+                    "versions": w.provenance.get("versions", []),
+                }
+                for n, w in reg.workflows.items()
+            }
+        )
+        return 0
+
+    if args.cmd == "quality":
+        reg = load_models(args.models_dir)
+        _print_json(reg.quality)
+        return 0
+
+    if args.cmd == "predict":
+        reg = load_models(args.models_dir)
+        out = predict_run(
+            reg, args.workflow, _parse_size(args.input_size), args.gpu_class, args.pipeline
+        )
+        if not args.full:
+            out["steps"] = [
+                {"snippet": s["snippet"], "start_offset_s": s["start_offset_s"],
+                 "duration_s": round(s["predicted"].get("duration_seconds", 0.0), 1),
+                 "duration_gpu_band_s": s.get("duration_gpu_band_s"),
+                 "mem_max_mb": round(s["predicted"].get("memory_rss_mb_max", 0.0), 1)}
+                for s in out["steps"]
+            ]
+        _print_json(out)
+        return 0
+
+    if args.cmd == "power":
+        reg = load_models(args.models_dir)
+        _print_json(
+            predict_power_curve(
+                reg, args.workflow, _parse_size(args.input_size),
+                args.bin_minutes, gpu_class=args.gpu_class, pipeline=args.pipeline,
+            )
+        )
+        return 0
+
+    if args.cmd == "gpu":
+        from .gpu import guess_gpu_name
+        reg = load_models(args.models_dir)
+        names = [args.workflow] if args.workflow else list(reg.workflows)
+        result = {}
+        for name in names:
+            wf = reg.get(name)
+            if wf is None:
+                continue
+            steps = {}
+            for step, sm in wf.steps.items():
+                if not sm.gpu_classes:
+                    continue
+                steps[step] = {
+                    "classes_seen": sm.gpu_classes,
+                    "duration_factors": {
+                        f"{c} ({guess_gpu_name(c)})": round(v, 3)
+                        for c, v in sm.gpu_duration_factor.items()
+                    },
+                }
+            if steps:
+                result[name] = steps
+        _print_json(result)
+        return 0
+
+    if args.cmd == "evaluate":
+        reg = load_models(args.models_dir)
+        out = evaluate_run(reg, args.dump)
+        if not args.full and "steps" in out:
+            out["steps"] = [s for s in out["steps"] if s.get("flags")]
+        _print_json(out)
+        return 0
+
+    if args.cmd == "recommend":
+        reg = load_models(args.models_dir)
+        names = [args.workflow] if args.workflow else list(reg.workflows)
+        result = {}
+        for name in names:
+            wf = reg.get(name)
+            if wf is None:
+                continue
+            wf_out = {}
+            for step, recs in wf.all_recommendations().items():
+                items = [r.to_json() for r in recs
+                         if not args.changes_only or r.action in ("increase", "decrease")]
+                if items:
+                    wf_out[step] = items
+            result[name] = wf_out
+        _print_json(result)
+        return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())