[Wave 4] Low/info — Docs: forgelm/config.py #769

Wave 4 · 16 finding(s) in 16 fix package(s). One pass over this document; keep the Turkish mirror in sync.

Findings

• DOC-BFIELD-020 (docs, Low) — forgelm/config.py: wrong detail — load_in_4bit: Load the model in 4-bit NF4 quantisation (QLoRA path).
  severity Low
  Where. forgelm/config.py:259 · type: wrong detail
  The document says. load_in_4bit: Load the model in 4-bit NF4 quantisation (QLoRA path).
  What the code does. The quant type comes from bnb_4bit_quant_type (fp4 is allowed). On a host without CUDA the model loads in full precision, with a warning (model.py:450-462).
  Code references. forgelm/model.py:441-462

• DOC-BFIELD-021 (docs, Low) — forgelm/config.py: misleading — bitsandbytes 4-bit settings (double quant, quant type, compute dtype).
  severity Low
  Where. forgelm/config.py:286-297 (bnb_4bit_use_double_quant, bnb_4bit_quant_type, bnb_4bit_compute_dtype) · type: misleading
  The document says. bitsandbytes 4-bit settings (double quant, quant type, compute dtype).
  What the code does. These apply only on the transformers backend with CUDA (model.py:441-449). The unsloth loader (model.py:326-337) passes only load_in_4bit, max_seq_length, trust_remote_code and revision. bnb_4bit_*, training.rope_scaling and training.sliding_window_attention are silently ignored there, and no validator warns.
  Code references. forgelm/model.py:326-337, forgelm/model.py:441-449

• DOC-BFIELD-022 (docs, Low) — forgelm/config.py: wrong detail — merge_adapters: When SFT finishes, merge LoRA adapters into the base model.
  severity Low
  Where. forgelm/config.py:457-460 · type: wrong detail
  The document says. merge_adapters: When SFT finishes, merge LoRA adapters into the base model.
  What the code does. save_final_model (trainer.py:1711-1749) merges for every trainer_type. config.py:1719-1724 only warns for non-SFT.
  Code references. forgelm/trainer.py:1711-1749, forgelm/config.py:1719-1724

• DOC-BFIELD-023 (docs, Low) — forgelm/config.py: misleading — packing: Pack short sequences into one to maximise GPU compute utilisation.
  severity Low
  Where. forgelm/config.py:499-501 · type: misleading
  The document says. packing: Pack short sequences into one to maximise GPU compute utilisation.
  What the code does. Only the SFT branch consumes it (trainer.py:693). For orpo/dpo/simpo/kto/grpo the value is silently ignored.
  Code references. forgelm/trainer.py:693

• DOC-BFIELD-024 (docs, Low) — forgelm/config.py: wrong detail — galore_optim: _layerwise cuts peak by recomputing per-layer.
  severity Low
  Where. forgelm/config.py:551 · type: wrong detail
  The document says. galore_optim: _layerwise cuts peak by recomputing per-layer.
  What the code does. The layerwise variants perform the optimizer step per layer during backward; they recompute nothing. ForgeLM passes the value through to TrainingArguments.optim (trainer.py:547).
  Code references. forgelm/trainer.py:544-560

• DOC-BFIELD-026 (docs, Low) — forgelm/config.py: misleading — data.add_eos: Append the EOS token to every example.
  severity Low
  Where. forgelm/config.py:821-823 · type: misleading
  The document says. data.add_eos: Append the EOS token to every example.
  What the code does. It applies only to SFT text/messages/user-assistant formatting. Passthrough trainers (data.py:724) and multimodal (data.py:714-716) never append EOS.
  Code references. forgelm/data.py:714-733

• DOC-BFIELD-027 (docs, Low) — forgelm/config.py: misleading — max_safety_regression: Auto-revert triggers when exceeded. severity_thresholds: Auto-revert when exceeded.
  severity Low
  Where. forgelm/config.py:944 and forgelm/config.py:981 · type: misleading
  The document says. max_safety_regression: Auto-revert triggers when exceeded. severity_thresholds: Auto-revert when exceeded.
  What the code does. Exceeding either threshold fails the gate. Revert happens only when evaluation.auto_revert is true (default False, config.py:1191-1194) and the evaluation completed (trainer.py:1458-1466). Otherwise the model is kept. The sibling benchmark.min_score description states the auto_revert condition; these two do not.
  Code references. forgelm/trainer.py:1458-1466, forgelm/config.py:1191-1194, forgelm/safety/_gates.py:259-277

• DOC-BFIELD-028 (docs, Low) — forgelm/config.py: wrong detail — Below this the gate fails with an insufficient valid evidence reason
  severity Low · already tracked: PARTIALLY-FIXED CORE-04 — docs/roadmap/phase-16-trust-surface-hardening.md:371,378-379; CHANGELOG.md:67-74
  Where. forgelm/config.py:1114-1126 (JudgeConfig.min_valid_fraction, F09) · type: wrong detail
  The document says. Below this the gate fails with an insufficient valid evidence reason
  What the code does. The emitted reason is 'Insufficient valid judge evidence: only N/M ...' (judge.py:822-827, reproduced). A scraper matching the quoted phrase misses it.
  Code references. forgelm/judge.py:819-829
  Proposed correction. Quote the actual prefix Insufficient valid judge evidence.

• DOC-BFIELD-029 (docs, Low) — forgelm/config.py: misleading — Auto-computed when validation set exists.
  severity Low
  Where. forgelm/config.py:1209-1214 (EvaluationConfig.baseline_loss, F13) · type: misleading
  The document says. Auto-computed when validation set exists.
  What the code does. _measure_baseline_loss runs only when four conditions hold: a validation split exists, evaluation.auto_revert is true, baseline_loss is unset, and trainer_type is not grpo (trainer.py:1272-1285). With auto_revert false, no baseline is computed and no regression check happens.
  Code references. forgelm/trainer.py:1272-1285
  Proposed correction. 'Auto-computed pre-training when a validation split exists and auto_revert is true (not for GRPO).'

• DOC-BFIELD-033 (docs, Low) — forgelm/config.py: wrong detail — floored at 10s by the SSRF-guarded HTTP chokepoint
  severity Low
  Where. forgelm/config.py:1351-1355 (SyntheticConfig.api_timeout, F44) · type: wrong detail
  The document says. floored at 10s by the SSRF-guarded HTTP chokepoint
  What the code does. Values below 10 are rejected, not floored: the schema has ge=10, and safe_post raises HttpSafetyError when timeout < min_timeout (_http.py:547-548).
  Code references. forgelm/_http.py:547-548
  Proposed correction. 'minimum 10s (lower values are rejected)'.

• DOC-BFIELD-035 (docs, Low) — forgelm/config.py: misleading — a webhook timeout silently degrades the audit chain (webhook failure is best-effort)
  severity Low
  Where. forgelm/config.py:1478-1487 (WebhookConfig.timeout, F59) · type: misleading
  The document says. a webhook timeout silently degrades the audit chain (webhook failure is best-effort)
  What the code does. A webhook transport failure only logs a WARNING (webhook.py:175-240). The audit log and its hash chain are written independently and are not affected.
  Code references. forgelm/webhook.py:175-240
  Proposed correction. Replace with 'a timeout drops that notification (best-effort; the audit log is unaffected)'.

• DOC-BFIELD-036 (docs, Low) — forgelm/config.py: misleading — a plaintext http:// webhook URL is refused (the SSRF chokepoint raises) ... set True on a regulated estate to make cleartext delivery a hard failure
  severity Low
  Where. forgelm/config.py:1492-1500 (WebhookConfig.require_https, F61) · type: misleading
  The document says. a plaintext http:// webhook URL is refused (the SSRF chokepoint raises) ... set True on a regulated estate to make cleartext delivery a hard failure
  What the code does. safe_post raises HttpSafetyError, but _post_payload catches it, logs a WARNING and returns (webhook.py:175-182). There is no config-time validator. Reproduced: require_https=True with an http:// URL left notify_start() returning normally, and the run is not failed.
  Code references. forgelm/webhook.py:156-182
  Proposed correction. Say 'the notification is not sent (WARNING logged); the run continues', or add a model validator rejecting http:// URLs when require_https is true.

• DOC-BFIELD-037 (docs, Low) — forgelm/config.py: misleading — Days to retain ingested raw documents (PDF / DOCX / EPUB / TXT / Markdown) under the operator's ingestion-output directory ... Closes ghost-features Phase 18: Library API analysis & design (design-only) #23
  severity Low
  Where. forgelm/config.py:1576-1584 (RetentionConfig.raw_documents_retention_days, F67) · type: misleading
  The document says. Days to retain ingested raw documents (PDF / DOCX / EPUB / TXT / Markdown) under the operator's ingestion-output directory ... Closes ghost-features Phase 18: Library API analysis & design (design-only) #23
  What the code does. The scan only checks the fixed names <output_dir>/raw_documents and <output_dir>/ingestion_output (_purge.py:1291-1312). Nothing in forgelm/ (ingestion included) ever writes a raw_documents directory, and the horizon is only reported by purge --check-policy. The description also cites an internal tracker id (Phase 18: Library API analysis & design (design-only) #23) that is meaningless to users.
  Code references. forgelm/cli/subcommands/_purge.py:1291-1312
  Proposed correction. Name the exact scanned paths, state that the horizon is report-only, and drop the tracker reference.

• DOC-BFIELD-038 (docs, Low) — forgelm/config.py: wrong detail — When present, trainer_type is required (Pydantic's existing TrainingConfig validation enforces this).
  severity Low
  Where. forgelm/config.py:2053-2060 (PipelineStage.training, F87) · type: wrong detail
  The document says. When present, trainer_type is required (Pydantic's existing TrainingConfig validation enforces this).
  What the code does. TrainingConfig defaults trainer_type to 'sft' (config.py:461). The requirement is enforced by PipelineStage._training_block_must_set_trainer_type_explicitly (config.py:2078-2096) through model_fields_set. The effect stated is correct; the attribution is wrong.
  Code references. forgelm/config.py:461, forgelm/config.py:2078-2096
  Proposed correction. '(enforced by the PipelineStage validator)'.

• DOC-BLEGAL-249 (docs, Low) — forgelm/config.py: wrong detail — "audit logs at 5 years (Article 12 record-keeping obligation × statute-of-limitations buffer)"
  severity Low
  Where. forgelm/config.py:1532-1534 (RetentionConfig docstring) · type: wrong detail
  The document says. "audit logs at 5 years (Article 12 record-keeping obligation × statute-of-limitations buffer)"
  What the code does. Art. 12 sets no retention period. Logs are kept for at least six months (Art. 19(1), 26(6)) and documentation for 10 years (Art. 18(1)). Five years is a ForgeLM choice.
  Proposed correction. 'audit logs at 5 years (ForgeLM default; AI Act Art. 19/26(6) require >= 6 months for operational logs, Art. 18 keeps documentation 10 years)'.

• DOC-E2E-011 (docs, Low) — forgelm/config.py: misleading — notify_on_failure: POST a notify_failure event when training fails (any non-zero exit).
  severity Low
  Where. forgelm/config.py:1476 · type: misleading
  The document says. notify_on_failure: POST a notify_failure event when training fails (any non-zero exit).
  What the code does. Config/precheck exits (1) send nothing. Exit 3 sends training.reverted. Exit 4 sends approval.required under notify_on_success. training.failure is sent only when train() raises (exit 2) or on reject.
  Code references. forgelm/trainer.py:1694-1710
  Proposed correction. List the events the flag gates, as the user manual does.

Done when

• Every finding above is fixed or closed with a reason (tick it here).
• Code fixes carry a test; doc fixes update the Turkish mirror in the same PR.

_{Found by the October 2026 ForgeLM code and documentation review against commit cab2947. Code links point at that commit; line numbers may have moved since. Finding IDs (CR-…, DOC-…, TECH-…) are stable references for this backlog.}