docs: PreprocessingConfig knobs — fix stale claims + document the six levers

[LukasWodka]

Closes tracebloc/backend#1189 (RFC 0003 §8/§9 rollout debt — tracebloc/backend#1091).

What

• how-training-works.mdx: the "not configurable from the notebook" claim is gone; tabular step 2 (imputation strategy enum, on/off, knn privacy exclusion, BYO guidance) and step 6 (scaler allowlist, QuantileTransformer exclusion) rewritten; TTE bullet knob-aware; TSF gains its imputation paragraph (timestamp-ordered ffill + fitted fallback).
• hyperparameters.mdx: new Preprocessing (Tabular & Time Series) section — all six knobs with a runnable example, the when-to-disable guidance (sklearn Pipeline / native-NaN models), the privacy note (knn + QuantileTransformer memorize raw data), and the defaults-unchanged promise.

⛔ Merge gate (docs-exception content rule: never document unshipped behaviour)

Draft until ALL of:

• tracebloc-engine promotion carries #474/#475/#476/#499 (L1b/L2/L3b-fill) to staging → master/prod images — currently on develop only
• tracebloc-engine#507 (L3a forecasting imputation) merged + promoted, and the SDK-side TSF gate widening released — on the released SDK the handle_missing_values/imputation_strategy guard does not include time-series-forecasting; that widening rides tracebloc-py-package#335 (review finding)
• tracebloc-engine#508 + tracebloc-py-package#335 + tracebloc/backend#1192 (indicator knob, all three halves) merged + promoted/released

backend#1095 is already on master ✅; SDK#287 is on master ✅.

Known gap, out of scope here: the docs have no time-series-classification use-case section at all — flagged separately.

🤖 Generated with Claude Code

---

Note

Low Risk
Markdown-only changes with no runtime impact; main risk is documenting behavior before it is released, which the author’s merge gate addresses.

Overview
Documentation-only update for RFC 0003 preprocessing knobs: readers are told preprocessing is configurable from the notebook, not fixed platform-only behavior.

how-training-works.mdx replaces the “not configurable from the notebook” replication note with a link to the new hyperparameters section and a reminder to match actual experiment settings. Tabular preprocessing steps 2 (imputation on/off, strategy enum, BYO-model guidance, why knn is excluded) and 6 (scaler allowlist, QuantileTransformer exclusion) are expanded. Time series forecasting gains an imputation paragraph (timestamp-ordered forward-fill plus fitted fallbacks). Time-to-event (PyTorch) preprocessing is aligned with the same knob vocabulary as tabular.

hyperparameters.mdx adds Preprocessing (Tabular & Time Series) with example training_plan.* calls for all six levers, when to disable built-in imputation, privacy rationale for excluded options, and a defaults-unchanged note.

The PR description flags a merge gate: do not ship until engine/SDK releases expose the documented behavior (including TSF imputation and TSC missingness_indicators).

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

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tracebloc	🟢 Ready	View Preview	Jul 23, 2026, 8:55 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tracebloc	🟡 Building	–	Jul 23, 2026, 8:54 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[LukasWodka]

👋 Heads-up — Code review queue is at 32 / 30

Above the WIP limit. The team convention is to review existing PRs before opening new work.

Open PRs currently in Code review (oldest first):

• .github#64 — fix(closure-router): add GH_TOKEN to closing-PR lookup so issues mirror their closing PR's Status · author: @LukasWodka · no reviewer assigned
• averaging-service#206 — feat(docker): containerize averaging-service (CPU-only) + build CI (#1163) · author: @saadqbal · no reviewer assigned
• backend#1153 — WS-C: delegate CheckModelMixin rewrite path to SDK ModelFileRewriter + pin tracebloc==0.14.0 (#1101) · author: @divyasinghds · reviewer: @saqlainsyed007
• backend#1188 — test(checker): vendor SDK rewrite golden corpus as WS-C contract gate (#1101) · author: @shujaatTracebloc · no reviewer assigned
• backend#1193 — Reject non-federatable sklearn estimators (KNN / GaussianProcess) at upload (#923) · author: @shujaatTracebloc · reviewer: @divyasinghds
• backend#1200 — Revert "chore(deps): bump torch from 2.11.0 to 2.13.0" · author: @saqlainsyed007 · no reviewer assigned
• cli#389 — fix(delete): verify the host-data wipe before printing ✔ (RFC-0003) · author: @saadqbal · reviewer: @LukasWodka
• cli#390 — feat(cli): auto-update — nudge + tracebloc upgrade (F1) · author: @LukasWodka · no reviewer assigned
• cli#391 — fix(push): stop progress bar colliding with staging log lines (D3) · author: @LukasWodka · no reviewer assigned
• cli#392 — feat(install): prefer ~/bin when already on PATH (B2, RFC 0001) · author: @LukasWodka · no reviewer assigned

Pull from review before opening new work. (This is a nudge from the kanban WIP check, not a block.)

[shujaatTracebloc]

Review — verified against source, not just the PR body

I checked the documented behaviour against the real code in tracebloc-engine, tracebloc-py-package, and backend (branch presence included). The content is accurate and well-written; the only real issue is timing/merge-safety.

✅ Merge gate is honest — every claim checks out

Gate claim	Reality	Status
engine #474/#475/#476/#499 "on develop only"	All 4 merged to develop; preprocessing code absent from origin/master	✅ correctly unchecked
engine#507 (TSF imputation)	Still OPEN — not even on develop (only on feat/505-forecasting-imputation)	✅ correctly unchecked
engine#508 + SDK#335 + backend#1192	engine#508 ✅ + backend#1192 ✅ on develop; SDK side still unmerged (on feat/472-missingness-indicators-sdk)	✅ correctly unchecked
"backend#1095 already on master ✅"	True — commit b1b2b464 + migration 0487_experiment_preprocessing_knobs on origin/master	✅ accurate
"SDK#287 on master ✅"	True — the five knob methods are on origin/master	✅ accurate

Nothing is over- or under-claimed.

✅ Technical accuracy — documented API matches the code exactly

• SDK (training_plan): handle_missing_values, imputation_strategy (median/mean/most_frequent/constant/iterative/none), encoding_strategy (label/onehot), normalize_features, scaler — all exact matches, on master. The scaler allowlist matches precisely, QuantileTransformer is rejected, and the (tabular & time-to-event) scope comment matches the real guard (TSC's scaler routes elsewhere).
• Engine (develop): constant→0.0, categorical "Unknown" / per-column mode under most_frequent, label never imputed, median default, iterative/MICE via IterativeImputer, none/handle_missing_values=False both disable the step, the six-scaler registry with QuantileTransformer in LEAKY_SCALERS, and the <col>__missing indicator channel — all match. The privacy framing even tracks the code comments word-for-word.

⚠️ Please address before this can sit safely

1. This PR is not a GitHub Draft (isDraft: false, mergeable/clean). The "⛔ Draft until ALL of…" gate is prose only — GitHub enforces none of it, so one stray merge ships docs for behaviour that's on master for nobody. Suggest gh pr ready --undo to make it an actual draft. This is the most important change.

2. Two content pieces describe unshipped behaviour (fine only behind a real draft gate):

   • The new TSF imputation paragraph → engine#507, not even on develop. (I checked feat/505-forecasting-imputation: it does implement forecasting imputation matching the paragraph exactly — forward-fill in timestamp order, leading-gap fallback honouring imputation_strategy, timestamp/label never imputed — so this is content-accurate, purely a timing gate, not a mislabel of the TSC feature.)
   • The missingness_indicators(True) snippet → the SDK method exists only on an unmerged feature branch; on the released SDK it raises AttributeError.

3. Gate under-specifies the SDK side of TSF imputation. On master the SDK guard for handle_missing_values / imputation_strategy does not include time-series-forecasting — the TSF widening rides the same unmerged feat/472 branch. So the TSF paragraph needs the SDK guard change and engine#507. Worth adding the SDK half explicitly to gate item 2 so it isn't forgotten.

Minor (non-blocking)

• The ## Preprocessing code block stacks handle_missing_values(False) with imputation_strategy('iterative') and normalize_features(True) + scaler(...). The # Or … comments signal these are alternatives, but a whole-block copy-paste sets contradictory values — a one-liner ("illustrative alternatives, not a recommended combination") removes the footgun.
• Anchor #preprocessing-tabular--time-series is correct (double hyphen from the & collapse) and the preview built green — worth one click-test of the cross-page link in the Mintlify preview.
• Spotted while verifying, out of scope here: the SDK facade scaler docstring (link_model_dataset.py:575) still lists QuantileTransformer as supported even though the validator rejects it — worth a small follow-up.

[LukasWodka]

Thanks for the source-verified review — all four actionable points are handled:

1. Real draft ✅ — converted (gh pr ready --undo); my --draft at creation evidently didn't take. GitHub now enforces the gate.
2. Unshipped-behaviour content — stays in, now behind the real draft gate per your note that both pieces are content-accurate against the feature branches.
3. Gate item 2 updated ✅ — now names the SDK-side TSF gate widening explicitly (it rides tracebloc/tracebloc-py-package#335), so the TSF paragraph can't go live on engine#507 alone.
4. Copy-paste footgun ✅ — the code block now says "illustrative alternatives, not a recommended combination" with the concrete contradiction spelled out (pushed to this branch).

Minor items: anchor format confirmed as you derived it (double hyphen); will click-test in the Mintlify preview before undrafting. Your out-of-scope catch — the facade scaler docstring still advertising QuantileTransformer — is fixed on the open tracebloc/tracebloc-py-package#335 rather than a new ticket (one docstring, file already in that diff). Open question for you there: the TS path's SDK allowlist (shape.py _SUPPORTED_SCALERS) still accepts QT client-side and relies on the engine's #499 runtime refusal — want the client-side rejection folded into #335 too, or as its own follow-up?

[LukasWodka]

Gate progress (2026-07-23 12:30): every code dependency is now merged — engine#507 ✅, the indicator trio (engine#508 / backend#1192 / py-package#335) ✅, and the SDK TSF-gate widening rode #335 ✅. The only remaining gate is deployment: the tracebloc-engine develop→staging→master promotion (prod images) and the SDK release cut from master. Undraft once those land.