MLZOO-D: frontend, registry, and explainability polish (PRP-31)

[w7-mgfcode]

Surfaces the v0.2.16 advanced-model metadata (LightGBM / XGBoost / regression / prophet_like) in the React dashboard and registry surface.

Scope (per PRPs/PRP-31-mlzoo-d-frontend-registry-explainability.md)

• Two new forecasting endpoints (read-only, additive, no Alembic migration):
  • GET /forecasting/runs/{run_id}/feature-metadata — keyed by registry UUID
  • GET /forecasting/jobs/{job_id}/feature-metadata — keyed by train-job ID (forecast.tsx only has the job ID; the train job's `result.run_id` is the artifact key, NOT a registry UUID — see memory `scenario-run-id-vs-registry-run-id`)
• One computed `model_family` field on `RunResponse` — `baseline` / `tree` / `additive`, derived from `model_type` at serialization time. No DB column, no migration, no backfill.
• One `FeatureImportancePanel` React component (one panel, `kind` discriminator for tree vs linear_coef).
• In-place edits to 5 pages — runs explorer (`Family` badge column + family filter), run detail, run compare, forecast.tsx, backtest.tsx (allow-list-only extension).
• New `UnprocessableEntityError` exception class in `app/core/exceptions.py` (code `UNPROCESSABLE_ENTITY`, distinct from `ValidationError`'s `VALIDATION_ERROR` — closes the `HTTPException(422)` anti-pattern from v0.2.16 PR feat(release): ship the MLZOO advanced ML model zoo (A–C2) to main (#252) #253).

Out of scope

• No SHAP / LIME / permutation importance — only native `feature_importances_` and `coef_` from the fitted estimator.
• No new agent-tool surface, no widening of `agent_require_approval`.
• No DB migration.

PRP

`PRPs/PRP-31-mlzoo-d-frontend-registry-explainability.md` (v3, 24 tasks, conf 9.5/10 — `prp-quality-agent` verdict: READY).

[w7-mgfcode]

PRP-31 Task 21 — Browser dogfood verdict (scenarios 1-7)

Dogfood session 2026-05-20, post-merge of PR #257 on dev @ c81c92c. Native Python Playwright (playwright==1.60.0) + snap chromium (/snap/bin/chromium) per memory [[playwright-dogfood-snap-chromium]]. Driver script: .ci-logs/dogfood_prp31.py. Screenshots captured locally in .ci-logs/screenshots-prp31/ (gitignored — this comment is the durable record).

Setup

# Postgres up, dev branch clean, ML extras installed (lightgbm 4.6.0, xgboost 3.2.0)
FORECAST_ENABLE_LIGHTGBM=true FORECAST_ENABLE_XGBOOST=true uv run uvicorn ...
cd frontend && ./node_modules/.bin/vite --host 0.0.0.0     # pnpm depsStatusCheck bypass

# Trained one of each: naive, lightgbm (×2), xgboost, regression, prophet_like
# All 6 registry runs in success state with artifact_uri set
# 5 completed train jobs (one per family) for the job-keyed forecast.tsx path

Verdict table

#	Scenario	URL / interaction	Network assertion	Visual assertion	Verdict
S1	Runs explorer filtered by model_type=lightgbm	/explorer/runs?model_type=lightgbm	—	Family column with the Tree badge renders on every lightgbm row	✅ PASS
S2	Run detail (lightgbm)	/explorer/runs/1212b466…	GET /forecasting/runs/{id}/feature-metadata → 200 returns 14 features	Feature Metadata card lists all 14 canonical columns (lag_1, lag_7, lag_14, lag_28, dow_sin/cos, month_sin/cos, is_weekend, is_month_end, is_holiday, price_factor, promo_active, days_since_launch). Feature Importance panel renders 14 horizontal bars sorted by magnitude with the tree SPLIT sub-label.	✅ PASS
S3	Run detail (naive baseline)	/explorer/runs/21714671…	(panel disabled — no fetch)	Baseline badge in profile header; existing Forecast Explanation card renders rule-based attribution. Neither the Feature Metadata card nor the Feature Importance panel is mounted.	✅ PASS
S4	Run compare (two lightgbm)	/explorer/runs/compare?a=1212b466…&b=1ef263f4…	feature-metadata fired for both Run A and Run B	Two Tree Family badges; Feature Importance (Run A vs Run B) card renders side-by-side coefficient/importance panels.	✅ PASS
S5	Run compare (lightgbm vs naive) — cross-family	/explorer/runs/compare?a=1212b466…&b=21714671…	0 /feature-metadata requests fired (verified via page.on('request'))	One Tree badge, one Baseline badge; cross-family card renders the muted message: "Cross-family comparisons are not rendered because magnitudes are not comparable between tree and additive models. Feature-importance comparison is only meaningful when both runs share a non-baseline model family."	✅ PASS
S6	Forecast viz (lightgbm train job) — collapsible	/visualize/forecast + paste 9ac040eb… + Load + Run forecast + expand "Model details"	1 GET /forecasting/jobs/{job_id}/feature-metadata call ✅. 0 run-keyed /forecasting/runs/.../feature-metadata calls ✅ — confirms the load-bearing memory hook [[scenario-run-id-vs-registry-run-id]] is honoured.	Model details collapsible with Tree badge; Feature Importance panel renders all 14 bars from the job-keyed endpoint.	✅ PASS
S6b	Forecast viz (naive train job)	/visualize/forecast + paste d9cd47f9… + Load + expand "Model details"	GET /forecasting/jobs/{job_id}/feature-metadata → 400	Collapsible header shows Baseline badge; panel renders the neutral message: "Feature importance is available for tree and additive model families only."	✅ PASS
S7	Backtest viz model dropdown lists Prophet-like	/visualize/backtest → open Model <Select>	—	Model dropdown enumerates all 7 options in order: Naive, Seasonal Naive, Moving Average, Regression (HistGBR), LightGBM, XGBoost, Prophet-like (additive) — matches MODEL_OPTIONS in frontend/src/pages/visualize/backtest.tsx:55-63.	✅ PASS

Summary: 8/8 scenarios green (S1–S7 incl. S6b). No deferrals, no skips — both ML extras (ml-lightgbm, ml-xgboost) were installed in this environment, so every family path was exercised.

Endpoint-shape evidence (curl, independent of the browser)

GET /forecasting/runs/1212b466…/feature-metadata  → 200  features=14   model_family=tree
GET /forecasting/runs/b033a1d1…/feature-metadata  → 200  features=14   model_family=tree     (xgboost)
GET /forecasting/runs/9681d00b…/feature-metadata  → 422  detail="Feature importance is not available for HistGradientBoostingRegressor…"  (PRP-31 honest-422 contract honoured for the regression family)
GET /forecasting/runs/6ebbab40…/feature-metadata  → 200  features=14   model_family=additive (prophet_like)
GET /forecasting/runs/21714671…/feature-metadata  → 400  detail="Feature metadata is available for tree and additive families only…"  (baseline)

Reproducer

# Prereqs: docker compose up -d, uv sync --extra dev --extra ml-lightgbm --extra ml-xgboost
#          backend on :8123 with FORECAST_ENABLE_LIGHTGBM=true FORECAST_ENABLE_XGBOOST=true
#          frontend on :5173, ≥ 1 success registry run per family + ≥ 1 completed train job per family
uv pip install playwright
uv run python .ci-logs/dogfood_prp31.py
# Screenshots → .ci-logs/screenshots-prp31/

Closes the browser dogfood deferred row in the PRP-31 system review's divergence analysis.

[w7-mgfcode]

Verified shipped in v0.2.17. Fix commits: c29d002 (PRP), e9c8ff8 (feature-metadata endpoints + UnprocessableEntityError), cbe9244 (UI family badge + importance panel + page wiring), 227b378 (docs). All acceptance criteria met: both /forecasting/{runs,jobs}/{id}/feature-metadata endpoints, model_family computed field on RunResponse, FeatureImportancePanel component, in-place edits to runs/run-detail/run-compare/forecast pages (panel pages — backtest.tsx received the allow-list-only extension), UnprocessableEntityError in app/core/exceptions.py. Dogfood S1-S7 (incl. S6b) all PASS per HANDOFF 2026-05-20-prp31-followup-and-v0.2.17-release.