# 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.

```python
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:

```python
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.

## Related references

- [CHANGELOG.md](https://github.com/Moffran/calibrated_explanations/blob/main/CHANGELOG.md)
- [docs/migration/deprecations.md](../migration/deprecations.md)
- [docs/get-started/ce_first_agent_guide.md](../get-started/ce_first_agent_guide.md)