# v1.0.0 upgrade checklist

Use this checklist when migrating from any v0.11.x release to v1.0.0.
Work through each topic in order; most items are verifiable with a one-line
command.

The authoritative env var reference is
[`docs/foundations/how-to/configure_runtime.md`](../foundations/how-to/configure_runtime.md).
The safe-defaults guide for production deployments is
[`docs/foundations/how-to/safe-defaults.md`](../foundations/how-to/safe-defaults.md).

---

## 1. Environment variables

> **Full reference:** [configure_runtime.md](../foundations/how-to/configure_runtime.md)
> covers all env vars, their pyproject.toml equivalents, accepted values, and
> the `export_effective()` diagnostic pattern. This section summarises the
> points most often misconfigured during upgrades.

All 25 recognised env vars are listed below. Keys not set default to their
pyproject.toml value or the library default.

| Key | Category | Notes |
|-----|----------|-------|
| `CE_EXPLANATION_PLUGIN` | Plugin selection | Alias for `CE_EXPLANATION_PLUGIN_FACTUAL` |
| `CE_EXPLANATION_PLUGIN_FACTUAL` | Plugin selection | Identifier of the factual explanation plugin |
| `CE_EXPLANATION_PLUGIN_ALTERNATIVE` | Plugin selection | Identifier of the alternative explanation plugin |
| `CE_EXPLANATION_PLUGIN_FAST` | Plugin selection | Identifier of the fast explanation plugin |
| `CE_EXPLANATION_PLUGIN_FACTUAL_FALLBACKS` | Plugin selection | Comma-separated fallback identifiers |
| `CE_EXPLANATION_PLUGIN_ALTERNATIVE_FALLBACKS` | Plugin selection | Comma-separated fallback identifiers |
| `CE_EXPLANATION_PLUGIN_FAST_FALLBACKS` | Plugin selection | Comma-separated fallback identifiers |
| `CE_INTERVAL_PLUGIN` | Plugin selection | Identifier of the interval plugin |
| `CE_INTERVAL_PLUGIN_FAST` | Plugin selection | Identifier of the fast interval plugin |
| `CE_INTERVAL_PLUGIN_FALLBACKS` | Plugin selection | Comma-separated fallback identifiers |
| `CE_INTERVAL_PLUGIN_FAST_FALLBACKS` | Plugin selection | Comma-separated fallback identifiers |
| `CE_PLOT_STYLE` | Plot | Plot style identifier |
| `CE_PLOT_STYLE_FALLBACKS` | Plot | Comma-separated fallback style identifiers |
| `CE_PLOT_RENDERER` | Plot | Plot renderer identifier |
| `CE_TRUST_PLUGIN` | Security | Comma-separated trusted plugin identifiers (allowlist) |
| `CE_DENY_PLUGIN` | Security | Comma-separated denied plugin identifiers (denylist) |
| `CE_PLUGIN_CONFIG_JSON` | Plugin | JSON string of per-plugin configuration |
| `CE_TELEMETRY_DIAGNOSTIC_MODE` | Observability | `true`/`false`; enables verbose telemetry |
| `CE_CACHE` | Performance | `off` (default) or `on[,max_items=N,max_bytes=N,ttl=N]` — see §6 Caching below |
| `CE_PARALLEL` | Performance | `off` (default) or `on[,workers=N,min_batch=N,threads]` — see §7 Parallel execution below |
| `CE_PARALLEL_MIN_BATCH_SIZE` | Performance | Standalone override for parallel minimum batch size |
| `CE_FEATURE_FILTER` | Runtime | Feature-filter expression; env-only key |
| `CE_STRICT_OBSERVABILITY` | Observability | `true`/`false`; converts observability soft errors to hard errors |
| `CE_DEBUG_TRUST_INVARIANTS` | Debug | Direct `os.getenv` read — NOT routed through ConfigManager; **never set in production** |
| `CI` | Environment | Detected by CI-aware heuristics; do not set explicitly |
| `GITHUB_ACTIONS` | Environment | Detected by CI-aware heuristics; do not set explicitly |

**Confirm no phantom keys:** Cache and parallel sizing is provided inline
within the `CE_CACHE` and `CE_PARALLEL` values — there are no standalone
sizing keys for cache item count, byte limit, TTL, or parallel worker count.
Use the inline token syntax shown in topics 6 and 7 below.

To print the effective configuration of a running process:

```python
from calibrated_explanations.core.config_manager import get_process_config_manager
snapshot = get_process_config_manager().export_effective()
# Resolved values live under "effective.<KEY>"; snapshot also contains
# "env.*", "pyproject.*", and "diagnostic.*" groups.
for key, value in snapshot.values.items():
    print(f"{key}: {value!r}  [{snapshot.sources[key]}]")
```

---

## 2. pyproject.toml configuration

> **Full reference:** [configure_runtime.md](../foundations/how-to/configure_runtime.md)
> documents every `[tool.calibrated_explanations.*]` section and field.

Minimum recommended `pyproject.toml` additions for v1.0.0:

```toml
[tool.calibrated_explanations.plugins]
trusted = ["your-plugin-id"]  # empty list = no plugins trusted

[tool.calibrated_explanations.explanations]
# factual = "my_factual_plugin"    # override default factual plugin
# alternative = "my_alt_plugin"   # override default alternative plugin
```

ConfigManager reads pyproject.toml at process start. Changes require a process
restart to take effect.

---

## 3. API changes from v0.11.x

The following symbols were removed in v0.11.x and are no longer present in the
codebase. Replace all usages before upgrading.

### Removed in v0.11.0

| Removed symbol | Canonical replacement |
|---|---|
| `get_explanation(index)` on `CalibratedExplanations` | `explanations[index]` |
| `explain_counterfactual(...)` on `WrapCalibratedExplainer` | `explore_alternatives(...)` |
| `calibrated_explanations.core` legacy module warning path | Use the package façade |
| `register_plot_plugin(...)` | `register_plot_builder(...)` + `register_plot_renderer(...)` |
| Parameter aliases `alpha`, `alphas` | `low_high_percentiles` |
| Parameter alias `n_jobs` | `parallel_workers` |
| Top-level package exports (`AlternativeExplanation`, `FactualExplanation`, `FastExplanation`, `AlternativeExplanations`, `CalibratedExplanations`, `BinaryEntropyDiscretizer`, `BinaryRegressorDiscretizer`, `EntropyDiscretizer`, `RegressorDiscretizer`, `IntervalRegressor`, `VennAbers`) | Import from respective submodules |
| `calibrated_explanations.perf` root facade | `calibrated_explanations.cache` + `calibrated_explanations.parallel` |

### Removed in v0.11.2

| Removed symbol | Canonical replacement |
|---|---|
| `CalibratedExplainer.preload_lime(...)` | `LimePipeline(explainer).preload(...)` |
| `CalibratedExplainer.preload_shap(...)` | `ShapPipeline(explainer).preload(...)` |
| `CalibratedExplainer.explain_lime(...)` | `LimePipeline(explainer).explain(...)` |
| `CalibratedExplainer.explain_shap(...)` | `ShapPipeline(explainer).explain(...)` |
| `CalibratedExplainer.is_lime_enabled(...)` | `LimePipeline(explainer).is_enabled()` |
| `CalibratedExplainer.is_shap_enabled(...)` | `ShapPipeline(explainer).is_enabled()` |
| `WrapCalibratedExplainer.explain_lime(...)` | `LimePipeline(wrapper).explain(...)` |
| `WrapCalibratedExplainer.explain_shap(...)` | `ShapPipeline(wrapper).explain(...)` |

### Removed in v0.11.3

| Removed symbol | Canonical replacement |
|---|---|
| `calibrated_explanations.perf.cache` | `calibrated_explanations.cache` |
| `calibrated_explanations.perf.parallel` | `calibrated_explanations.parallel` |
| `assign_threshold`, `initialize_interval_learner`, `initialize_interval_learner_for_fast_explainer`, `update_interval_learner` from `core.calibration_helpers` | `calibrated_explanations.calibration.interval_learner` |
| Plugin `modes` value `"explanation:factual"` | `"factual"` |
| Plugin `modes` value `"explanation:alternative"` | `"alternative"` |
| Plugin `modes` value `"explanation:fast"` | `"fast"` |
| `ParallelConfig(granularity="feature")` | `granularity="instance"` |
| `RejectPolicy.PREDICT_AND_FLAG`, `RejectPolicy.EXPLAIN_ALL` | `RejectPolicy.FLAG` |
| `RejectPolicy.EXPLAIN_REJECTS` | `RejectPolicy.ONLY_REJECTED` |
| `RejectPolicy.EXPLAIN_NON_REJECTS`, `RejectPolicy.SKIP_ON_REJECT` | `RejectPolicy.ONLY_ACCEPTED` |
| `calibrated_explanations.core.calibration` (package) | `calibrated_explanations.calibration` |
| `CalibratedExplainer.initialize_reject_learner(...)` | `explainer.reject_orchestrator.initialize_reject_learner(...)` |
| `CalibratedExplainer.predict_reject(...)` | `explainer.reject_orchestrator.predict_reject(...)` |
| `WrapCalibratedExplainer.initialize_reject_learner(...)` | `wrapper.explainer.reject_orchestrator.initialize_reject_learner(...)` |
| `WrapCalibratedExplainer.predict_reject(...)` | `wrapper.explainer.reject_orchestrator.predict_reject(...)` |
| `CalibratedExplainer.build_plot_style_chain(...)` | `explainer.plugin_manager.build_plot_chain(...)` |
| `CalibratedExplainer.instantiate_plugin(...)` | `explainer.plugin_manager.explanation_orchestrator.instantiate_plugin(...)` |
| `CalibratedExplainer.invoke_explanation_plugin(...)` | `explainer.explanation_orchestrator.invoke(...)` |
| `CalibratedExplainer.ensure_interval_runtime_state(...)` | `explainer.prediction_orchestrator.ensure_interval_runtime_state(...)` |
| `CalibratedExplainer.gather_interval_hints(...)` | `explainer.prediction_orchestrator.gather_interval_hints(...)` |
| `CalibratedExplainer.interval_plugin_hints`, `.interval_plugin_fallbacks`, `.interval_preferred_identifier`, `.telemetry_interval_sources`, `.interval_plugin_identifiers`, `.interval_context_metadata` | `explainer.plugin_manager.<same name>` |
| `CalibratedExplainer.explanation_plugin_overrides`, `.interval_plugin_override`, `.fast_interval_plugin_override`, `.plot_style_override` | `explainer.plugin_manager.<same name>` |
| `CalibratedExplanations.as_lime(...)` | `LimePipeline(...).explain(...)` |
| `CalibratedExplanations.as_shap(...)` | `ShapPipeline(...).explain(...)` |
| `plugins.registry.register(plugin)` | `register_explanation_plugin(identifier, plugin, metadata)` |
| `plugins.registry.trust_plugin(plugin)` | `register_explanation_plugin(..., metadata={"trusted": True, ...})` |
| `plugins.registry.find_for(model)` | `find_explanation_plugin_for(..., trusted_only=False)` |
| `plugins.registry.find_for_trusted(model)` | `find_explanation_plugin_for(..., trusted_only=True)` |

### Removed in v0.11.3 (guarded wrapper methods)

| Removed symbol | Canonical replacement |
|---|---|
| `CalibratedExplainer.explain_guarded_factual(...)` | `explainer.explain_factual(..., guarded_options=GuardedOptions())` |
| `CalibratedExplainer.explore_guarded_alternatives(...)` | `explainer.explore_alternatives(..., guarded_options=GuardedOptions())` |
| `WrapCalibratedExplainer.explain_guarded_factual(...)` | `wrapper.explain_factual(..., guarded_options=GuardedOptions())` |
| `WrapCalibratedExplainer.explore_guarded_alternatives(...)` | `wrapper.explore_alternatives(..., guarded_options=GuardedOptions())` |

### Removed in v0.11.3 (plugin metadata enforcement)

Entry-point plugins that omit the `data_modalities` key in their metadata are now
**skipped** with a `UserWarning` rather than defaulting to `('tabular',)`.

| Action required | Detail |
|---|---|
| Declare `data_modalities` in every entry-point plugin's `plugin_meta` | Add `"data_modalities": ("tabular",)` (or `"vision"`, etc.) to your `plugin_meta` dict. Plugins missing this key are silently excluded from discovery as of v0.11.3. |

Import: `from calibrated_explanations.explanations.guarded_options import GuardedOptions`

The `guarded=True` boolean kwarg is **also deprecated** (emits `DeprecationWarning`; removed v1.0.0).
Set `CE_DEPRECATIONS=error` in CI to surface any remaining uses as hard errors:

```bash
CE_DEPRECATIONS=error pytest your_tests/
```

---

## 4. Guarded explanation migration

The `explain_guarded_factual` / `explore_guarded_alternatives` methods were
**removed in v0.11.3** (not merely deprecated).  The `guarded=True` boolean
kwarg is **deprecated as of v0.11.3** and will be removed in v1.0.0.

**Before (v0.11.2 and earlier):**

```python
# Removed in v0.11.3 — raises AttributeError
result = wrapper.explain_guarded_factual(X_test)
result = wrapper.explore_guarded_alternatives(X_test)
```

**Intermediate (v0.11.3 — deprecated, still works):**

```python
# Deprecated — emits DeprecationWarning; removed in v1.0.0
result = wrapper.explain_factual(X_test, guarded=True)
result = wrapper.explore_alternatives(X_test, guarded=True)
```

**Canonical (v0.11.3+ and v1.0.0-compatible):**

```python
from calibrated_explanations.explanations.guarded_options import GuardedOptions
result = wrapper.explain_factual(X_test, guarded_options=GuardedOptions())
result = wrapper.explore_alternatives(X_test, guarded_options=GuardedOptions())
```

`GuardedOptions` fields (all optional): `confidence=0.9`, `n_neighbors=None`,
`normalize=False`, `merge_adjacent=False`.

---

## 5. ExplainerBuilder and ExplainerConfig wiring

`ExplainerBuilder` and `ExplainerConfig` are exported from the root namespace
as of v0.11.3.

**Direct config construction:**

```python
from calibrated_explanations import ExplainerConfig, WrapCalibratedExplainer

config = ExplainerConfig(model=model, auto_encode=True)
wrapper = WrapCalibratedExplainer.from_config(config)
```

`model` is a required field on `ExplainerConfig`. `from_config` takes only the
config object — the model is already inside it.

**Fluent builder:**

```python
from calibrated_explanations import ExplainerBuilder, WrapCalibratedExplainer

config = (
    ExplainerBuilder(model)
    .perf_cache(True, max_items=512, max_bytes=16_777_216, ttl=600)
    .perf_parallel(True, workers=4, min_batch=16)
    .build_config()
)
wrapper = WrapCalibratedExplainer.from_config(config)
```

Key points:
- `perf_cache` and `perf_parallel` require `enabled: bool` as the first
  positional argument.
- `build_config()` returns the assembled `ExplainerConfig`; pass it to
  `WrapCalibratedExplainer.from_config()` to get the wrapper.
- `CE_CACHE` and `CE_PARALLEL` env vars take precedence over builder settings
  at runtime (applied after builder construction — ADR-034 §7).

---

(6-caching)=
## 6. Caching

> **Full reference:** [tune_runtime_performance.md](../foundations/how-to/tune_runtime_performance.md)

Caching is **opt-in** and **disabled by default** (ADR-003). To enable:

```bash
# Minimal — enable with defaults
CE_CACHE=on

# With inline sizing tokens (single env var value)
CE_CACHE=on,max_items=512,max_bytes=16777216,ttl=600
```

Accepted inline tokens: `max_items=N`, `max_bytes=N`, `ttl=N`,
`namespace=<str>`, `version=<str>`.

Enabled label values: `1`, `true`, `on`, `yes`, `enable`.

All sizing is done inline within the `CE_CACHE` value (no standalone sizing
keys exist), or programmatically via `ExplainerBuilder.perf_cache(...)`.

---

(7-parallel)=
## 7. Parallel execution

> **Full reference:** [tune_runtime_performance.md](../foundations/how-to/tune_runtime_performance.md)

Parallel execution is **opt-in** and **disabled by default** (ADR-004). To enable:

```bash
# Minimal — enable with defaults
CE_PARALLEL=on

# With inline tokens (single env var value)
CE_PARALLEL=on,workers=4,min_batch=16,threads
```

Accepted inline tokens: `workers=N`, `min_batch=N`, `min_instances=N`,
`tiny=N`, `instance_chunk=N`, `feature_chunk=N`, `task_bytes=N`,
`force_serial=`, `granularity=`.

`CE_PARALLEL_MIN_BATCH_SIZE` is a supported standalone key for the minimum
batch size only. There is no standalone key for worker count — set it
inline: `CE_PARALLEL=on,workers=4`.

The `granularity="feature"` value was removed in v0.11.3. Only
`granularity="instance"` is accepted.

---

## 8. Plugin testing and diagnostics

Verify plugin trust and configuration using the `get_process_config_manager`
singleton (not a fresh `ConfigManager.from_sources()` snapshot):

```python
from calibrated_explanations.core.config_manager import get_process_config_manager

snapshot = get_process_config_manager().export_effective()

# Resolved effective values use the "effective.<KEY>" namespace
print("trusted:", snapshot.values.get("effective.CE_TRUST_PLUGIN"))
print("denied:", snapshot.values.get("effective.CE_DENY_PLUGIN"))

# Plugin config is already a decoded dict in the snapshot (not a JSON string)
print("plugin config:", snapshot.values.get("effective.CE_PLUGIN_CONFIG_JSON"))

# Iterate all effective keys (also includes env.*, pyproject.*, diagnostic.* groups)
for key, value in snapshot.values.items():
    print(f"{key}: {value!r}  [{snapshot.sources[key]}]")
```

CLI equivalent (one-shot snapshot, does not inspect a running process):

```bash
python -m calibrated_explanations.cli config show
```

Production recommendation: set an explicit `[tool.calibrated_explanations.plugins]
trusted = [...]` in `pyproject.toml` rather than relying on `CE_TRUST_PLUGIN`
env var. Env var overrides pyproject.toml if both are set.

---

## 9. Reject framework

The reject framework was stabilised in v0.11.x. The canonical enum members are:

- `RejectPolicy.FLAG` — flag all, explain all
- `RejectPolicy.ONLY_ACCEPTED` — explain only accepted instances
- `RejectPolicy.ONLY_REJECTED` — explain only rejected instances
- `RejectPolicy.NONE` — disable reject logic entirely

The legacy aliases `PREDICT_AND_FLAG`, `EXPLAIN_ALL`, `EXPLAIN_REJECTS`,
`EXPLAIN_NON_REJECTS`, `EXPLAIN_REJECTS`, and `SKIP_ON_REJECT` were removed
in v0.11.3 and raise `ValueError` / `AttributeError` at runtime.

Use `RejectPolicySpec` for a type-safe factory:

```python
from calibrated_explanations import WrapCalibratedExplainer, RejectPolicySpec

result = wrapper.explore_alternatives(X_test, reject_policy=RejectPolicySpec.flag())
result = wrapper.explain_factual(X_test, reject_policy=RejectPolicySpec.only_accepted())
```

The `filter_by_target_confidence(confidence)` method on
`AlternativeExplanations` provides post-hoc conformal decision-making: it
returns only the alternative intervals that survive the conformal threshold at
the given confidence level.

```python
from calibrated_explanations import WrapCalibratedExplainer

result = wrapper.explore_alternatives(X_test)
high_confidence = result.filter_by_target_confidence(0.9)
```