[Wave 3] Medium — Docs: docs/guides/library_api.md #577

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

Findings

• DOC-D2B04-013 (docs, Medium) — docs/guides/library_api.md: broken example — report.near_duplicate_summary['pairs'] is the duplicate count
  severity Medium
  Where. docs/guides/library_api.md lifecycle and Airflow snippets (near_duplicate_summary["pairs"]) · type: broken example
  The document says. report.near_duplicate_summary['pairs'] is the duplicate count
  What the code does. near_duplicate_summary keys are method, pairs_per_split, hamming_threshold; ['pairs'] raises KeyError. The reference doc (lines 70,134) correctly uses pairs_per_split, so the two docs contradict each other.
  Code references. scripts/s5_misc.py output, forgelm/data_audit/_types.py:141
  Proposed correction. Sum report.near_duplicate_summary['pairs_per_split'].values() in both guide snippets.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D2B04-014 (docs, Medium) — docs/guides/library_api.md: misleading — Anything the CLI does, the library can do — minus the exit-code mapping and the structured logging setup.
  severity Medium
  Where. docs/guides/library_api.md:9 (Turkish mirror: docs/guides/library_api-tr.md:9) · type: misleading
  The document says. Anything the CLI does, the library can do — minus the exit-code mapping and the structured logging setup.
  What the code does. forgelm.all (32 names) covers config, training, dataset prep, audit, PII/secrets, dedup signatures, the audit log, the verify_* family, the webhook, benchmark and synthetic. It has no public entry for ingest, export, deploy, chat, merge, purge, reverse-pii, approve/reject/approvals, safety-eval, judge or doctor; those modules are Internal by the tier policy.
  Code references. forgelm/__init__.py:77-119, forgelm/__init__.py:142-177
  Proposed correction. Replace with: 'The library covers configuration, training, dataset audit, PII/secrets utilities, audit logging and artefact verification. Ingest, export, deploy, chat, merge, purge, reverse-pii, approvals, safety-eval and doctor are CLI-only public surfaces.'
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D2B04-015 (docs, Medium) — docs/guides/library_api.md: broken example — Quick start installs forgelm[ingestion] (or [ingestion,security]). The lifecycle example then calls audit_dataset(..., enable_pii_ml=True).
  severity Medium
  Where. docs/guides/library_api.md:33-37, docs/guides/library_api.md:85-89 (Turkish mirror: docs/guides/library_api-tr.md:33-37, docs/guides/library_api-tr.md:86-89) · type: broken example
  The document says. Quick start installs forgelm[ingestion] (or [ingestion,security]). The lifecycle example then calls audit_dataset(..., enable_pii_ml=True).
  What the code does. enable_pii_ml=True needs Presidio from the separate ingestion-pii-ml extra plus a spaCy model download, neither of which [ingestion] provides. Without them audit_dataset raises ImportError with the install hint (runtime, presidio absent).
  Code references. pyproject.toml:141-148, pyproject.toml:165-167, forgelm/data_audit/_pii_ml.py:97-98, forgelm/data_audit/_orchestrator.py:307-316
  Proposed correction. Either drop enable_pii_ml=True from the lifecycle example, or add pip install 'forgelm[ingestion-pii-ml]' and python -m spacy download en_core_web_lg to the quick start.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D2B04-016 (docs, Medium) — docs/guides/library_api.md: false claim — A runnable notebook (notebooks/library_api_example.ipynb) ships with the wheel and walks the same three patterns.
  severity Medium
  Where. docs/guides/library_api.md:54 (Turkish mirror: docs/guides/library_api-tr.md:54) · type: false claim
  The document says. A runnable notebook (notebooks/library_api_example.ipynb) ships with the wheel and walks the same three patterns.
  What the code does. notebooks/ holds 11 notebooks, and library_api_example.ipynb is not among them. The wheel packages only forgelm*, so no notebook ships with it; the installed wheel contains only forgelm/ and its dist-info.
  Code references. pyproject.toml:250-252, notebooks/ (directory listing)
  Proposed correction. Delete the sentence, or ship the notebook and describe it as part of the repository rather than the wheel.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D2B04-017 (docs, Medium) — docs/guides/library_api.md: wrong detail — Operator identity is required. The chain attributes every event to $FORGELM_OPERATOR, and if the variable is unset and FORGELM_ALLOW_ANONYMOUS_OPERATOR is n…
  severity Medium
  Where. docs/guides/library_api.md:76-77, docs/guides/library_api.md:228, docs/guides/library_api.md:237 (Turkish mirror: docs/guides/library_api-tr.md:77-78, docs/guides/library_api-tr.md:229, docs/guides/library_api-tr.md:238) · type: wrong detail
  The document says. Operator identity is required. The chain attributes every event to $FORGELM_OPERATOR, and if the variable is unset and FORGELM_ALLOW_ANONYMOUS_OPERATOR is not 1, the run aborts loudly.
  What the code does. When FORGELM_OPERATOR is unset, AuditLogger falls back to getpass.getuser()@​hostname. It raises ConfigError only when no username can be resolved (KeyError/OSError/ImportError from getuser) and FORGELM_ALLOW_ANONYMOUS_OPERATOR != "1".
  Code references. forgelm/compliance.py:192-227
  Proposed correction. Rewrite as: 'If FORGELM_OPERATOR is unset, ForgeLM records <user>@<hostname>. Only when no username can be resolved (e.g. a random-UID container) does it refuse to start, unless FORGELM_ALLOW_ANONYMOUS_OPERATOR=1. Set FORGELM_OPERATOR explicitly in CI.'
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

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