xailens 0.1.2__py3-none-any.whl

xai_compare/__init__.py

@@ -0,0 +1,6 @@
+from xai_compare.registry.autodiscover import autodiscover_adapters
+from xai_compare.context import RunContext, RunData, DataSchema, ResponseSchema
+from xai_compare.runner import run
+
+# Register on package import
+autodiscover_adapters()

xai_compare/_version.py

@@ -0,0 +1,2 @@
+# ./_version.py
+__version__ = "0.1.2"

xai_compare/adapters/comparison/coefficient_treeshap_adapter.py

@@ -0,0 +1,56 @@
+import plotly.graph_objects as go
+
+from xai_compare.context import ComparisonContext
+from xai_compare.registry.comparison_registry import register_comparison
+from xai_compare.adapters.comparison.comparison_base import ComparisonAdapter
+from xai_compare.dashboard.components.formatting import format_model_name
+from xai_compare import config, context
+
+
+@register_comparison("coefficients", "shap_tree")
+class CoefficientTreeShapComparison(ComparisonAdapter):
+    """For comparing coefficients with shap tree"""
+
+
+    def _viz_diff_bar(self, features_a, features_b, run_a, run_b, axis_range=None):
+        raise NotImplementedError
+
+    def _viz_dumbbell(self, features_a, features_b, run_a, run_b, axis_range=None):
+        raise NotImplementedError
+
+    def _viz_alignment_scale(self, ctx: ComparisonContext ):
+        diff = ctx.features_a.sub(ctx.features_b, fill_value=0)
+        diff = diff.sort_values()
+
+        colors = [config.PLOT_LEFT_COLOR if v < 0 else config.PLOT_RIGHT_COLOR for v in diff]
+
+        fig = go.Figure(go.Bar(
+            x=diff.values,
+            y=diff.index,
+            orientation='h',
+            marker_color=colors,
+        ))
+
+        label_a = format_model_name(ctx.run_a)
+        label_b = format_model_name(ctx.run_b)
+
+        fig.update_layout(
+            title=f"Explanation Difference: {label_a} − {label_b}",
+            xaxis_title=f"Attribution difference ({label_a} − {label_b})",
+            xaxis=config.PLOT_ZERO_LINE,
+            yaxis_title="Feature",
+            height=400 + len(diff) * 15,
+        )
+        if ctx.axis_range:
+            fig.update_layout(xaxis={"range": ctx.axis_range})
+        return fig
+
+    visualisations_available = {
+        "Difference (bar)": _viz_diff_bar,
+        "Dumbbell": _viz_dumbbell,
+        "Alignment Scale": _viz_alignment_scale
+    }
+
+    def render_comparison(self, ctx: context.ComparisonContext, viz_type):
+
+        return self.visualisations_available[viz_type](self, ctx)

xai_compare/adapters/comparison/comparison_base.py

@@ -0,0 +1,28 @@
+import pandas as pd
+from abc import ABC, abstractmethod
+from typing import Any
+
+from xai_compare.context import ComparisonContext
+from xai_compare.services.preprocess import normalise_values
+
+
+class ComparisonAdapter(ABC):
+    """Handles comparison between two XAI explanations."""
+
+    compatible_pairs: set[frozenset[str]]
+    visualisations_available = []
+
+    @classmethod
+    def get_abs_max(cls, explanation_a: pd.Series, explanation_b: pd.Series, sample_id_column) -> float:
+        """ calculate absolute max value from explanation
+        required for ensuring charts use the same scales """
+        features_a = normalise_values(explanation_a, sample_id_column)
+        features_b = normalise_values(explanation_b, sample_id_column)
+        a = pd.to_numeric(features_a, errors='coerce')
+        b = pd.to_numeric(features_b, errors='coerce')
+        diff = a.sub(b, fill_value=0)
+        return diff.abs().max()
+
+    @abstractmethod
+    def render_comparison(self, ctx: ComparisonContext, viz_type) -> Any:
+        raise NotImplementedError

xai_compare/adapters/explainers/__init__.py

@@ -0,0 +1 @@
+

xai_compare/adapters/explainers/coefficients_adapter.py

@@ -0,0 +1,49 @@
+
+import pandas as pd
+from typing import Any
+
+from xai_compare.context import RunData
+from xai_compare.exceptions import MissingDataError
+from xai_compare.registry.xai_registry import register_xai
+from xai_compare.adapters.explainers.xaimethod_base import XAIMethodAdapter
+from xai_compare.run import Run
+from xai_compare import constants, strings, config
+from xai_compare.context import RunContext
+
+
+@register_xai("coefficients")
+class CoefficientsAdapter(XAIMethodAdapter):
+    """For models with native interpretability"""
+
+    display_name = strings.COEFFICIENTS_DISPLAY_NAME
+    default_visualisation = config.COEFFICIENTS_DEFAULT_VIZ
+    compatible_visualisations = config.COEFFICIENTS_COMPATIBLE_VIZ
+
+    @classmethod
+    def load_explanation(cls, run: Run, sample_id: str):
+        df = run.store.load_dataframe(f"explanations_{cls.key}")
+        row = df[df[run.get(constants.DATA_SCHEMA_ID_COLUMN)] == sample_id]
+        if row.empty:
+            raise MissingDataError(f"Sample '{sample_id}' not found in explanations for {cls.key}")
+        return row.iloc[0]
+
+    def explain_local_df(self, ctx: RunContext, model=None) -> pd.DataFrame:
+        """Computes the local explanation from the coefficients of the model
+        Args:
+            ctx: RunContext object
+            model: Trained model object
+
+        Returns:
+            pd.DataFrame: dataframe containing local explanations
+
+        Raises:
+            MissingDataError: if data.x is not provided
+        """
+        if ctx.data.x is None:
+            raise MissingDataError("CoefficientsAdapter requires x in RunData")
+        coef = model.coef_[0]
+        local_explanations = ctx.data.x * coef
+        return local_explanations
+
+    def explain_local_json(self, ctx: RunContext) -> dict[str, Any]:
+        raise NotImplementedError

xai_compare/adapters/explainers/cor_adapter.py

@@ -0,0 +1,107 @@
+import json
+
+import pandas as pd
+from typing import Any
+from dataclasses import dataclass
+
+from xai_compare.context import RunContext, ResponseSchema
+from xai_compare.exceptions import MissingDataError
+from xai_compare.registry.xai_registry import register_xai
+from xai_compare.adapters.explainers.xaimethod_base import XAIMethodAdapter
+from xai_compare import strings, config
+
+
+@dataclass
+class ContribScore:
+    score: int
+    reasoning: str
+
+@dataclass
+class LLMResponse:
+    reasoning: str
+    prediction: int | str
+    confidence: float
+    contributions: dict[str, ContribScore]
+    raw: dict
+
+    def to_dict(self, sample_id_col: str, sample_id: str) -> dict:
+        return {
+            sample_id_col: sample_id,
+            "reasoning": self.reasoning,
+            "prediction": self.prediction,
+            "confidence": self.confidence,
+            "contributions": {
+                feature: {"score": c.score, "reasoning": c.reasoning}
+                for feature, c in self.contributions.items()
+            }
+        }
+
+@register_xai("cor")
+class CoRAdapter(XAIMethodAdapter):
+    """For chain-of-reasoning/chain-of-thought explanations"""
+
+    display_name = strings.COR_DISPLAY_NAME
+    default_visualisation = config.COR_DEFAULT_VIZ
+    compatible_visualisations = config.COR_COMPATIBLE_VIZ
+
+    # no features as such so will process the explanations in this adapter
+    requires_encoded_features: bool = False
+
+    # uses a json file for explanation storage
+    explanation_file_type: str = "json"
+
+    def explain_local_df(self, ctx: RunContext, model=None) -> pd.DataFrame:
+        raise NotImplementedError
+
+    def explain_local_json(self, ctx: RunContext) -> list[dict[str, Any]]:
+        """Processes the CoR local explanations
+        Args:
+            ctx: RunContext object
+
+        Returns:
+            list[dict[str, Any]]: list of dicts containing local explanations
+
+        Raises:
+            MissingDataError: if data.x is not provided
+        """
+        if ctx.data.y_exp is None:
+            raise MissingDataError("CoRAdapter requires y_exp in RunData")
+        if ctx.response_schema is None:
+            raise MissingDataError(
+                "CoRAdapter requires a ResponseSchema on RunContext")
+
+        sample_id_col = ctx.data.data_schema.sample_id_column
+        output = []
+        for idx, row in ctx.data.y_exp.iterrows():
+            raw = json.loads(row["explanation"])
+            response = self._normalise(raw, ctx.response_schema)
+            output.append(response.to_dict(sample_id_col, row[sample_id_col]))
+        return output
+
+    def _normalise(self, raw: dict, schema: ResponseSchema) -> LLMResponse:
+        raw_contribs = raw[schema.contributions_field]
+
+        if schema.contribution_key is not None:
+            contributions = {
+                item[schema.contribution_key]: ContribScore(
+                    score=item["score"],
+                    reasoning=item["reasoning"],
+                )
+                for item in raw_contribs
+            }
+        else:
+            contributions = {
+                feature: ContribScore(
+                    score=values["score"],
+                    reasoning=values["reasoning"],
+                )
+                for feature, values in raw_contribs.items()
+            }
+
+        return LLMResponse(
+            reasoning=raw["reasoning"],
+            prediction=raw["prediction"],
+            confidence=raw["confidence"],
+            contributions=contributions,
+            raw=raw,
+        )

xai_compare/adapters/explainers/kernelshap_adapter.py

@@ -0,0 +1,37 @@
+import shap
+import pandas as pd
+from typing import Any
+
+from xai_compare.exceptions import MissingDataError
+from xai_compare.context import RunContext
+from xai_compare.registry.xai_registry import register_xai
+from xai_compare.adapters.explainers.xaimethod_base import XAIMethodAdapter
+from xai_compare import config, strings
+
+@register_xai("shap_kernel")
+class KernalSHAPAdapter(XAIMethodAdapter):
+    """Model-agnostic Kernel Shap Explainer"""
+
+    display_name = strings.KERNEL_SHAP_DISPLAY_NAME
+    default_visualisation = config.KERNEL_SHAP_DEFAULT_VIZ
+    compatible_visualisations = config.KERNEL_SHAP_COMPATIBLE_VIZ
+
+    def explain_local_df(self, ctx: RunContext, model=None) -> pd.DataFrame:
+        """Computes the local explanation using KernelShap method
+        Args:
+            ctx: RunContext object
+            model: Trained model object
+
+        Returns:
+            pd.DataFrame: dataframe containing local explanations
+
+        Raises:
+            MissingDataError: if x_train or x_test is not provided
+        """
+        if ctx.data.x_train is None or ctx.data.x_test is None:
+            raise MissingDataError("KernalSHAPAdapter requires x_train and x_test in RunData")
+        explainer = shap.KernelExplainer(model.predict_proba, ctx.data.x_train)
+        return explainer.shap_values(ctx.data.x_test)
+
+    def explain_local_json(self, data: RunContext) -> dict[str, Any]:
+        raise NotImplementedError

xai_compare/adapters/explainers/treeshap_adapter.py

@@ -0,0 +1,77 @@
+import shap
+import pandas as pd
+from typing import Any
+
+from xai_compare.exceptions import MissingDataError
+from xai_compare.context import RunContext
+from xai_compare.registry.xai_registry import register_xai
+from xai_compare.adapters.explainers.xaimethod_base import XAIMethodAdapter
+from xai_compare.run import Run
+from xai_compare import constants, strings, config
+
+@register_xai("shap_tree")
+class TreeSHAPAdapter(XAIMethodAdapter):
+    """Tree Shap Explainer"""
+
+    display_name = strings.TREE_SHAP_DISPLAY_NAME
+    default_visualisation = config.TREE_SHAP_DEFAULT_VIZ
+    compatible_visualisations = config.TREE_SHAP_COMPATIBLE_VIZ
+
+    @classmethod
+    def load_explanation(cls, run: Run, sample_id: str):
+        df = run.store.load_dataframe(f"explanations_{cls.key}")
+        row = df[df[run.get(constants.DATA_SCHEMA_ID_COLUMN)] == sample_id]
+        if row.empty:
+            raise ValueError(f"Sample '{sample_id}' not found in explanations for {cls.key}")
+        return row.iloc[0]
+
+
+    def explain_local_df(self, ctx: RunContext, model=None) -> pd.DataFrame:
+        """Computes the local explanation from the coefficients of the model
+        Args:
+            ctx: RunContext object
+            model: Trained model object
+
+        Returns:
+            pd.DataFrame: dataframe containing local explanations
+
+        Raises:
+            MissingDataError: if data.x_test is not provided
+        """
+        if not hasattr(ctx.data, "x_test") or ctx.data.x_test is None:
+            raise MissingDataError("CoefficientsAdapter requires x_test in RunData")
+
+        data = ctx.data.x_test
+        if ctx.data.data_schema.sample_id_column in data.columns:
+            data = data.set_index(ctx.data.data_schema.sample_id_column)
+        data = data.select_dtypes(include=['number'])
+
+        explainer = shap.TreeExplainer(model)
+        shap_values = explainer.shap_values(data)
+
+        # (n_samples, 1, n_features)
+        if shap_values.ndim == 2:
+            dfs = [pd.DataFrame(shap_values, index=data.index, columns=ctx.data.x_test.columns)]
+            dfs[0]['class'] = 0
+            return dfs[0].set_index('class', append=True)
+
+        # SHAP returns (n_samples, n_features, n_classes) for multiclass tree models
+        # slice last axis per class to get (n_samples, n_features) per DataFrame
+        if shap_values.ndim == 3:
+            n_classes = shap_values.shape[2]
+            dfs = []
+
+            for i in range(n_classes):
+                # Slice the last axis [:, :, i] to get (n_samples, n_features)
+                df = pd.DataFrame(
+                    shap_values[:, :, i],
+                    index=data.index,
+                    columns=data.columns
+                )
+                dfs.append(df)
+
+            keys = ctx.data.data_schema.class_names if ctx.data.data_schema.class_names is not None else range(n_classes)
+            return pd.concat(dfs, keys=keys, names=['class', data.index.name])
+
+    def explain_local_json(self, ctx: RunContext) -> dict[str, Any]:
+        raise NotImplementedError

xai_compare/adapters/explainers/xaimethod_base.py

@@ -0,0 +1,64 @@
+import pandas as pd
+from abc import ABC, abstractmethod
+from typing import Any
+
+from xai_compare.context import RunContext, RunData
+from xai_compare.services.preprocess import normalise_values
+
+
+class XAIMethodAdapter(ABC):
+    """
+    Abstract class for XAI method adapter.
+    """
+    display_name: str | None = None
+    default_visualisation: str | None = None
+    compatible_visualisations: list[str] = []
+
+    # default to true for most explanation adapters
+    requires_encoded_features: bool = True
+
+    # type of explanation storage - df or json
+    explanation_file_type: str = "df"
+
+    @classmethod
+    def load_explanation(cls, store, sample_id: str):
+        raise NotImplementedError
+
+    @classmethod
+    def get_abs_max(cls, explanation: pd.Series, sample_id_column) -> float:
+        """ calculate absolute max value from explanation
+        required for ensuring charts use the same scales """
+        features = normalise_values(explanation, sample_id_column)
+        return pd.to_numeric(features, errors='coerce').abs().max()
+
+    @abstractmethod
+    def explain_local_df(self, ctx: RunContext, model=None) -> pd.DataFrame:
+        """Computes the local explanation for the model
+        Args:
+            ctx: RunContext object
+            model: Trained model object
+
+        Returns:
+            pd.DataFrame: dataframe containing local explanations
+
+        Raises:
+            MissingDataError: if required data is not provided
+        """
+        pass
+
+    @abstractmethod
+    def explain_local_json(self, ctx: RunContext) -> list[dict[str, Any]]:
+        """Computes the local explanation for the model
+        Args:
+            ctx: RunContext object
+
+        Returns:
+            list of dicts - json containing local explanations
+
+        Raises:
+            MissingDataError: if required data is not provided
+        """
+        pass
+
+
+

xai_compare/adapters/models/llm_adapter.py

@@ -0,0 +1,11 @@
+from xai_compare.registry.model_registry import register_model
+from xai_compare.adapters.models.model_base import ModelAdapter
+from xai_compare import strings
+
+@register_model("llm")
+class LLMAdapter(ModelAdapter):
+
+    display_name = strings.LLM_DISPLAY_NAME
+
+    def prepare(self):
+        pass

xai_compare/adapters/models/logisticregression_adapter.py

@@ -0,0 +1,8 @@
+from xai_compare.registry.model_registry import register_model
+from xai_compare.adapters.models.model_base import ModelAdapter
+from xai_compare import strings
+
+@register_model("logistic_regression")
+class LogisticRegressionAdapter(ModelAdapter):
+
+    display_name = strings.LOGISTIC_REGRESSION_DISPLAY_NAME

xai_compare/adapters/models/model_base.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+
+
+class ModelAdapter(ABC):
+
+    display_name: str | None = None
+
+    def __init__(self, model=None):
+        self.model = model
+
+    def prepare(self):
+        return self.model
+
+
+

xai_compare/adapters/models/xgboost_adapter.py

@@ -0,0 +1,8 @@
+from xai_compare.registry.model_registry import register_model
+from xai_compare.adapters.models.model_base import ModelAdapter
+from xai_compare import strings
+
+@register_model("xgboost")
+class XGBoostAdapter(ModelAdapter):
+
+    display_name = strings.XGBOOST_DISPLAY_NAME

xai_compare/adapters/viz/forceplot_viz_adapter.py

@@ -0,0 +1,40 @@
+import plotly.graph_objects as go
+
+from xai_compare.adapters.viz.viz_base import VizAdapter
+from xai_compare.registry.viz_registry import register_viz
+from xai_compare import strings, config
+from xai_compare.services.preprocess import normalise_values
+
+
+@register_viz("forceplot")
+class ForcePlotVizAdapter(VizAdapter):
+
+    display_name = strings.FORCE_PLOT_DISPLAY_NAME
+    compatible_explanations = config.FORCE_PLOT_COMPATIBLE_XAI
+
+    def render_local(self, explanation, sample_id_col, axis_range=None):
+        features = normalise_values(explanation, sample_id_col)
+
+        colors = [config.PLOT_LEFT_COLOR if v < 0 else config.PLOT_RIGHT_COLOR for v in features.values]
+
+        fig = go.Figure(go.Bar(
+            orientation="h",
+            y=features.index.tolist(),
+            x=features.values.tolist(),
+            marker_color=colors,
+        ))
+
+        fig.update_layout(
+            title=strings.FORCE_PLOT_TITLE,
+            xaxis_title=strings.FORCE_PLOT_X_AXIS,
+            xaxis=config.PLOT_ZERO_LINE,
+            showlegend=False,
+        )
+        if axis_range:
+            fig.update_layout(xaxis={"range":axis_range})
+            
+        return fig
+
+    def render_global(self, explanations):
+        # Placeholder function
+        return

xai_compare/adapters/viz/viz_base.py

@@ -0,0 +1,15 @@
+from typing import Any
+from abc import ABC, abstractmethod
+
+class VizAdapter(ABC):
+
+    display_name: str | None = None
+    compatible_explanations: list[str] = []
+
+    @abstractmethod
+    def render_local(self, explanation, sample_id_col, axis_range=None) -> Any:
+        raise NotImplementedError
+
+    @abstractmethod
+    def render_global(self, explanations) -> Any:
+        raise NotImplementedError

xai_compare/adapters/viz/waterfall_viz_adapter.py

@@ -0,0 +1,38 @@
+import plotly.graph_objects as go
+from xai_compare.adapters.viz.viz_base import VizAdapter
+from xai_compare.registry.viz_registry import register_viz
+from xai_compare import strings, config
+
+@register_viz("waterfall")
+class WaterfallVizAdapter(VizAdapter):
+
+    display_name = strings.WATERFALL_DISPLAY_NAME
+    compatible_explanations = config.WATERFALL_COMPATIBLE_XAI
+
+    def render_local(self, explanation, sample_id_col, axis_range=None)  -> go.Figure:
+        features = explanation.drop([sample_id_col, "class"], errors="ignore")
+
+        # Sort by absolute value descending
+        features = features.reindex(features.abs().sort_values(ascending=True).index)
+
+        # Normalise by sum of absolute values
+        features = features / features.abs().sum()
+
+        fig = go.Figure(go.Waterfall(
+            orientation="h",
+            measure=["relative"] * len(features),
+            y=features.index.tolist(),
+            x=features.values.tolist(),
+            connector={"line": {"color": "rgb(63, 63, 63)"}},
+        ))
+        fig.update_layout(
+            title=strings.WATERFALL_TITLE,
+            xaxis_title=strings.WATERFALL_X_AXIS,
+        )
+        if axis_range:
+            fig.update_layout(xaxis={"range": axis_range})
+        return fig
+
+    def render_global(self, explanations):
+        # Placeholder function
+        return

xai_compare/artifacts.py

@@ -0,0 +1,70 @@
+import os
+import pandas as pd
+import numpy as np
+import uuid
+
+from datetime import datetime
+from dataclasses import asdict
+
+from xai_compare import RunContext
+from xai_compare import config
+from xai_compare.storage.store_base import DataStore
+from xai_compare.storage.filesystem_store import FilesystemStore
+
+
+class ArtifactStore:
+    """ArtifactStore - handles the data storage
+
+     Args:
+        ctx (RunContext): The current run configuration.
+        store (DataStore): Storage backend. Defaults to FilesystemStore.
+    """
+
+    def __init__(self, ctx: RunContext, store: DataStore = None):
+        self.ctx = ctx
+        self.run_datetime = datetime.now().strftime("%Y%m%d-%H%M%S")
+        dirname = self._resolve_dirname(ctx)
+        self.store = store or FilesystemStore(dirname)
+
+
+    def _resolve_dirname(self, ctx):
+        BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+        if ctx.run_name:
+            return os.path.join(BASE_DIR, config.RUNS_DIR_NAME, ctx.run_name)
+        return os.path.join(BASE_DIR, config.RUNS_DIR_NAME, self.run_datetime)
+
+
+    def write_metadata(self):
+        """Writes the artifact metadata directly from the context dataclass
+        """
+        excluded = {'data', 'model'}
+        obj = {k: v for k, v in asdict(self.ctx).items() if k not in excluded}
+        obj['datetime'] = self.run_datetime
+        obj['run_uuid'] = str(uuid.uuid4())
+
+        # Add the dataschema info
+        obj['data_schema'] = asdict(self.ctx.data.data_schema)
+
+        self.store.save_json(config.META_INFO_FILENAME, obj)
+
+    def write_model(self):
+        if self.ctx.model:
+            self.store.save_model(config.MODEL_FILENAME ,self.ctx.model)
+
+    def write_data(self, name, data):
+        if data is None:
+            return
+        if isinstance(data, pd.Series):
+            data = data.to_frame()
+        elif isinstance(data, np.ndarray):
+            data = pd.DataFrame(data)
+        elif isinstance(data, list):
+            data = pd.DataFrame(data)
+        self.store.save_dataframe(name, data)
+
+    def write_explanation(self, name, data, type="df"):
+        self.store.save_explanation(name, data, type)
+
+    def load_dataframe(self, name:str) -> pd.DataFrame:
+        return self.store.load_dataframe(name)
+

xai_compare/cli.py

@@ -0,0 +1,10 @@
+import os
+import subprocess
+
+def main():
+    base_dir = os.path.dirname(os.path.abspath(__file__))
+    app_path = os.path.join(base_dir, "dashboard", "app.py")
+    subprocess.run(["streamlit", "run", app_path])
+
+if __name__ == "__main__":
+    main()