# Error handling and validation

This package raises a small set of library-specific exceptions to make failures predictable and easy to handle. They are conservative in Phase 1B (no behavior changes to successful paths) and surfaced early during input checking.

## Key exceptions

- `calibrated_explanations.core.exceptions.ValidationError`: Inputs or configuration failed validation.
- `calibrated_explanations.core.exceptions.DataShapeError`: Shapes or dtypes are incompatible (e.g., X/y length mismatch, non-2D X).
- `calibrated_explanations.core.exceptions.ConfigurationError`: Conflicting or invalid parameter combinations.
- `calibrated_explanations.core.exceptions.ModelNotSupportedError`: Model lacks required methods.
- `calibrated_explanations.core.exceptions.NotFittedError`: Operation requires a fitted explainer or estimator.
- `calibrated_explanations.core.exceptions.ConvergenceError`: Optimization or calibration failed to converge.
- `calibrated_explanations.core.exceptions.SerializationError`: Failure to (de)serialize artifacts.

## Validation helpers

- `calibrated_explanations.core.validation.validate_inputs_matrix(X, y, ...)`: Ensures 2D X, matching y, and finiteness.
- `calibrated_explanations.core.validation.validate_model(model)`: Checks for a `predict` method and defers finer checks to call sites.
- `calibrated_explanations.core.validation.validate_fit_state(obj)`: Ensures the object is in a fitted state where required.
- `calibrated_explanations.core.validation.infer_task(...)`: Heuristic task inference based on model/y.

## Parameter canonicalization

- `calibrated_explanations.api.params.reject_removed_aliases(kwargs)`: Raises `ConfigurationError` when removed aliases (`alpha`, `alphas`, `n_jobs`) are used.
- `calibrated_explanations.api.params.canonicalize_kwargs(kwargs)`: Returns a normalized copy of kwargs without alias remapping.
- `calibrated_explanations.api.params.validate_param_combination(kwargs)`: Reserved for future stricter checks; a no-op in Phase 1B.

## Usage tips

- Callers should prefer canonical keys when reading kwargs.
- Catch `ValidationError` (or specific subclasses) at integration boundaries to provide user-friendly messages.
- For libraries that consume this package, prefer catching these exceptions over generic `Exception` to avoid masking other issues.