Stable-tier ForgeTrainer is documented as ForgeTrainer(config) but the real signature is (model, tokenizer, config, dataset) (CR-A02-007) #430

Wave 1 · theme D1-8: Docs describing features that do not exist (doc side of code findings) · highest severity High · 1 finding(s) · effort small

Summary

A library user copies the documented stable-API snippet and it fails immediately.

Primary finding

CR-A02-007 — Stable-tier ForgeTrainer is documented as ForgeTrainer(config) but the real signature is (model, tokenizer, config, dataset)

severity High · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end

What happens. ForgeTrainer.init (trainer.py:340) requires model, tokenizer, config and dataset, while library_api_reference.md:54 and the headline library example call ForgeTrainer(config), which raises TypeError.

Where.

• forgelm/trainer.py:340 (confirmed)
• docs/reference/library_api_reference.md:46
• docs/reference/library_api_reference.md:175
• docs/reference/library_api_reference.md:242
• docs/guides/library_api.md:94
• forgelm/trainer.py:ForgeTrainer.init
• forgelm/config.py:2245
• docs/guides/library_api.md:88
• docs/design/library_api.md:55-60
• tools/check_library_api_doc.py:35-47

Evidence.

• scripts/ft_doc_example.py: signature (self, model: Any, tokenizer: Any, config: Any, dataset: Dict[str, Any]); the documented example raises TypeError: ForgeTrainer.__init__() missing 3 required positional arguments: 'tokenizer', 'config', and 'dataset'.
• fpy -C new: forgelm.ForgeTrainer(config) -> TypeError: ForgeTrainer.init() missing 3 required positional arguments: 'tokenizer', 'config', and 'dataset'. inspect.signature(ForgeTrainer.init) = (self, model: Any, tokenizer: Any, config: Any, dataset: Dict[str, Any]). Real call sites forgelm/cli/_training.py:148 and forgelm/cli/_pipeline.py:1566 use the 4-argument form. docs/reference/library_api_reference.md:54, :175, :242; docs/guides/library_api.md:94; docs/design/library_api.md sect…

Recommended fix. Document the real four-argument constructor with the get_model_and_tokenizer + prepare_dataset preamble, or add a config-only factory. Extend check_library_api_doc to compare signatures.

Acceptance criteria

• A regression test reproduces the failure scenario and asserts the corrected behaviour.
• Documentation listed above is corrected in English and in its Turkish mirror in the same PR.
• Every finding in this issue is resolved or explicitly closed with a reason.

_{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.}