Internal RFC: Prediction Semantics Contract

This document defines the strict contract for how predictions must be normalized and structured within TrustLens backends. All resolve() functions must adhere to these rules.

1. Classification Semantics

Binary Classification

TrustLens metrics expect binary probabilities as a 2D array.

  • Allowed Input Shapes: (n,), (n, 1), (n, 2).

  • Normalization Rule: All binary outputs must be normalized to (n, 2) where index 1 represents the positive class.

  • Example: If a model returns a 1D array of positive probabilities, the backend must expand it to [1-p, p].

Multiclass Classification

  • Allowed Input Shape: (n, C).

  • Normalization Rule: Probabilities must sum to 1.0 per sample. No logits allowed in the PredictionBundle.

2. Regression Semantics

TrustLens does NOT currently support regression tasks.

  • Contract: Backends should raise NotImplementedError if regression output is detected.

Logits Policy

Raw logits are strictly forbidden inside the PredictionBundle.

Backends are responsible for converting logits to calibrated probabilities (e.g., via Softmax for multiclass or Sigmoid for binary tasks) before constructing the bundle. This ensures that downstream trust metrics, calibration plots, and uncertainty estimations receive standardized probability scores.

3. Label Consistency

  • Class Labels: The class_labels field in PredictionBundle should be populated whenever possible to ensure that metric reports use the correct semantic labels (e.g., “Malignant” instead of 1).

4. Metadata Hooks

Every PredictionBundle should include detection metadata for debugging:

metadata = {
    "resolver": "sklearn",
    "detection_method": "module_name", # or "explicit", "capability"
    "framework_version": "1.3.0"
}

5. Manual Overrides (model=None)

TrustLens supports auditing prediction data without a direct model reference.

  • Contract: If model=None is passed to analyze(), the manual resolver is used.

  • Requirement: Either y_pred or y_prob must be provided.

  • Derivation: If y_prob is provided but y_pred is missing, y_pred will be derived via argmax.

6. Degraded Mode Transparency

When critical components (like y_prob) are missing, TrustLens enters a Degraded Mode.

  • Audit Trail: Metadata will include "degraded_mode": True and a list of "missing_components".

  • Module Behavior: Analysis modules must skip confidence-based metrics (e.g., Calibration, ECE) and report a "skipped" status instead of crashing.