CE Pipeline Builder

You are implementing a CE-first pipeline. Load references/ce-first-policy.md for the full policy text. Non-negotiable invariants are repeated inline below for quick reference.

Mandatory CE-First Checklist (enforce in order)

1. Library check — if calibrated_explanations is not importable, fail fast:

   python
   1pip install calibrated-explanations

2. Wrapper — always use WrapCalibratedExplainer. Never invent a new wrapper class; never use CalibratedExplainer directly in user-facing code.
3. Fit — explainer.fit(x_proper, y_proper). Assert explainer.fitted is True before proceeding.
4. Calibrate — explainer.calibrate(x_cal, y_cal). Assert explainer.calibrated is True before proceeding.
5. Explain (standard) — explainer.explain_factual(X) or explainer.explore_alternatives(X).
6. Explain (guarded / in-distribution) — when higher security or in-distribution filtering is needed, use explainer.explain_guarded_factual(X) or explainer.explore_guarded_alternatives(X) instead of the standard paths. Also use when rule conditions of the form x < feature <= y are needed, since the guarded APIs support this natively.
7. Conjunctions — explanations.add_conjunctions(...) or explanations[idx].add_conjunctions(...).
8. Narratives & plots — .to_narrative(output_format=...) and .plot(...).
9. Calibrated by default — never return uncalibrated outputs unless the user has explicitly requested them.

Minimal Working Skeleton

Adapt the task type (binary / multiclass / regression) based on the user's data and model. Choose from the three templates below:

Binary classification

python
1from __future__ import annotations
2import numpy as np
3from calibrated_explanations import WrapCalibratedExplainer
4
5# --- Data split ---------------------------------------------------------
6# x_proper, y_proper : proper training set (used for model training)
7# x_cal, y_cal       : calibration set    (must NOT overlap with x_proper)
8# X_query            : instances to explain
9
10# --- Build pipeline -----------------------------------------------------
11explainer = WrapCalibratedExplainer(model)           # model: any sklearn-compat
12explainer.fit(x_proper, y_proper)
13assert explainer.fitted is True
14
15explainer.calibrate(x_cal, y_cal)
16assert explainer.calibrated is True
17
18# --- Explain ------------------------------------------------------------
19explanations = explainer.explain_factual(X_query)
20# Optional: add feature conjunctions
21explanations.add_conjunctions(max_rule_size=3)
22# Optional: narrative
23print(explanations[0].to_narrative())
24# Optional: plot
25explanations[0].plot()

Multiclass classification

Same scaffold as binary. The explain_factual call returns one explanation object per query instance, with per-class calibrated probabilities available in explanations[i].prediction["__full_probabilities__"].

Regression (percentile intervals)

python
1explainer = WrapCalibratedExplainer(reg_model)
2explainer.fit(x_proper, y_proper)
3assert explainer.fitted is True
4
5explainer.calibrate(x_cal, y_cal)
6assert explainer.calibrated is True
7
8# low_high_percentiles controls the conformal interval width (ADR-021)
9explanations = explainer.explain_factual(X_query, low_high_percentiles=(10, 90))

Regression (thresholded / probabilistic)

python
1# threshold= activates the CPS + Venn-Abers path (ADR-021 §3)
2explanations = explainer.explain_factual(X_query, threshold=my_threshold)

Using ce_agent_utils helpers

Prefer the validated helpers from src/calibrated_explanations/ce_agent_utils.py for end-to-end pipelines in agent code:

python
1from calibrated_explanations.ce_agent_utils import (
2    ensure_ce_first_wrapper,
3    fit_and_calibrate,
4    explain_and_narrate,
5    wrap_and_explain,
6)
7
8# Full pipeline in one call:
9explanations = wrap_and_explain(
10    model, x_proper, y_proper, x_cal, y_cal, X_query
11)

Decision: explain_factual vs explain_guarded_factual

Guarded variants apply ADR-032 semantics — see references/adr-032-guarded-semantics.md.

Data Split Rules

• x_proper / y_proper and x_cal / y_cal must not overlap.
• Typical split: 60% proper training, 20% calibration, 20% test. Adjust based on calibration data needs (larger calibration → tighter intervals).
• Never reuse training data for calibration.

Out of Scope

This skill does NOT:

• Train or tune the underlying model (use your usual scikit-learn workflow).
• Generate plots or visualizations beyond .plot() invocation (see ce-plotspec-author).
• Cover the serialization / persistence of calibrators (see ce-serializer-impl).
• Add new plugins or modify core/ (see ce-plugin-scaffold).

Evaluation Checklist (self-verify before returning)

• WrapCalibratedExplainer used (not raw CalibratedExplainer).
• fit() called with proper training data.
• calibrate() called with separate calibration data.
• Both .fitted is True and .calibrated is True asserted.
• explain_factual or explore_alternatives (or guarded variants) called.
• No uncalibrated output returned unless explicitly requested.
• Skeleton is runnable with the user's model and data shapes.