fix(ingest): catch single-label classification at preflight + surface backend reason (issue #251)

[divyasinghds]

Closes #251.

Two coupled improvements to the user experience when a classification dataset has fewer than 2 distinct label values — surfaced by adversarial testing against v0.3.10-rc1.

The cascade we hit

Submit a `tabular_classification` (or any classification-family) dataset where the `label` column has ONE distinct value across all rows (e.g. all rows labelled `"X"`):

1. Validators pass — no per-record issue, just label uniformity
2. All rows insert into MySQL successfully
3. `prepare_dataset` calls `/global_meta/prepare/`
4. Backend returns HTTP 400: `{"message":"Please provide atleast 2 labels."}`
5. Framework raises generic: "Backend failed to prepare the dataset; it was NOT registered (its rows are already in the database). See the logged API error above."

The user-visible error tells you to grep the log. The actual reason is one ERROR-line up. Rows are orphaned in MySQL by the time anything surfaces.

Fix 1 — LabelDiversityValidator at preflight

New validator: `tracebloc_ingestor/validators/label_diversity_validator.py`.

• Reads only the label column when given a CSV path (`usecols=[...]` — a multi-GB proteomics panel doesn't get materialised just to count labels).

• Counts non-null distinct values; rejects when `< min_distinct` (default 2 — matches the backend's exact contract).

• Error message names the offending distinct value(s) and value-count breakdown:

  ```
  Classification category requires at least 2 distinct label values in
  column 'label'; this dataset has 1 distinct value(s): ['X'].
  Value counts: {'X': 10}. If this is intentional (e.g. you have a
  continuous target), pick a regression-family category like
  tabular_regression or time_series_forecasting instead.
  ```

• Suggests regression-family categories so users with continuous targets get a pointer instead of being told to fake a second class.

• Gracefully no-ops on empty input / missing label column — other validators already surface those.

Wired in via `validators_mapping.py` for every classification-family category:

• `tabular_classification`, `image_classification`, `text_classification`, `object_detection`, `semantic_segmentation`, `keypoint_detection`

NOT wired for regression (`tabular_regression`, `time_series_forecasting`, `time_to_event_prediction` — continuous targets) or self-supervised (`masked_language_modeling`, `token_classification`).

Fix 2 — propagate backend body into the user-visible error

`APIClient.prepare_dataset` now stashes the formatted backend response on `self.last_prepare_error` (`HTTP : `). `base.py`'s "Backend failed to prepare" RuntimeError reads it and includes the actual backend reason verbatim.

Before:

Backend failed to prepare the dataset; it was NOT registered (its rows are already in the database). See the logged API error above.

After:

Backend failed to prepare the dataset; it was NOT registered (its rows are already in the database). Backend response: HTTP 400: {"message":"Please provide atleast 2 labels."}

A user piping the log through filtered output (CI, error tooling, paste-into-Slack) sees the cause in the visible line — no more grep.

What this PR does NOT do

• The backend typo `"atleast"` → `"at least"` lives in the backend repo, not here. Flagged in Single-label classification dataset surfaces as misleading 'Backend failed to prepare' instead of a clear preflight error #251 for whoever owns that endpoint.

Test plan

• 14 new tests in `tests/test_label_diversity_validator.py`:
  • Positive: 2+ labels, many labels, nulls don't count, case-insensitive column match
  • Failure: single label (with value-counts in message), all-null, one-value-plus-nulls
  • Error message mentions the regression alternative
  • Defensive: empty input / missing column → silent pass (other validators own those)
  • CSV-path: reads only the label column; rejects single-label CSV at the file level
  • Custom label column name
• 3 new tests in `tests/test_api_client_methods.py`:
  • On HTTP error, `last_prepare_error` populated with status + body
  • Clean ingestor: `last_prepare_error is None`
  • Network error (no response): still populated with stringified exception
• CI green
• Re-run S5/S8 from the adversarial pass:
  • Single-label data → fails fast at preflight with the value-counts message (no MySQL writes, no backend round-trip)
  • Multi-label data → continues to pass end-to-end

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes preflight gating and post-commit registration error messaging on a critical ingest path; mis-tuned label counting could block valid datasets or still allow bad ones, though extensive tests target parity with CSV ingest rules.

Overview
Adds LabelDiversityValidator so classification-family ingests fail before MySQL writes when the label column has fewer than two distinct non-null values, with errors that list offending values/counts and suggest regression categories when appropriate. It is wired through validators_mapping for tabular/image/text/object/semantic/keypoint classification (not token classification or regression/self-supervised), reads CSVs via label-only usecols with NA/dtype rules aligned to ingest via full_schema from base.py, and includes hardening for headers, read failures, and schema vs non-schema NA handling (#252).

APIClient.prepare_dataset now clears and sets last_prepare_error on HTTP/network failures; base.py includes that text in the RuntimeError when prepare fails so users see the backend body (e.g. “Please provide atleast 2 labels.”) instead of only “see the logged API error above.”

Tests cover the validator, mapping, and last_prepare_error behavior.

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

[LukasWodka]

👋 Heads-up — Code review queue is at 16 / 8

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

Open PRs currently in Code review (oldest first):

• averaging-service#106 — test(integration): pin XGBoost/LightGBM/CatBoost end-to-end averaging round-trips · author: @LukasWodka · no reviewer assigned
• averaging-service#111 — fix(averaging): correctness round-2 sweep — N5/N7/N8/N9/N10 + load_model except (Sync develop → master for v0.3.0 release #109) · author: @LukasWodka · no reviewer assigned
• client#254 — Sync develop → main for v1.7.1 chart release (egress-enforcement preflight helm test, inert) · author: @saadqbal · no reviewer assigned
• client#256 — fix(egress-proxy): probe reports DNS failure distinctly, not as a TCP connect [image_validator falsely rejects images when target_size matches exactly #104] · author: @saadqbal · no reviewer assigned
• client-runtime#105 — chore(ci): drop unused mysqlclient dep; report test coverage (Phase 0) · author: @LukasWodka · no reviewer assigned
• client-runtime#106 — fix(schema): sync vendored ingest.v1.json — restore token_classification · author: @LukasWodka · no reviewer assigned
• data-ingestors#248 — refactor(P2): extract ingestion-summary renderer into reporting.ConsoleRenderer · author: @LukasWodka · no reviewer assigned
• data-ingestors#249 — fix(database): CHAR(N) must map to a SQLAlchemy type in _get_sqlalchemy_type · author: @divyasinghds · no reviewer assigned
• data-ingestors#250 — fix(csv): empty CSV must fail fast with clear input-error message · author: @divyasinghds · no reviewer assigned
• design-system#47 — feat(table): Table compound organism (Figma 959:6061 + 986:9822) · author: @waqaskhanroghani · no reviewer assigned

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

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f271082. Configure here.}