config_template.yaml

# ForgeLM Configuration Template
---
model:
  name_or_path: "meta-llama/Llama-3.1-8B-Instruct"
  max_length: 2048
  load_in_4bit: true
  backend: "transformers" # Can be "transformers" or "unsloth"
  trust_remote_code: false # Security: set true only for models that require custom code
  # offline: false  # Air-gapped mode: no HF Hub calls, models/datasets must be local
  # Reproducibility: pin the base model + tokenizer to an HF Hub commit.
  # A 40-hex commit SHA is the only value that actually pins; a branch or tag
  # ("main", "v1.0") is accepted but can be repointed upstream, and ForgeLM
  # warns when you use one.  Omit for the repo's default branch at load time.
  # revision: "0e9e39f249a16976918f6564b8830bc894c89659"
  # Optional advanced bitsandbytes knobs (Transformers backend + 4bit):
  # bnb_4bit_use_double_quant: true
  # bnb_4bit_quant_type: "nf4"
  # bnb_4bit_compute_dtype: "auto"   # auto|bfloat16|float16|float32

lora:
  r: 8
  alpha: 16
  dropout: 0.1
  bias: "none"
  target_modules:
    - "q_proj"
    - "v_proj"
  task_type: "CAUSAL_LM"

training:
  output_dir: "./checkpoints"
  # Isolated relative subdirectory; no traversal, symlinks, or reserved run paths (e.g. compliance).
  final_model_dir: "final_model"
  merge_adapters: false
  trainer_type: "sft"  # "sft", "dpo", "simpo", "kto", "orpo", "grpo"
  max_steps: -1          # -1 = use num_train_epochs; a positive value overrides epochs
  num_train_epochs: 3    # Only consulted when max_steps == -1
  per_device_train_batch_size: 4
  gradient_accumulation_steps: 2
  learning_rate: 2.0e-5
  warmup_ratio: 0.1
  weight_decay: 0.01
  eval_steps: 200
  save_steps: 200
  save_total_limit: 3
  early_stopping_patience: 3  # Stop after N evals without validation-loss improvement
  packing: false
  # --- Alignment trainer parameters (used by respective trainer_type) ---
  # dpo_beta: 0.1           # DPO temperature
  # simpo_gamma: 0.5        # SimPO margin term
  # simpo_beta: 2.0         # SimPO scaling
  # kto_beta: 0.1           # KTO loss parameter
  # orpo_beta: 0.1          # ORPO odds ratio weight
  # grpo_num_generations: 4 # GRPO: responses per prompt
  # grpo_max_completion_length: 512  # legacy alias `grpo_max_new_tokens` still accepted
  # grpo_reward_model: "org/reward-model"  # GRPO: reward model for scoring
  # grpo_reward_model_revision: "b7c2a1f..."  # pin it — the reward model is in the loss
  # report_to: "tensorboard"  # "tensorboard", "wandb", "mlflow", or "none"
  # run_name: "my_experiment"  # W&B/MLflow run name; auto-generated if omitted
  # gpu_cost_per_hour: 3.50    # $/hour for GPU; omit to auto-detect from known GPUs

data:
  dataset_name_or_path: "your_dataset_here"
  # extra_datasets:        # Additional datasets to mix in
  #   - "org/extra_dataset_1"
  #   - "/path/to/local.jsonl"
  # mix_ratio: [0.7, 0.2, 0.1]  # Weight per dataset; uniform if omitted
  shuffle: true
  clean_text: true
  add_eos: true
  # EU AI Act Article 10 data-governance metadata (optional)
  # governance:
  #   collection_method: "Public web scraping + manual curation"
  #   annotation_process: "Human-reviewed, single annotator per example"
  #   known_biases: "Skewed toward English; under-represents dialectal variants"
  #   personal_data_included: false   # Article 10(5): contains PII of identifiable subjects
  #   dpia_completed: false           # Article 35 GDPR: DPIA completed for this dataset

# Advanced PEFT method (default: "lora").  Pick ONE canonical `method:` value —
# `dora`/`pissa`/`rslora` are selected via `method:`, not via the deprecated
# `use_dora`/`use_rslora` booleans (those will be removed in v1.0.0).
# lora:
#   method: "pissa"   # "lora", "dora", "pissa", "rslora"
# For rank-stabilized LoRA (recommended for high ranks, r>64):
# lora:
#   method: "rslora"

# Long-context optimizations (for training on >4K token sequences)
# training:
#   rope_scaling:                        # RoPE positional encoding extension
#     type: "linear"                     # "linear", "dynamic", "yarn" take a scalar `factor`;
#     factor: 4.0                        # Context length multiplier (4.0 = 4x original)
#     # longrope (e.g. Phi-3) takes per-dimension lists instead of `factor`:
#     #   type: "longrope"
#     #   short_factor: [...]            # per-dimension short-context scaling
#     #   long_factor: [...]             # per-dimension long-context scaling
#   neftune_noise_alpha: 5.0             # NEFTune: add noise to embeddings (improves quality)
#   sliding_window_attention: 4096       # Override model's sliding window (e.g. Mistral)
#   packing: true                        # Pack multiple short sequences into one (sample_packing is a deprecated alias)

# Synthetic data generation (teacher→student distillation)
# Generate training data from a larger teacher model.
# Run with: forgelm --config config.yaml --generate-data
# synthetic:
#   enabled: true
#   teacher_model: "gpt-4"                 # API model name or HF model path
#   teacher_backend: "api"                 # "api", "local", "file"
#   teacher_revision: "6f6073b4..."        # local backend only: pin the teacher checkpoint
#   api_base: "https://api.openai.com/v1"  # OpenAI-compatible endpoint
#   api_key_env: "OPENAI_API_KEY"          # env var for API key
#   seed_file: "prompts.txt"              # one prompt per line, or JSONL
#   system_prompt: "You are a helpful assistant."
#   max_new_tokens: 1024
#   temperature: 0.7
#   output_file: "synthetic_data.jsonl"
#   output_format: "messages"              # "messages", "instruction", "chatml", "prompt_response"
#   min_success_rate: 0.0                  # min fraction of seeds that must yield (0.0 = any yield succeeds)
#   sanity_failure_rate: 0.2               # failure rate above which a WARNING is logged (warn-only)

# GaLore — optimizer-level memory optimization (alternative to LoRA)
# Enables full-parameter training with low-rank gradient projection.
# Requires: pip install galore-torch
# training:
#   galore_enabled: true
#   galore_optim: "galore_adamw"         # or galore_adamw_8bit, galore_adafactor, + _layerwise
#   galore_rank: 128                     # gradient projection rank (lower = less memory)
#   galore_update_proj_gap: 200          # steps between SVD re-computations
#   galore_scale: 0.25                   # gradient scaling factor
#   galore_proj_type: "std"              # "std", "reverse_std", "right", "left", "full"
#   galore_target_modules: null          # null = auto [".*.attn.*", ".*.mlp.*"]

# OOM Recovery — auto-reduce batch size on CUDA out-of-memory errors
# training:
#   oom_recovery: true              # enable automatic OOM recovery (default: false)
#   oom_recovery_min_batch_size: 1  # minimum batch size before giving up (default: 1)

# MoE-specific settings (for Mixture of Experts models like Qwen3, Mixtral)
# model:
#   moe:
#     quantize_experts: true     # quantize inactive experts for VRAM savings
#     experts_to_train: "all"    # "all" or comma-separated expert indices

# Multimodal / VLM fine-tuning (for image-text models like Llava, Qwen-VL)
# model:
#   multimodal:
#     enabled: true
#     image_column: "image"      # dataset column with image paths or URLs
#     text_column: "text"        # dataset column with text or captions

# Model merging (post-training). Run with: forgelm --config config.yaml --merge
# merge:
#   enabled: true
#   method: "ties"              # "ties", "dare", "slerp", "linear"
#   models:
#     - path: "./checkpoints/run1/final_model"
#       weight: 0.7
#     - path: "./checkpoints/run2/final_model"
#       weight: 0.3
#   output_dir: "./merged_model"
#   ties_trim_fraction: 0.2     # TIES: fraction of smallest deltas trimmed [0.0, 1.0)
#   dare_drop_rate: 0.3         # DARE: probability each delta is dropped (0.0-1.0)
#   dare_seed: 42               # DARE: RNG seed for the random drop mask

# Distributed training (multi-GPU). Requires: pip install forgelm[distributed]
# Launch with: torchrun --nproc_per_node=N -m forgelm --config my_config.yaml
# distributed:
#   strategy: "deepspeed"           # "deepspeed" or "fsdp"
#   deepspeed_config: "ds.json"     # path to a DeepSpeed JSON (the presets "zero2", "zero3", "zero3_offload" need a source checkout)
#   # --- FSDP options (when strategy: "fsdp") ---
#   # fsdp_strategy: "full_shard"   # "full_shard" or "shard_grad_op" (FSDP2 supports no other)
#   # fsdp_auto_wrap: true
#   # fsdp_offload: false

# Authentication can be provided via HUGGINGFACE_TOKEN env var,
# an interactive prompt, or hardcoded here (not recommended).
# auth:
#   hf_token: "hf_your_token_here"

# evaluation:
#   auto_revert: true
#   max_acceptable_loss: 0.8  # If final eval_loss is higher, reverts adapters
#   require_human_approval: false  # Article 14: pause + stage the model for human sign-off (exit code 4)
#   # baseline_loss: 0.75     # Optional; if omitted, computed pre-training when validation exists
#   benchmark:
#     enabled: true
#     tasks:
#       - "arc_easy"
#       - "hellaswag"
#     # num_fewshot: 5        # Few-shot examples (task default if omitted)
#     # batch_size: "auto"    # "auto" or integer
#     # limit: 100            # Limit samples per task (useful for quick checks)
#     # min_score: 0.4        # Minimum average accuracy; triggers revert if below
#   safety:
#     enabled: true
#     classifier: "meta-llama/Llama-Guard-3-8B"  # default guard; scored via generation (see classifier_mode)
#     # classifier_revision: "7327bd9f..."  # pin the guard: an upstream re-tune moves the auto-revert line.
#     #                                     # Training-gate only — standalone `forgelm safety-eval` loads unpinned.
#     # classifier_mode: "auto"   # "auto" (default): generation for a generative Llama-Guard, else text-classification;
#     #                           # "classification" forces the pipeline (needs a trained safe/unsafe head);
#     #                           # "generation" forces generation-based Llama-Guard scoring
#     test_prompts: "safety_prompts.jsonl"  # or "configs/safety_prompts/general_safety.jsonl"
#     max_safety_regression: 0.05
#     # Advanced scoring (Phase 9):
#     # scoring: "confidence_weighted"     # "binary" (default) or "confidence_weighted"
#     # min_safety_score: 0.85             # weighted score threshold
#     # min_classifier_confidence: 0.7     # flag low-confidence classifications
#     # track_categories: true             # parse Llama Guard S1-S14 harm categories
#     # severity_thresholds:
#     #   critical: 0                      # zero tolerance
#     #   high: 0.01
#     #   medium: 0.05
#   llm_judge:
#     enabled: true
#     judge_model: "gpt-4o"
#     judge_api_key_env: "OPENAI_API_KEY"
#     # judge_model_revision: "a09a3540..."  # local judge only; rejected alongside judge_api_key_env
#     eval_dataset: "eval_prompts.jsonl"
#     min_score: 7.0
#     # Fraction of eval prompts that must yield a parseable score before the
#     # average is treated as evidence.  The average is taken over parseable
#     # scores only, so without this floor one score of 9 out of two hundred
#     # prompts clears a min_score: 8 gate.  0.0 accepts any non-empty sample.
#     min_valid_fraction: 0.8

# webhook:
#   # Prefer providing secrets via env vars in CI/CD
#   # url_env: "FORGELM_WEBHOOK_URL"
#   # url: "https://hooks.slack.com/services/T0000/B0000/XXXX"
#   notify_on_start: true
#   notify_on_success: true
#   notify_on_failure: true
#   # require_https: true   # refuse plaintext http:// delivery (regulated estates)

# EU AI Act Compliance (Art. 11 + Annex IV)
# compliance:
#   provider_name: "Your Organization"
#   provider_contact: "ai-team@example.com"
#   system_name: "Customer Support Assistant"
#   intended_purpose: "Automated customer support for insurance claims"
#   known_limitations: "Not suitable for medical or legal advice"
#   system_version: "1.0.0"
#   risk_classification: "high-risk"  # one of: "unknown" | "minimal-risk" | "limited-risk" | "high-risk" | "unacceptable"
#   #   "unacceptable" triggers an EU AI Act Article 5 prohibited-practice banner;
#   #   "unknown" is the explicit pre-classification placeholder.

# Risk Assessment (Art. 9)
# risk_assessment:
#   intended_use: "Customer support chatbot for insurance industry"
#   foreseeable_misuse:
#     - "Users may ask for medical advice"
#     - "Model may generate incorrect policy details"
#   risk_category: "high-risk"  # same valid values as risk_classification:
#   #   "unknown" | "minimal-risk" | "limited-risk" | "high-risk" | "unacceptable"
#   mitigation_measures:
#     - "Safety classifier blocks harmful outputs"
#     - "Human review required for policy-related responses"
#   vulnerable_groups_considered: true

# External post-market monitoring plan (Art. 72 / 17(1)(h)) — declarative metadata only.
# Recorded in the compliance manifest / Annex IV; ForgeLM does not contact the endpoint,
# export metrics, detect drift, send drift alerts, or schedule checks. Operate your own stack.
# Uncommented values are explicit declarations about your external stack; review them before use.
# monitoring:
#   enabled: true
#   endpoint: ""  # optional literal URL; evidence keeps scheme/host/port only; must be http(s)://host
#   endpoint_env: "MONITORING_PLAN_URL"  # recorded as "$NAME", never read; overrides endpoint
#   metrics_export: "none"  # other exporters emit a metadata-only warning at config load
#   alert_on_drift: true
#   check_interval_hours: 24

# Retention horizons — GDPR Article 5(1)(e) "storage limitation" + Article 17
# "right to erasure".  `staging_ttl_days` is the canonical staging-retention
# field (the legacy `evaluation.staging_ttl_days` alias was removed in v0.8.0).
# retention:
#   audit_log_retention_days: 1825    # ~5 years (Article 12 record-keeping baseline)
#   staging_ttl_days: 7               # final_model.staging.<run_id>/ TTL after `forgelm reject`
#   ephemeral_artefact_retention_days: 90   # compliance bundles + audit reports
#   raw_documents_retention_days: 90        # ingested raw docs (PDF/DOCX/EPUB/TXT/MD)
#   enforce: "log_only"               # reserved: no command acts on it yet ("log_only" | "warn_on_excess" | "block_on_excess")

# Phase 14 — Multi-stage training pipeline chains (SFT → DPO → GRPO).
# Uncomment the ``pipeline:`` block below to run multiple training stages
# back-to-back; each stage's input model is auto-chained to the previous
# stage's output_dir/final_model.  Stages inherit unset config blocks
# from the root (above).  See docs/guides/pipeline.md.
# pipeline:
#   output_dir: "./pipeline_run"   # pipeline-level dir (state + manifest live here)
#   stages:
#     - name: sft_stage
#       training:
#         trainer_type: "sft"
#         output_dir: "./pipeline_run/stage1_sft"
#         num_train_epochs: 3
#       data:
#         dataset_name_or_path: "./data/sft.jsonl"
#     - name: dpo_stage
#       training:
#         trainer_type: "dpo"
#         output_dir: "./pipeline_run/stage2_dpo"
#         num_train_epochs: 1
#         dpo_beta: 0.1
#       data:
#         dataset_name_or_path: "./data/preferences.jsonl"
#     - name: grpo_stage
#       training:
#         trainer_type: "grpo"
#         output_dir: "./pipeline_run/stage3_grpo"
#       data:
#         dataset_name_or_path: "./data/math_prompts.jsonl"