v0.11.6 Upgrade Checklist

Who should read this

  • Downstream callers that pass shared **kwargs dicts into CE public APIs.

  • Notebook and app integrations that relied on warn-and-ignore behavior from v0.11.4 or on legacy reject-policy aliases.

  • Teams preparing for the v1.0.0 release-candidate API freeze and wanting to clear inert parameter usage now.

What changed

v0.11.6 closes several silent-no-op or warn-and-ignore seams and turns them into fail-fast validation errors. The goal is to make invalid CE calls visible before the release-candidate freeze, not to open a new deprecation cycle.

Upgrade actions

1. Replace unknown or method-mismatched public kwargs

calibrate(), explain_factual(), explore_alternatives(), explain_fast(), predict(), and predict_proba() now raise ConfigurationError for unknown public kwargs.

If you were passing a shared kwargs dict across multiple CE methods, split it by method instead of relying on unused keys being ignored.

2. Migrate the six newly rejected inert names

The following names were previously accepted on public surfaces but had no effect. They now fail fast instead of disappearing silently:

  • condition

  • condition_label

  • condition_labels

  • include_reject_details

  • output_interval

  • y_threshold

Remove them from public CE calls unless you are updating internal/plugin code that uses a documented supported replacement on a different surface.

3. Replace removed guarded kwargs with GuardedOptions

These removed v0.11.5 kwargs now raise ConfigurationError on every public entry path:

  • guarded

  • significance

  • n_neighbors

  • normalize_guard

  • merge_adjacent

Use guarded_options=GuardedOptions(...) instead.

from calibrated_explanations.explanations.guarded_options import GuardedOptions

explanations = explainer.explain_factual(
    X_query,
    guarded_options=GuardedOptions(confidence=0.9),
)

4. Replace the removed reject-policy aliases

Reject-policy NCF inputs are now limited to default and ensured.

  • ncf="entropy" now raises ValidationError; use ncf="default".

  • Explicit ncf="hinge" and ncf="margin" now raise ValidationError; use ncf="default" for the task-dependent built-in scorer.

  • Removed confidence= reject aliases now raise; use reject_confidence=....

5. Stop passing boolean normalize=

Legacy boolean normalize=True/False passthrough no longer resolves silently in VennAbers.predict_proba(...). Invalid values now raise ValidationError.

Pass the explicit normalization strategy instead:

from calibrated_explanations.calibration.normalization_strategy import (
    NormalizationStrategy,
)

proba = venn_abers.predict_proba(
    X,
    normalization=NormalizationStrategy.COHERENCE,
)

6. Update narrative aliases

Removed legacy aliases now fail fast:

  • The legacy format= keyword on to_narrative(...) is not supported; use output_format=....

  • narrative_format= in ce_agent_utils helpers now raises ConfigurationError; use expertise_level=....

Quick verification for downstream integrators

  1. Search your integration code for the removed names listed above.

  2. Re-run your CE explain/predict smoke tests and confirm no ConfigurationError or ValidationError is raised from legacy kwargs.

  3. If you maintain notebooks, re-execute them and remove any stale examples that still show removed aliases.