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. The safe-defaults guide for production deployments is docs/foundations/how-to/safe-defaults.md.

1. Environment variables¶

Full reference: 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:

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 documents every [tool.calibrated_explanations.*] section and field.

Minimum recommended pyproject.toml additions for v1.0.0:

[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:

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):

# 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):

# 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):

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:

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:

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¶

Full reference: tune_runtime_performance.md

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

# 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 execution¶

Full reference: tune_runtime_performance.md

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

# 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):

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):

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:

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.

from calibrated_explanations import WrapCalibratedExplainer

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