fix(docs): install commands named SDK extras removed in 0.10.0 (backend#1858)

[LukasWodka]

Fixes tracebloc/backend#1858

The bug

tools-help/tracebloc.mdx documented two install commands whose extras do not exist:

# pip install "tracebloc[boosting]>=0.8.1"   # XGBoost / CatBoost / LightGBM
# pip install "tracebloc[survival]>=0.8.1"   # lifelines / scikit-survival

pip does not fail on an unknown extra. It warns, installs the base package, and exits 0 — so the reader gets a core-only SDK and finds out later as an ImportError, far from the command that caused it.

Reproduced on Python 3.12, against the real package

$ pip install --dry-run "tracebloc[boosting]>=0.8.1"
Collecting tracebloc>=0.8.1 (from tracebloc[boosting]>=0.8.1)
  Using cached tracebloc-0.18.1-py3-none-any.whl.metadata (12 kB)
...
WARNING: tracebloc 0.18.1 does not provide the extra 'boosting'
...
Would install Pygments-2.20.0 certifi-2026.7.22 charset-normalizer-3.5.0 idna-3.18
  markdown-it-py-4.2.0 mdurl-0.1.2 numpy-2.5.2 pandas-3.0.5 psutil-7.2.2
  python-dateutil-2.9.0.post0 requests-2.34.2 rich-15.0.0 six-1.17.0
  termcolor-3.3.0 tqdm-4.70.0 tracebloc-0.18.1 urllib3-2.7.0

EXIT_CODE=0

No xgboost, no catboost, no lightgbm. Same for [survival]:

$ pip install --dry-run "tracebloc[survival]>=0.8.1"
WARNING: tracebloc 0.18.1 does not provide the extra 'survival'
Would install ... tracebloc-0.18.1 urllib3-2.7.0
EXIT_CODE=0

The removal happened in 0.10.0, not 0.14.0

Read from published Provides-Extra on PyPI:

version	extras
0.8.0	tensorflow, pytorch, sklearn, huggingface, boosting, survival, all, dev
0.8.1	… + catboost, lightgbm, xgboost, lifelines, scikit-survival (umbrellas still present)
0.10.0	tensorflow, pytorch, sklearn, catboost, lightgbm, xgboost, lifelines, scikit-survival, all, dev
0.18.1 (current)	same as 0.10.0

So boosting, survival and huggingface all disappeared at 0.10.0. Eight published releases have shipped without them.

A second, related defect found while verifying

join-use-case/start-training.mdx told readers to create a Python 3.9 environment. The SDK has required >=3.11,<3.13 since 0.10.0. Combined with the stale >=0.8.1 floor, that does not error — it silently installs the ancient 0.8.1:

$ python3.10 -m pip install --dry-run "tracebloc[pytorch]>=0.8.1"
Would install ... timm-1.0.28 torch-2.2.2 ... tracebloc-0.8.1 ...
EXIT_CODE=0

The stale floor is the root cause of both symptoms. With the corrected floor, the same unsupported interpreter now fails loudly instead:

$ python3.10 -m pip install --dry-run "tracebloc[pytorch]>=0.18.1"
ERROR: Ignored the following versions that require a different python version:
  0.10.0 Requires-Python <3.13,>=3.11; ... 0.18.1 Requires-Python <3.13,>=3.11
ERROR: Could not find a version that satisfies the requirement tracebloc[pytorch]>=0.18.1
  (from versions: 0.0.1, 0.8.0, 0.8.1)
ERROR: No matching distribution found for tracebloc[pytorch]>=0.18.1

What changed

• tools-help/tracebloc.mdx — [boosting]/[survival] replaced with the per-library extras; added a note that the umbrellas (and [huggingface]) were removed in 0.10.0 and that pip fails silently on a bad extra; stated the Python requirement.
• join-use-case/start-training.mdx — python=3.9 → python=3.12; version floors bumped.
• Every >=0.8.1 floor in the repo → >=0.18.1 (10 specs across the two pages — these were the only files with tracebloc[...] lines).
• scripts/check-sdk-extras.py + .github/workflows/sdk-extras-check.yml — the regression guard.

Every replacement extra was verified to resolve and pull the right libraries:

xgboost            OK (resolves)
catboost           OK (resolves)
lightgbm           OK (resolves)
lifelines          OK (resolves)
scikit-survival    OK (resolves)
pytorch            OK (resolves)
tensorflow         OK (resolves)
sklearn            OK (resolves)
all                OK (resolves)

$ pip install --dry-run "tracebloc[catboost,lightgbm,xgboost]>=0.18.1"
Would install ... catboost-1.2.10 ... lightgbm-4.7.0 ... xgboost-3.4.0
$ pip install --dry-run "tracebloc[lifelines,scikit-survival]>=0.18.1"
Would install ... lifelines-0.30.3 ... scikit-survival-0.28.0 ...

The guard, and proof it catches this

Mintlify validates links and MDX; a fenced code block is opaque to it. The new check extracts every tracebloc[...] spec, resolves the version its floor selects, and asserts each extra is in that release's Provides-Extra.

Against the pre-fix content — it fails, naming both bugs:

$ python3 scripts/check-sdk-extras.py orig.mdx orig-start.mdx
2 problem(s) found:

  orig.mdx:20: tracebloc[boosting] does not exist in 0.18.1 (the version '>=0.8.1'
    resolves to). Available: all, catboost, dev, lifelines, lightgbm, pytorch,
    scikit-survival, sklearn, tensorflow, xgboost
  orig.mdx:21: tracebloc[survival] does not exist in 0.18.1 (the version '>=0.8.1'
    resolves to). Available: all, catboost, dev, lifelines, lightgbm, pytorch,
    scikit-survival, sklearn, tensorflow, xgboost

Note: pip warns and exits 0 on an unknown extra, so a wrong extra here silently
installs the core SDK only.
EXIT=1

Against the fixed tree — green:

$ make check-sdk-extras
python3 scripts/check-sdk-extras.py
Checked 10 documented 'tracebloc[...]' spec(s); latest release is 0.18.1.
All documented extras exist in the versions they resolve to.
EXIT=0

It also runs weekly on cron, because these docs can rot without the docs changing — a floating >= floor re-points at each new release.

Test plan / caveats

• make check-sdk-extras — green (above).
• make check (mint broken-links) — not run: the Mintlify CLI is not installed in this environment. No links were added or changed except one intra-page <Note>, so link risk is low, but this check is genuinely unrun on my side and CI/preview should confirm it.
• This repo has no test suite, and there was no existing check covering install commands — that gap is what this PR adds. I am not implying pre-existing coverage.
• The Makefile comment asserting "no content gate in CI" is now false and is updated in this PR.
• Not verified: the downstream ImportError itself, which needs a real model-upload flow against a running backend. What is directly shown is that pip exits 0 with the boosting libraries absent.

---

Note

Low Risk
Documentation and validation-only changes; no application runtime or auth paths are modified.

Overview
Fixes stale pip install "tracebloc[...]" examples that documented removed umbrella extras ([boosting], [survival]) and a low >=0.8.1 floor that could resolve to releases without those extras while pip still exits 0.

Docs: tools-help/tracebloc.mdx now lists per-library extras (xgboost, lifelines, etc.), bumps floors to >=0.18.1, documents Python 3.11–3.12, and warns that bad extras fail silently. join-use-case/start-training.mdx switches the conda env to Python 3.12 and aligns install lines with the same version floor.

Automation: Adds scripts/check-sdk-extras.py to scan .md/.mdx for tracebloc[...] specs and assert each extra exists in the PyPI release the specifier resolves to. Wired into make check-all / make check-sdk-extras and .github/workflows/sdk-extras-check.yml (PR/push, weekly cron, manual dispatch).

^{Reviewed by Cursor Bugbot for commit f7a8a6c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[saadqbal]

Verified every extra against PyPI Provides-Extra: [boosting]/[survival]/[huggingface] are gone as of 0.10.0, and the new [sklearn] (pulls catboost/lightgbm/xgboost), [xgboost], [lifelines,scikit-survival], [pytorch] (pulls transformers+peft) all resolve on 0.18.1. Floors and Python 3.11/3.12 requirement are right, and the specs are consistent across both pages. Nice, thorough fix with a real guard.

One nit inline: the new Python note describes the old floor's behavior.

[shujaatTracebloc]

Verified against live PyPI rather than just reading the diff:

• tracebloc latest is 0.18.1 and requires_python is >=3.11,<3.13 — the new "Requires Python 3.11 or 3.12" line and the python=3.12 conda bump are both correct.
• Published extras on 0.18.1 are exactly all, catboost, dev, lifelines, lightgbm, pytorch, scikit-survival, sklearn, tensorflow, xgboost. Every extra the docs now name exists; boosting/survival/huggingface are genuinely gone.
• Checked the replacement guidance the script can't validate: [sklearn] in pyproject.toml really does pull catboost, lightgbm and xgboost, so "incl. XGBoost / CatBoost / LightGBM" is accurate.
• Confirmed the new workflow actually executed here (SDK install extras [pull_request] -> success) — it is not a gate that silently no-ops on the PR that introduces it.

The framing is the valuable part: pip warning-and-exiting-0 on an unknown extra is exactly why this rotted for eight releases, and the weekly schedule: trigger is the right call given a floating >= floor re-points itself without the docs changing.

Three non-blocking nits for later, all outside backend#1858's scope:

• parse_version maps 0.19.0rc1 to (0,19,0), so a prerelease could tie/win in max() even though pip excludes prereleases by default. Same class: meta["releases"] includes yanked versions.
• ~= is accepted by SPEC_RE but resolved as if it were >=, so ~=0.18.1 would wrongly resolve past 0.19.x. Nothing in the docs uses it today.
• extras_cache is annotated dict[str, set[str]] but stores None on fetch failure. Handled correctly by the caller, just an inaccurate annotation.

LGTM.

[saadqbal]

Reword nails it — clears my earlier comment. With the floor at >=0.18.1 (only 0.18.1 resolves, Requires-Python >=3.11,<3.13), an old Python gets a loud No matching distribution found, not a 0.8.1 fallback; that fallback was only ever possible under the old >=0.8.1 floor. Checked against PyPI: extras all valid, boosting/survival/huggingface gone since 0.10.0, both files consistent on Python 3.11/3.12. 👍