EulerForge CLI Reference

# Output in English
eulerforge --lang en train --preset configs/presets/qwen3.5_0.8b_dense_lora_sft.yml

# Output in Japanese
eulerforge --lang ja bench --preset configs/bench/sft_target_only.yml

export EULERFORGE_LANG=en
eulerforge train --preset ...    # Output in English

eulerforge train [OPTIONS]

# SFT → DPO pipeline example
eulerforge train --preset configs/presets/qwen3.5_0.8b_dense_lora_dpo.yml \
    --set model_name=outputs/sft/final \
    --output-dir outputs/dpo

# Inspect fields (explore input file structure)
eulerforge convert --task sft --input data/sft_10k.jsonl --print-sample-flat

# Map mode (flat fields)
eulerforge convert --task sft --input data/custom.jsonl --output data/out.jsonl \
    --map prompt=instruction --map response=output

# Map mode (nested fields — automatic dot-path flattening)
eulerforge convert --task prompted_preference --input data/dpo_10k.jsonl --output data/dpo_10k_raw.jsonl \
    --map prompt=instruction.value --map chosen=chosen.value --map rejected=rejected.value

# Recipe mode (messages array)
eulerforge convert --task sft --input data/sft_10k.jsonl --output data/sft_10k_raw.jsonl \
    --recipe sft_messages --messages-expr json_record.messages

# Validate mode (schema validation without conversion)
eulerforge convert --task sft --input data/sft_10k_raw.jsonl --validate

eulerforge preprocess --task TASK --input RAW.jsonl --output PROCESSED.jsonl --model-name MODEL

eulerforge bench [OPTIONS]

Phase 1: Load target → run inference on all samples → unload
Phase 2: Load baseline → run inference on all samples → unload (when enabled)
Phase 3: Load judge → evaluate all samples → unload (when enabled)
Phase 4: Aggregate results → same output format as before

bench:
  task: sft                                  # sft | preference
  data_path: data/sft_1k_bench_raw.jsonl
  sample:
    k: 10
    seed: 42
    shuffle: true
  generation:
    max_new_tokens: 256
    temperature: 0.7
    top_p: 0.95
  models:
    target:
      # Method A: API model (Ollama/OpenAI/Gemini)
      provider: ollama                       # ollama | openai | gemini
      model: "qwen3:0.6b"
      base_url: "http://localhost:11434/v1"

      # Method B: Training output directory (automatic checkpoint resolution)
      # output_dir: "outputs/run_20260301_120000"
      # checkpoint: "final"                  # final | latest | best (default: final)
      # device: "auto"                       # default: auto
      # dtype: "auto"                        # default: auto

      # Method C: Specify HF model directory directly
      # provider: local_hf                   # can be omitted (auto-configured)
      # model_dir: "outputs/run_20260301_120000/final"
    baseline:
      enabled: false
      provider: ollama
      model: "qwen3:4b"
    judge:
      enabled: false
      provider: ollama
      model: "gemma3:27b"
      mode: pointwise                        # pointwise | pairwise
      mitigate_position_bias: true           # pairwise A/B swap (2 rounds)
  output:
    out_dir: outputs/bench
    save_jsonl: true
    print_examples: true
    print_max_chars: 1500

# Using an API model
eulerforge bench --preset configs/bench/sft_target_only.yml

# Load final checkpoint from training output directory
eulerforge bench --preset configs/bench/sft_local.yml \
  --target-output-dir outputs/run_20260301_120000

# Use latest checkpoint
eulerforge bench --preset configs/bench/sft_local.yml \
  --target-output-dir outputs/run_20260301_120000 --checkpoint latest

# Specify model directory directly
eulerforge bench --preset configs/bench/sft_local.yml \
  --target-model-dir outputs/run_20260301_120000/final

# Specify GPU (load target on GPU 1 when judge is using GPU 0)
eulerforge bench --preset configs/bench/sft_local.yml \
  --target-output-dir outputs/run_20260301_120000 --target-device cuda:1

# Override configuration
eulerforge bench --preset configs/bench/sft_target_only.yml --set bench.sample.k=20

# Validate only
eulerforge bench --preset configs/bench/sft_target_only.yml --validate-only

# Preview samples (no model calls)
eulerforge bench --preset configs/bench/sft_target_only.yml --dry-run

training:
  type: orpo
  orpo_lambda: 1.0  # ORPO term weight (required, positive)

training:
  type: rm
  # RewardHead is auto-generated (hidden_size → 1)

training:
  type: ppo
  ppo:
    clip_range: 0.2     # PPO clipping range
    kl_coef: 0.1        # KL penalty coefficient
    epochs: 4           # PPO update epochs per batch
    max_gen_len: 64     # Maximum generation length
    temperature: 1.0    # Sampling temperature
  reward_model:
    model_name: "path/to/model"  # Reward model path
    checkpoint_path: ""          # Checkpoint (optional)

model:
  load_precision:
    mode: int4               # fp32 | fp16 | bf16 | int8 | int4
    compute_dtype: bf16      # Compute dtype for int8/int4 operations (fp16 | bf16)
    quant_type: nf4           # int4 only: nf4 | fp4
    double_quant: true        # int4 only
    dequantize_on_train: true # Auto-dequantize when base_ffn becomes trainable

# Method 1: Already tokenized processed JSONL
data:
  format: processed
  path: data/sft_processed.jsonl

# Method 2: Raw JSONL (auto-preprocessed and cached during training)
data:
  format: raw
  task: prompted_preference
  path: data/dpo_10k_raw.jsonl
  max_length: 512
  # num_proc: default = 50% of CPU cores (automatic)
  # cache_dir: default = outputs/.cache (shared cache across runs)
  #
  # Cache filename convention: {input_filename}_{task}_{model_name}_len{max_length}.jsonl
  # Example: dpo_10k_raw_prompted_preference_qwen3.5-0.8b-base_len512.jsonl
  # Automatically reused when parameters match (no re-preprocessing)

# Method 3 (legacy): Specify processed_data_path directly
processed_data_path: data/sft_processed.jsonl

Data: processed dataset row 0 missing 'input_ids'
Fix: Run `eulerforge preprocess ...` or set data.format=raw with schema mapping
See: docs/tutorials/en/00_data_preprocessing.md

Data Config: data.task='sft' is incompatible with training.type='dpo'. Task 'sft' produces data for sft, ppo training
Fix: Set --set training.type=sft or change data.task to match
See: docs/tutorials/en/00_data_preprocessing.md

--set training.lr=2e-5
--set injection.lora_r=32
--set training.phases.1.step=100  # Update a specific list element's field (sparse)
--set training.phases.0.trainable=[lora,attn_lora]  # List-of-list element value

CLI --set overrides > YAML preset values

outputs/run_YYYYMMDD_HHMMSS/
├── resolved_config.json    # Full resolved configuration (for reproducibility)
├── checkpoint-latest/      # Latest checkpoint
│   ├── model files...
│   ├── tokenizer files...
│   └── training_state.pt   # Optimizer, scheduler, step, best_val_loss
├── checkpoint-best/        # Best validation loss checkpoint
│   └── ...
└── final/                  # Final model after training completes
    └── ...

MoE Config: moe.router_z_loss_coef is required for MoE strategies.
Fix: Set moe.router_z_loss_coef: 0.001 (ST-MoE recommended)
See: docs/tutorials/en/09_moe_stability_and_validation.md

eulerforge train --preset PRESET.yml --preflight

[Phase2] Step 400/600 (micro 4500/6000) | Loss: 0.1234 | LR: 1.00e-05 | ... | Handoff[expert_lora=0.75, attn_lora=0.80, ffn_lr_mult=2.50]

pip install eulerforge[tb]

logging:
  metrics_level: advanced      # "minimal" | "advanced"
  tensorboard:
    enabled: true              # Enable TensorBoard logging (default: false)
    log_dir: "outputs/tb"      # Log directory
  log_interval: 50             # Write to TensorBoard every N steps
  max_experts_log: 16          # Log detailed stats for top N experts in advanced mode

eulerforge train --preset PRESET.yml --metrics-level advanced

# Validate spec only (dry-run)
eulerforge grid configs/grid/sft_random_search.yml --dry-run

# Run
eulerforge grid configs/grid/sft_random_search.yml

# Specify project root explicitly
eulerforge grid configs/grid/sft_random_search.yml --project-root /path/to/project

pip install eulerforge[hpo]

<output_root>/
├── trial_0000/
│   ├── metrics.jsonl       # Per-step metrics (train/total_loss, etc.)
│   └── checkpoint-latest/
├── trial_0001/
│   └── ...
├── summary.json            # Overall results (best_trial + all_trials)
└── summary.csv

from eulerforge import load_model

@dataclass
class LoadedModel:
    model: nn.Module           # eval mode
    tokenizer: PreTrainedTokenizer
    metadata: ModelMetadata

@dataclass
class ModelMetadata:
    strategy: str              # "dense_lora" | "moe_expert_lora" | "mixture_lora" | "none"
    backbone: str              # "qwen3" | "llama" | "gemma3" | ""
    path_type: str             # "run_dir" | "checkpoint_dir"
    checkpoint_dir: str        # Actual checkpoint directory path
    lora_config: dict | None   # {"lora_r": int, "lora_alpha": float}
    structure_preserved: bool  # Whether MoE/MixtureLoRA structure is preserved
    load_precision: str | None # "fp32" | "fp16" | "bf16" | "int8" | "int4" | None

from eulerforge import load_model

# 1. Load from training output directory (final checkpoint)
result = load_model("outputs/run_20260311_163425")
print(result.metadata.strategy)     # "moe_expert_lora"
print(result.metadata.backbone)     # "qwen3"

# 2. Load best checkpoint
result = load_model("outputs/run_20260311_163425", checkpoint="best")

# 3. Specify checkpoint directory directly
result = load_model("outputs/run_20260311_163425/final", device="cuda:0")

# 4. Quantized loading (int4/int8)
result = load_model("outputs/run_20260311_163425", load_precision="int4")
result = load_model("outputs/run_20260311_163425", load_precision="bf16")

# 5. Inference
messages = [{"role": "user", "content": "Hello"}]
text = result.tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = result.tokenizer(text, return_tensors="pt").to(result.model.device)
with torch.no_grad():
    out = result.model.generate(**inputs, max_new_tokens=128)
print(result.tokenizer.decode(out[0], skip_special_tokens=True))

# 6. Using metadata
if result.metadata.structure_preserved:
    print("This checkpoint preserves the MoE structure")
if result.metadata.lora_config:
    print(f"LoRA r={result.metadata.lora_config['lora_r']}")

# dense_lora → merged HF model
eulerforge export-hf --checkpoint outputs/run_20260311_163425 --output ./exported

# MoE → custom_moe HF model (load with trust_remote_code=True)
eulerforge export-hf --checkpoint outputs/run_moe --output ./exported_moe

# dry-run (print plan only)
eulerforge export-hf --checkpoint outputs/run --output ./out --dry-run

# validate-only
eulerforge export-hf --checkpoint outputs/run --output ./out --validate-only

eulerforge pretrain [OPTIONS]

# Device
device: "cuda:0"             # cuda:0, cuda:1, cpu

# Model (EulerStack export directory)
model_dir: "outputs/full_hybrid_moe"
trust_remote_code: true

# Tokenizer (specify separately if not in model_dir)
tokenizer: "gpt2"

# Data
data:
  path: "data/dolma_10k.jsonl"
  text_column: "text"        # text key in JSONL
  max_length: 1024
  packing: true              # packed chunking (concatenate → split to fixed length)

# Training
training:
  max_steps: 500
  batch_size: 2
  grad_accum_steps: 4
  lr: 3.0e-4
  weight_decay: 0.1
  warmup_steps: 50
  max_grad_norm: 1.0
  log_steps: 10
  save_steps: 250
  dtype: "float32"           # Hybrid models (Hyena/RetNet) require float32
  amp: false                 # FFT ops don't support bf16 → disabled
  seed: 42

# Basic run
eulerforge pretrain --preset configs/presets/pretrain/eulerstack_hybrid_moe.yml

# Override settings
eulerforge pretrain --preset ... --set training.max_steps=1000 --set training.lr=1e-4

# Validate only
eulerforge pretrain --preset ... --validate-only

# Specify output directory
eulerforge pretrain --preset ... --output-dir outputs/my_pretrain

outputs/pretrain_YYYYMMDD_HHMMSS/
├── pretrain_config.json         # Config snapshot
├── metrics.jsonl                # Per-step loss, lr
├── checkpoint-250/              # Mid-training checkpoint
│   ├── config.json
│   ├── model.safetensors
│   └── tokenizer files...
└── final/                       # Final model
    ├── config.json
    ├── model.safetensors
    └── tokenizer files...