ce-modality-extension

name	ce-modality-extension
description	Extend CE to non-tabular data modalities (vision, audio, timeseries, text) via ADR-033 plugin contracts, modality naming rules, and extension safety guardrails.

CE Modality Extension

You are implementing or evaluating a modality extension plugin per ADR-033. Modality extensions keep the CE core dependency-light while enabling non-tabular inputs via separately packaged plugins.

---

Core principle (ADR-033 + ADR-001)

Modality-specific runtime code MUST NOT be added directly to calibrated_explanations core. A thin shim module (calibrated_explanations.vision, calibrated_explanations.audio) is allowed; it must raise MissingExtensionError if the extension package is absent.

---

Canonical modality taxonomy

Canonical name	Aliases (registry-normalised)
"tabular"	— (default)
"image"	"vision"
"audio"	—
"text"	—
"timeseries"	"time_series"
"multimodal"	"multi-modal"
"x-<vendor>-<name>"	Custom extension namespace

---

plugin_meta for a modality extension

plugin_meta = {
    "schema_version": 1,
    "name": "mypkg.vision.explanation",
    "version": "0.1.0",
    "provider": "author/org",
    "capabilities": ["explanation:factual"],
    "trusted": False,
    # ADR-033 required for non-tabular:
    "data_modalities": ("image",),     # normalised canonical name(s)
    "plugin_api_version": "1.0",       # "MAJOR.MINOR" — must match CE contract
}

Compatibility policy (ADR-033 §1.4)

CE plugin_api_version	Extension plugin_api_version	Registry result
"1.0"	"1.0"	✅ accepted
"1.0"	"1.1"	⚠️ UserWarning + governance log; accepted
"1.0"	"2.0"	❌ ValidationError — major mismatch
"1.0"	not present	⚠️ treated as "1.0" (backward-compat default)

---

Shim module pattern

CE ships thin shims for first-party modality namespaces:

# src/calibrated_explanations/vision.py
"""Thin shim for image/vision modality extensions (ADR-033)."""
from __future__ import annotations

try:
    from ce_vision import _register_vision_plugin  # first-party extension package
except ImportError:
    def __getattr__(name: str):  # noqa: ANN001
        from calibrated_explanations.utils.exceptions import MissingExtensionError
        raise MissingExtensionError(
            f"calibrated_explanations.vision.{name} requires the 'ce-vision' package. "
            "Install it with: pip install ce-vision"
        )

---

Monorepo multi-package structure (ADR-033 §7)

Preferred layout for first-party modality packages:

calibrated-explanations/        ← core package (this repo)
ce-vision/                      ← separate package, independent versioning
  pyproject.toml                   version = "0.1.0"
  src/ce_vision/
    plugins.py                     VisionExplanationPlugin
    preprocessing.py               image → tabular feature extraction
    tests/
      test_packaging_smoke.py      entry-point discovery + import smoke test

Entry-point declaration:

# ce-vision/pyproject.toml
[project.entry-points."calibrated_explanations.plugins"]
ce_vision = "ce_vision.plugins:VisionExplanationPlugin"

---

CI smoke test (ADR-033 §8)

A lightweight "dummy" modality plugin must be present in tests/ to validate the contract in CI:

# tests/unit/plugins/test_modality_contract.py
import pytest
from calibrated_explanations.plugins.base import validate_plugin_meta


DUMMY_VISION_META = {
    "schema_version": 1,
    "name": "test.vision.dummy",
    "version": "0.1.0",
    "provider": "test-author",
    "capabilities": ["explanation:factual"],
    "trusted": False,
    "data_modalities": ("image",),
    "plugin_api_version": "1.0",
}

def test_should_pass_meta_validation_when_vision_plugin_meta_is_valid():
    validate_plugin_meta(DUMMY_VISION_META)  # no exception


def test_should_raise_on_major_version_mismatch_when_plugin_api_version_incompatible():
    from calibrated_explanations.plugins.registry import _check_plugin_api_compat
    import pytest
    with pytest.raises(Exception, match="major"):
        _check_plugin_api_compat(required="1.0", provided="2.0")

---

Release timeline (ADR-033)

Release	What ships
v0.11.0	Metadata contract validation + modality taxonomy enforcement + resolver tie-break
v0.11.1	CLI --modality, shim modules (vision/audio), packaging smoke-test gate
v0.12.0	First-party modality package promotions (after v0.11.0 contract stabilises)

---

Out of Scope

• Adding modality preprocessing code to core/ — it belongs in the extension package.
• Modality-specific plot renderers in core/ — use a PlotPlugin variant.
• Cross-modality explanation fusion — deferred to a future ADR.

Evaluation Checklist

• plugin_meta includes data_modalities (canonical or x-<vendor>-<name>).
• plugin_api_version present; major-version compatibility verified.
• No modality-specific code added to calibrated_explanations.core.
• Shim module present if using a CE namespace (vision, audio).
• Shim raises MissingExtensionError (not ImportError) when extension absent.
• CI smoke test validates entry-point discovery and import behaviour.
• Extension packaged independently with its own version.