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_guarded_kwargs(kwargs: dict[str, Any]) → None

Reject guarded kwargs removed in v0.11.5 with actionable migration guidance.

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

Reject reject-policy kwargs removed in v0.11.5 with migration guidance.

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.reject_removed_normalization_kwarg(kwargs: dict[str, Any]) → None

Reject the legacy normalize= bool passthrough removed in v0.11.5.

normalize= looked like a synonym of the live normalization= parameter but was actually a removed alias: any presence raises, regardless of value. Previously this was only caught deep inside VennAbers.predict_proba via ValidationError, well past the public wrapper boundary; catching it here gives a ConfigurationError consistent with every other removed alias (ADR-038 5B).

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

Reject unsupported to_narrative kwargs that were previously ignored.

The CE-first docs mistakenly taught format=... while the runtime only supported output_format=... plus expertise_level=.... Prior to v0.11.6 Task 12, format was silently forwarded and ignored, yielding the default dataframe output instead of the requested narrative style.

calibrated_explanations.api.params.reject_unknown_public_kwargs(kwargs: dict[str, Any], *, allowed: frozenset[str] | set[str], surface: str) → None

Reject unrecognized public keyword arguments (ADR-038 D3: fail-fast).

Replaces the pre-v0.11.6 behavior of warning and silently forwarding unknown public kwargs; see development/current-work/v0.11.6_plan.md (D3 resolution) for the CHANGELOG-documented reversal from v0.11.4 Task 15.

calibrated_explanations.api.params.reject_cross_surface_kwargs(kwargs: dict[str, Any], *, allowed: frozenset[str] | set[str], closed_surface_names: frozenset[str] | set[str], surface: str) → None

Reject kwargs known on another closed surface but not valid here (ADR-038 5C).

For experimental plugin-forwarding surfaces (ADR-038 §3 exception), a name genuinely unknown anywhere is treated as plugin-defined and passed through silently. Only names that are recognized on a closed surface (e.g. CalibratedExplainer.__init__/predict/predict_proba) but not valid on this experimental surface are rejected – this preserves the plugin extensibility the §3 exception grants while still closing the cross-method silent-no-op class of bug (ADR-038 5B/5C).

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.