First bounded training run¶

Maturity: verified

The command below is the real application entry point used by tests and the Gemini Enterprise Agent Platform submission adapter. It is bounded by optimizer-step count; it is not a train/validation loop or a model-quality evaluation.

Prerequisites¶

A run requires all of the following:

the source environment from Prepare a source checkout;
a complete canonical dataset bundle with manifest, signal HDF5, metadata Parquet, and persisted split files;
a dataset registry entry whose canonical location resolves in the process;
a writable application artifact root;
an NVIDIA CUDA GPU for the shipped preset, unless the exact override training.device=cpu selects CPU execution for a bounded local check.

The committed registry uses gs:// locations. A process resolving those URIs must receive a mounted bucket namespace such as Gemini Enterprise Agent Platform’s /gcs. The application does not authenticate, mount, or download Cloud Storage objects.

Run the application¶

PYTHONPATH=src:. uv run --project analysis/eda \
  python -m rffm.cli.main pretrain \
  --config-dir configs \
  --experiment radioml2018_one_step_npp \
  --run-id <logical-run-id> \
  --attempt-id <attempt-id> \
  --rffm-repository-root . \
  --gcs-bucket-namespace-root /gcs

run-id names the logical run. attempt-id names one execution attempt within that run and must differ from the parent attempt during resume. Both values must be safe path components.

The application writes under:

<artifact-root>/<run-id>/attempts/<attempt-id>/application/

Successful completion prints one JSON record describing the run ID, attempt ID, final global step, resolved configuration path, metrics path, checkpoint path, and terminal manifest path.

Local filesystem alternative¶

Tests replace the registry and artifact root with local paths and override the device to CPU. Use the tested configuration helpers in training/tests/pretrain_test_support.py as the executable local example. The repository does not ship a synthetic-fixture CLI or a packaged sample dataset, so this guide does not invent one.

What success proves¶

One completed optimizer step proves that the selected canonical data, configuration, model, objective, optimizer, finite-value guards, checkpoint, and artifact path compose. The accepted #62 evidence additionally proves a separate attempt can restore step 1 and advance to step 2 on a Gemini Enterprise Agent Platform L4 worker.

It does not prove convergence, classification accuracy, validation behavior, exact random-number-generator resume, or production-scale throughput.