calibrated_explanations.api.params

Parameter canonicalization utilities (ADR-002).

This module centralizes lightweight argument normalization and consistency checks, enabling downstream validators and plugins to rely on a stable parameter contract.

Notes

• Alias mapping enables backward compatibility without behavior drift.

• Combination validation enforces ADR-compliant constraints (e.g., conflicting parameter exclusivity).

• Canonicalization only maps known aliases to canonical keys when the canonical key is not already provided.

See ADR-002 for context.

calibrated_explanations.api.params.canonicalize_kwargs(kwargs: dict[str, Any]) → dict[str, Any]

Return a copy of kwargs with known aliases mapped to canonical keys.

Notes

• If an alias exists in kwargs and the canonical key is absent, copy the value to the canonical key.

• If both alias and canonical are present, keep the canonical value and do not overwrite it.

• Always preserve original keys; we do not delete aliases to avoid any chance of behavior drift. Callers should read canonical keys first.

• Unknown keys are left untouched.

calibrated_explanations.api.params.reject_removed_aliases(kwargs: dict[str, Any]) → None

Reject aliases removed in v0.11.0 with actionable migration guidance.

calibrated_explanations.api.params.validate_param_combination(kwargs: dict[str, Any]) → None

Perform basic consistency checks for parameter combinations (ADR-002).

Enforces mutual exclusivity and conflict constraints. Raises ConfigurationError when violations are detected.

Parameters:

kwargs (dict) – Keyword arguments to validate.

Raises:

ConfigurationError – When conflicting parameter combinations are detected.

calibrated_explanations.api.params.warn_on_aliases(kwargs: dict[str, Any]) → None

Compatibility wrapper for the removed alias guard.

Notes

• warn_on_aliases historically emitted deprecation warnings.

• Since aliases were removed in v0.11.0, this now fails fast.