calibrated_explanations.api.config¶

Configuration primitives for calibrated_explanations.

This module provides a configuration dataclass and a fluent builder for constructing explainers with validated options. See ADR-009 for preprocessing-related fields and ADR-034 §7 for env-var precedence rules.

class calibrated_explanations.api.config.ExplainerConfig(model: Any, low_high_percentiles: tuple[int, int] = (5, 95), threshold: float | None = None, preprocessor: Any | None = None, auto_encode: bool | Literal['auto'] = 'auto', unseen_category_policy: Literal['ignore', 'error'] = 'error', perf_cache_enabled: bool = False, perf_cache_max_items: int = 512, perf_cache_max_bytes: int | None = 33554432, perf_cache_namespace: str = 'calibrator', perf_cache_version: str = 'v1', perf_cache_ttl: float | None = None, perf_parallel_enabled: bool = False, perf_parallel_backend: Literal['auto', 'sequential', 'joblib', 'threads', 'processes'] = 'auto', perf_parallel_workers: int | None = None, perf_parallel_min_batch: int = 8, perf_parallel_min_instances: int | None = None, perf_parallel_tiny_workload: int | None = None, perf_parallel_granularity: Literal['instance'] = 'instance', perf_telemetry: Any | None = None, perf_feature_filter_enabled: bool = False, perf_feature_filter_per_instance_top_k: int = 8)[source]¶

Bases: object

Configuration for building an explainer wrapper.

Notes

Fields wired by from_config(): model, preprocessor, auto_encode, unseen_category_policy; performance primitives (cache, parallel executor) via the perf factory; internal feature-filter config.
Fields applied at explain-time: threshold and low_high_percentiles are forwarded to explain_factual / explore_alternatives via kwargs.setdefault().

WrapCalibratedExplainer auto-detects task from the fitted model; there is no task field. perf_parallel_workers is the governed parallel-worker count (CE_PARALLEL env var takes precedence — see ADR-034 §7).

Attributes:

perf_cache_ttl
perf_factory: Factory for performance telemetry.
perf_parallel_min_instances
perf_parallel_tiny_workload
perf_parallel_workers
perf_telemetry
preprocessor
threshold

model: Any¶

low_high_percentiles: tuple[int, int] = (5, 95)¶

threshold: float | None = None¶

preprocessor: Any | None = None¶

auto_encode: bool | Literal['auto'] = 'auto'¶

unseen_category_policy: Literal['ignore', 'error'] = 'error'¶

perf_cache_enabled: bool = False¶

perf_cache_max_items: int = 512¶

perf_cache_max_bytes: int | None = 33554432¶

perf_cache_namespace: str = 'calibrator'¶

perf_cache_version: str = 'v1'¶

perf_cache_ttl: float | None = None¶

perf_parallel_enabled: bool = False¶

perf_parallel_backend: Literal['auto', 'sequential', 'joblib', 'threads', 'processes'] = 'auto'¶

perf_parallel_workers: int | None = None¶

perf_parallel_min_batch: int = 8¶

perf_parallel_min_instances: int | None = None¶

perf_parallel_tiny_workload: int | None = None¶

perf_parallel_granularity: Literal['instance'] = 'instance'¶

perf_telemetry: Any | None = None¶

perf_feature_filter_enabled: bool = False¶

perf_feature_filter_per_instance_top_k: int = 8¶

property perf_factory¶: Factory for performance telemetry.

class calibrated_explanations.api.config.ExplainerBuilder(model: Any)[source]¶

Bases: object

Store base model reference and seed configuration defaults.

Methods

`auto_encode`(flag)	Toggle automatic categorical encoding behavior.
`build_config`()	Return the assembled configuration (no side effects).
`low_high_percentiles`(p)	Update the percentile pair for interval explanations.
`perf_cache`(enabled, *[, max_items, ...])	Enable or disable the performance cache options.
`perf_feature_filter`(enabled, *[, ...])	Configure internal FAST-based feature filtering.
`perf_parallel`(enabled, *[, backend, ...])	Configure the parallel backend used for performance operations.
`perf_telemetry`(callback)	Register a telemetry callback shared by cache and parallel executors.
`preprocessor`(pre)	Attach an optional preprocessing object to the configuration.
`threshold`(t)	Store a regression-style threshold value on the configuration.
`unseen_category_policy`(policy)	Select the strategy for handling unseen categorical values.

low_high_percentiles(p: tuple[int, int]) → ExplainerBuilder[source]¶

Update the percentile pair for interval explanations.

Parameters:: p (tuple of int) – Inclusive lower and upper percentiles used for interval computation.

threshold(t: float | None) → ExplainerBuilder[source]¶

Store a regression-style threshold value on the configuration.

Parameters:: t (float or None) – Threshold applied when producing probabilistic regression outputs.

preprocessor(pre: Any | None) → ExplainerBuilder[source]¶

Attach an optional preprocessing object to the configuration.

Parameters:: pre (Any or None) – Preprocessor applied to inputs prior to fitting or calibration.

auto_encode(flag: bool | Literal['auto']) → ExplainerBuilder[source]¶

Toggle automatic categorical encoding behavior.

Parameters:: flag (bool or "auto") – Whether to auto-encode categorical inputs when preprocessing.

unseen_category_policy(policy: Literal['ignore', 'error']) → ExplainerBuilder[source]¶

Select the strategy for handling unseen categorical values.

Parameters:: policy ({"ignore", "error"}) – Policy to apply when encountering unseen categories at inference time.

Enable or disable the performance cache options.

Parameters:

enabled (bool) – Flag indicating whether caching primitives should be provisioned.
max_items (int, optional) – Maximum number of cached entries when caching is enabled.

Notes

CE_CACHE env var takes precedence over enabled because CacheConfig.from_env() is applied after builder construction inside _build_perf_factory() (ADR-034 §7).

perf_parallel(enabled: bool, *, backend: Literal['auto', 'sequential', 'joblib', 'threads', 'processes'] | None = None, workers: int | None = None, min_batch: int | None = None, min_instances: int | None = None, tiny_workload: int | None = None, granularity: Literal['instance'] | None = None) → ExplainerBuilder[source]¶

Configure the parallel backend used for performance operations.

Parameters:

enabled (bool) – Whether parallel primitives should be created.
backend ({"auto", "sequential", "joblib"}, optional) – Explicit backend selection overriding the default when provided.

Notes

CE_PARALLEL env var takes precedence over enabled because ParallelConfig.from_env() is applied after builder construction inside _build_perf_factory() (ADR-034 §7).

perf_telemetry(callback: Any | None) → ExplainerBuilder[source]¶: Register a telemetry callback shared by cache and parallel executors.

perf_feature_filter(enabled: bool, *, per_instance_top_k: int | None = None) → ExplainerBuilder[source]¶

Configure internal FAST-based feature filtering.

Parameters:

enabled (bool) – Flag indicating whether the internal FAST-based feature filter is enabled.
per_instance_top_k (int, optional) – Maximum number of features to keep per instance based on FAST weights.

build_config() → ExplainerConfig[source]¶: Return the assembled configuration (no side effects).