Getting Started

This page walks through preparing the trainer block and running a training job end to end. trainer wraps a pinned SWE-Lego LLaMA-Factory checkout and the swe_data_process converter package, so most setup is about getting those into a single uv environment.

Prerequisites

• 8× A100/H100 GPUs — full fine-tuning with DeepSpeed ZeRO-3 targets a single 8-GPU node.
• uv — used to build and run the training environment.
• CUDA 12.8 toolchain available on the node (the installer pulls CUDA 12.8 PyTorch wheels).
• Training data — a Harbor job_dir, a ready-made Hugging Face LF dataset/file, or a local LF JSON.
• A base model — a Hub model ID or local model directory (the active profile uses Qwen/Qwen3.5-35B-A3B-Base).

1. Build the environment

Create the uv training environment at meta_info.environment.sft_uv (default artifacts/env/lf):

bash scripts/install_env.sh

This installs CUDA 12.8 PyTorch 2.10.0, editable repos/swe_data_process[llm] and the patched LLaMA-Factory plus metrics/DeepSpeed/Liger requirements, source-built flash-attn, Qwen3.5's flash-linear-attention and tilelang dependencies, and wandb. See Inputs & Outputs for the env layout.

2. Point the config at your inputs

Edit config.yaml → runtime_info.input:

• source.type — the dataset source: harbor_job (convert Harbor trajectories, the default), hf_lf (a ready-made LF dataset on the HuggingFace Hub), or local_lf (a local LF json). See Input sources.
• For harbor_job: set source.scaffold + source.job_dir. For hf_lf: set source.hf_hub_url; optionally set source.hf_file_name to select exactly one repository file, otherwise use hf_subset/hf_split. For local_lf: set source.lf_path.
• conversion.data_name — the dataset name (the LF file and registered dataset key derive from it).
• model.model_name_or_path — a Hub model ID or local base-model directory.
• training.* — hyperparameters (template, cutoff length, batch size, learning rate, epochs, …).
• infrastructure.n_gpus_per_node — the GPU count on this node.

See Configuration for what each field controls.

3. Validate the config

Run the dry-run preflight. It checks the pinned repos, the uv environment, source-specific data settings, converter modules when applicable, the model, output directory, and GPU count — without side effects:

bash scripts/dryrun.sh

Fix anything it reports before launching a run.

4. (Optional) Prepare data only

To convert and inspect the dataset before committing to a training run, run the data-only pipeline:

bash scripts/dataprep.sh

For harbor_job, this runs conversion and writes the LF dataset under artifacts/data/lf_data/ without registering it or training. Ready-made hf_lf/local_lf sources have nothing to convert, so the command exits early. See Data Pipeline.

5. Launch a run

scripts/start.sh runs the dry run, then the full pipeline (obtain/convert LF data → dataset registration → training), and archives the run on exit:

bash scripts/start.sh

To run the pipeline directly without the archive wrapper, use bash scripts/train.sh. See Training for what each step does.

6. Inspect results

Training writes to:

artifacts/model/<run>/      # checkpoints, trainer_log.jsonl, trainer_state.json, *_results.json
artifacts/logs/<run>_<ts>.log   # console log

After a successful run, config.yaml → runtime_info.output is updated with the checkpoint path, metrics, and artifact paths. For a live view, open the dashboard.

Operating with the agent plugin

If you operate the block through its Claude plugin, the same lifecycle maps to slash commands:

/root:check trainer     # preflight: config, repos, env, source data, GPUs
/trainer:setup           # build the uv environment and validate the config
/root:run trainer       # execute scripts/start.sh and archive
/trainer:run             # trainer-specific run procedure + post-run bookkeeping
/trainer:dashboard       # launch / summarize the training dashboard