calibrated_explanations.api.config

Configuration primitives for calibrated_explanations.

This module introduces a light-weight configuration dataclass and a builder to simplify constructing explainers with validated options. no wiring to core classes is performed to avoid behavior changes; consumers may import and use these types for future-facing code.

See RELEASE_PLAN_v1 milestone targets and ADR-009 for preprocessing-related fields.

class calibrated_explanations.api.config.ExplainerConfig(model: Any, task: Literal['classification', 'regression', 'auto'] = 'auto', 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', parallel_workers: int | None = None, 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['feature', 'instance'] = 'feature', perf_telemetry: Any | None = None, perf_feature_filter_enabled: bool = False, perf_feature_filter_per_instance_top_k: int = 8)

Bases: object

Configuration for building an explainer wrapper.

Notes

• Fields included here are future-facing.

• Keep defaults aligned with existing behavior to prevent drift when adopted.

Attributes:

parallel_workers

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

task: Literal['classification', 'regression', 'auto'] = 'auto'

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'

parallel_workers: int | None = None

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['feature', 'instance'] = 'feature'

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)

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.
parallel_workers(n)	Configure the desired number of parallel worker processes.
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.
task(task)	Set the task type for the explainer configuration.
threshold(t)	Store a regression-style threshold value on the configuration.
unseen_category_policy(policy)	Select the strategy for handling unseen categorical values.

task(task: Literal['classification', 'regression', 'auto']) → ExplainerBuilder

Set the task type for the explainer configuration.

Parameters:

task ({"classification", "regression", "auto"}) – Desired task literal to store in the configuration.

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

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

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

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

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

Select the strategy for handling unseen categorical values.

Parameters:

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

parallel_workers(n: int | None) → ExplainerBuilder

Configure the desired number of parallel worker processes.

Parameters:

n (int or None) – Worker count for parallel execution; None leaves the default in place.

perf_cache(enabled: bool, *, max_items: int | None = None, max_bytes: int | None = None, namespace: str | None = None, version: str | None = None, ttl: float | None = None) → ExplainerBuilder

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.

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['feature', 'instance'] | None = None) → ExplainerBuilder

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.

perf_telemetry(callback: Any | None) → ExplainerBuilder

Register a telemetry callback shared by cache and parallel executors.

perf_feature_filter(enabled: bool, *, per_instance_top_k: int | None = None) → ExplainerBuilder

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

Return the assembled configuration (no side effects).