Architecture¶

Maturity: verified

RFFM separates reusable learning primitives from one executable pretraining workflow and from provider submission. That boundary keeps a canonical dataset, model, objective, or checkpoint usable without importing application lifecycle or Google Cloud behavior.

Pretraining data flow¶

Hydra YAML groups
  -> strict Pydantic pretraining configuration
  -> canonical dataset registry lookup
  -> process-visible canonical bundle
  -> semantic RF samples and collated batches
  -> I/Q normalization, metadata normalization, fixed patching
  -> catalog-selected model, objective, and optimizer
  -> bounded optimizer steps
  -> metrics, checkpoints, terminal attempt manifest

For managed execution, an independent shell adapter adds this outer layer:

immutable training image + launch YAML
  -> Gemini Enterprise Agent Platform CustomJob submission
  -> python -m rffm.cli.main pretrain

The adapter supplies provider identities and the mounted Cloud Storage bucket namespace. It does not calculate loss, decide checkpoint compatibility, or write application metrics.

Responsibility layers¶

Canonical data and signal preparation¶

src/rffm/data/ reads the common canonical bundle and returns semantic RF records. src/rffm/signal/ owns I/Q normalization, physical-metadata normalization, fixed patching, and the model-input record. These modules do not select an experiment or write run artifacts.

Model and training primitives¶

src/rffm/model/ owns the causal-patch model contract and the shipped tiny implementation. src/rffm/training/ owns next-patch prediction, guarded optimizer steps, bounded diagnostics, and generic checkpoint save/load.

These are reusable library capabilities. They do not own run IDs, provider job IDs, application directories, or terminal manifests.

Pretraining application¶

src/rffm/applications/pretrain/ composes configuration, selects code-owned component registrations, creates datasets and dataloaders, owns run and attempt identity, executes the bounded loop, publishes artifacts atomically, and validates resume compatibility before state mutation.

The command dispatcher in src/rffm/cli/main.py is an application entry point, not a general-purpose training library API.

Provider adapter¶

infra/runtime/submit_vertex_ai_training.sh validates a separate launch YAML, requires an immutable image digest and full source revision, persists the launch configuration, and submits one CustomJob. Gemini Enterprise Agent Platform owns provisioning, status, logs, and worker lifecycle.

Capability limitations¶

There is no landed train/validation epoch loop, scheduler, latest/best checkpoint selection, exact sampler or random-number-generator resume, dataset mixture, distributed strategy, sweep runner, callback system, post-training application, or evaluator. Those concepts remain in the design sources and are not part of the current application graph.