Architecture Overview

This page summarizes the high-level component and data flow for the library. See docs/improvement/component_diagram.md for the development version; this page is the user-facing snapshot.

Explain Flow

        flowchart LR
    subgraph EXT[External]
        D[Training Data]
        M[Trained Model]
    end
    subgraph CE[calibrated_explanations]
        CFG[Config & Validation]
        CAL[Calibration Orchestrator]
        STRAT_CAL[(Calibration Strategies)]
        CACHE[(Cache)]
        PAR[Parallel Executor]
        ART[Calibrated Artifacts]
        EXP[Explanation Manager]
        STRAT_EXP[(Explanation Strategies)]
        SCHEMA[Schema & Envelope]
        PLOT[PlotSpec Generator]
        RENDER[Renderers]
        PLUG[Plugin Registry]
        MET[Metrics]
        LOG[Logging]
    end
    D --> M
    M --> CFG
    D --> CFG
    CFG --> CAL --> STRAT_CAL --> ART --> EXP --> STRAT_EXP --> SCHEMA
    STRAT_CAL --> PAR
    STRAT_EXP --> PAR
    STRAT_EXP --> CACHE
    STRAT_CAL --> CACHE
    SCHEMA --> PLOT --> RENDER
    PLUG --> STRAT_CAL
    PLUG --> STRAT_EXP
    CACHE -. stats .-> MET
    PAR -. timings .-> MET
    CAL -. logs .-> LOG
    EXP -. logs .-> LOG

Layers

        flowchart TB
    UI[Public API]
    ORCH[Orchestrators]
    STRATS[Strategies]
    SERVICES[Support Services\n(Cache, Parallel, Schema, Plugins, Validation)]
    EXT[External Model & Data]
    UI --> ORCH --> STRATS --> SERVICES --> EXT

Component Roles

Component

Role

Config & Validation

Normalize inputs, enforce constraints, structured errors

Calibration Orchestrator

Run selected calibration strategy, produce calibrated sets/intervals

Explanation Manager

Produce explanation objects using calibrated artifacts

Cache

Reuse deterministic intermediates; bounded memory footprint

Parallel Executor

Strategy-agnostic concurrency selection

Schema & Envelope

Versioned JSON contract for portable explanations

PlotSpec / Renderers

Backend-agnostic visualization generation

Plugin Registry

Controlled discovery & trust gating for extensions

Metrics & Logging

Observability (latency, hit ratio, warnings)

Evolution

Initial phases keep cache disabled & serial execution by default to preserve baseline behavior. Later phases progressively enable heuristics and pluggable backends.

Validation and parameters (Phase 1B)

  • Validation is enforced at the wrapper boundary:

  • WrapCalibratedExplainer.calibrate(...) performs strict checks on inputs and the learner (no NaNs in x/y; model must implement predict, classification auto-detected via predict_proba).

  • Other wrapper entry points (predict/explain/plot) run permissive input shape checks and allow NaNs to avoid behavior drift in Phase 1B.

  • Removed-alias enforcement: legacy aliases (alpha, alphas, n_jobs) are rejected at the public boundary. Use canonical names (low_high_percentiles, parallel_workers).

  • The core CalibratedExplainer maintains legacy checks; the wrapper provides the unified validation surface for public use.