### Install RAITAP with multiple extras

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/installing/manual.md

Install RAITAP with multiple assessment extras and a specific hardware backend. This example includes 'onnx-cpu', 'transparency', and 'metrics'. Choose 'uv' or 'pip'.

```bash
uv add "raitap[onnx-cpu,transparency,metrics]"
```

```bash
pip install "raitap[onnx-cpu,transparency,metrics]"
```

--------------------------------

### Running RAITAP with Preprocessing Enabled

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/data/preprocessing.md

Command-line examples for running RAITAP with preprocessing enabled, using either uv or pip for installation. The '-yp' flag is required to execute preprocessing scripts.

```shell
uv run raitap --config-name assessment -yp
```

```shell
raitap --config-name assessment -yp
```

--------------------------------

### Install Custom Dependencies with uv

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/setup.md

Use this command to install specific dependency groups and extra packages for your development setup. Ensure you run this command only once to avoid overriding previous installations.

```shell
uv sync --group dev --extra onnx-cpu --extra transparency
```

--------------------------------

### Install RAITAP using uv

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/get-it-running.md

Use 'uv add' to install the RAITAP package. This is the recommended installation method.

```bash
uv add raitap
```

--------------------------------

### Install Dependencies with UV

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/installing/automatic.md

Use this command to have RAITAP automatically install dependencies using uv.

```bash
uv run raitap --config-dir my-configs --config-name assessment
```

--------------------------------

### Install Plugin and RAITAP

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/writing-a-plugin.md

Install your plugin alongside RAITAP using either `uv` or `pip`. This step is necessary for performing a self-test.

```bash
uv add raitap raitap-superxai
```

```bash
pip install raitap raitap-superxai
```

--------------------------------

### Preview Documentation Locally

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/setup.md

Starts a local server to preview the documentation. The server supports hot-reloading, so changes are reflected automatically.

```shell
uv run docs-preview
```

--------------------------------

### Install RAITAP and a plugin using uv

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/using-plugins.md

Install RAITAP and the 'raitap-superxai' plugin together using the 'uv' package manager. This is the recommended way to add third-party adapters.

```bash
uv add raitap raitap-superxai
```

--------------------------------

### Example MyBackend Implementation

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/adding/adding-a-backend.md

Demonstrates subclassing ModelBackend, registering capabilities, and implementing core methods for a PyTorch-based backend. Use this as a template for new backends.

```python
from pathlib import Path
from typing import Any

import torch
from torch import nn

from raitap import backends
from raitap.models.backend import ModelBackend
from raitap.types import Capability, ResolvedHardware


@backends.register(
    provides={Capability.AUTOGRAD},
    extensions={'.pth', '.pt'},
    extra="mybackend",
    supported_hardware={ResolvedHardware.cpu, ResolvedHardware.cuda},  # ships cpu + cuda wheels
)
class MyBackend(ModelBackend):
    def __init__(self, model: nn.Module) -> None:
        self.model = model

    @classmethod
    def from_path(
        cls, path: Path, *, model_cfg: Any, hardware: str, allow_unsafe_pickle: bool = False
    ) -> ModelBackend:  # load a model file into this backend
        ...

    def __call__(self, inputs: torch.Tensor) -> Any:  # run inference, return raw output
        return self.model(inputs)

    @property
    def hardware_label(self) -> str:  # free-form display label for the run summary
        return get_hardware_label_for_mybackend(self.device)

    def autograd_module(self) -> nn.Module:  # only if AUTOGRAD-capable
        return self.model

```

--------------------------------

### Python Configuration for ShapExplainer

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/transparency/frameworks-and-libraries.md

Demonstrates the equivalent configuration for ShapExplainer in Python, mirroring the YAML example. It shows both minimal and full setup options for visualizers.

```python
from raitap.transparency import shap, shap_image

transparency = {
    "my_shap_explainer": shap(
        algorithm="GradientExplainer",
        constructor={"local_smoothing": 0.0},
        call={"target": 0},
        raitap={
            "baseline": {"source": "imagenet_samples", "n_samples": 50},
            "batch_size": 1,
        },
        visualisers=[
            # Minimal configuration.
            shap_image(max_samples=1),
            # Full configuration — builder takes flat constructor kwargs
            # directly; ``call=`` carries render-time options.
            shap_image(
                max_samples=2,
                title="Tumour attribution",
                include_original_image=True,
                show_colorbar=True,
                cmap="coolwarm",
                overlay_alpha=0.65,
                call={"show_sample_names": True},
            ),
        ],
    ),
}
```

--------------------------------

### Install RAITAP and a plugin using pip

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/using-plugins.md

Install RAITAP and the 'raitap-superxai' plugin together using 'pip'. This method is an alternative to using 'uv'.

```bash
pip install raitap raitap-superxai
```

--------------------------------

### Install RAITAP using pip

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/get-it-running.md

Use 'pip install' to install the RAITAP package. This is an alternative installation method.

```bash
pip install raitap
```

--------------------------------

### Install RAITAP with Launcher Extra

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/job-launcher.md

Install the 'launcher' extra for RAITAP to enable job launcher support. This is required for using features like Submitit.

```bash
uv add "raitap[launcher]"
```

```bash
pip install "raitap[launcher]"
```

--------------------------------

### Python Configuration Example

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/configuration/general.md

This Python code initializes Raitap's AppConfig with multiclass classification metrics and a PGD robustness assessor.

```python
from raitap import AppConfig
from raitap.metrics import multiclass_classification
from raitap.robustness import image_pair, torchattacks

config = AppConfig(
    metrics=multiclass_classification(num_classes=1000),
    robustness={
        "pgd": torchattacks(
            algorithm="PGD",
            constructor={"eps": 0.03, "alpha": 0.005, "steps": 10},
            visualisers=[image_pair()],
        ),
    },
)
```

--------------------------------

### Configure Detection Explanation (Python)

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/transparency/detection.md

Set detection explanation parameters programmatically using Python. This example configures Integrated Gradients with specific detection settings.

```python
from raitap.transparency import captum, detection_image

transparency = {
    "my_ig_explainer": captum(
        algorithm="IntegratedGradients",
        call={"target": 0},
        raitap={
            "detection": {
                "score_threshold": 0.5,
                "max_boxes": 5,
                "iou_threshold": 0.5,
            }
        },
        visualisers=[detection_image()],
    ),
}
```

--------------------------------

### Configure Model via CLI

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/model/configuration.md

Example of configuring the model source using a command-line interface argument.

```bash
model.source=resnet50
```

--------------------------------

### Quickstart: Run RAITAP Configuration from Python

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/configuration/python-api.md

Build an AppConfig object and pass it to the 'run' function to execute a RAITAP pipeline. The results are returned as a RunOutputs object. Set verbose=False to suppress the console summary.

```python
from raitap import AppConfig, Hardware, run
from raitap.data import DataConfig, LabelsConfig
from raitap.metrics import multiclass_classification
from raitap.models import ModelConfig
from raitap.robustness import image_pair, torchattacks
from raitap.transparency import captum, captum_image

cfg = # config code, omitted

outputs = run(cfg, verbose=False)
```

--------------------------------

### Install Dependencies with Pip

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/installing/automatic.md

Use this command to have RAITAP automatically install dependencies using pip.

```bash
raitap --config-dir my-configs --config-name assessment
```

--------------------------------

### Install RAITAP with Transparency extra

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/installing/manual.md

Install RAITAP with the 'transparency' assessment extra. This includes all libraries associated with transparency assessments. Choose 'uv' or 'pip'.

```bash
uv add "raitap[transparency]"
```

```bash
pip install "raitap[transparency]"
```

--------------------------------

### SuperXAI Explainer Adapter

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/adding/adding-an-adapter.md

Example of creating a new adapter for the SuperXAI library. This snippet demonstrates the use of the `@adapters.transparency` decorator with various configuration options and the implementation of the `compute_attributions` method.

```python
from __future__ import annotations

from typing import TYPE_CHECKING

from raitap import adapters
from raitap.transparency.contracts import ExplainerAlgorithmSpec, MethodFamily

from .base_explainer import AttributionOnlyExplainer

if TYPE_CHECKING:
    import torch
    import torch.nn as nn


@adapters.transparency(
    registry_name="superxai",      # CLI `+transparency=superxai` / Python `from raitap.transparency import superxai`
    # extra="superxai",            # uv extra name; defaults to `registry_name` (omit unless they differ, see metrics for an exception)
    library="superxai-lib",        # real PyPI package name; drives `self._lazy_import()`
    error_patterns={
        r"some library footgun": "Do X instead.",
    },
    suppress_warnings=[
        (r"some noisy.*pattern", UserWarning, r"superxai.*",),
    ],
    algorithm_registry={
        # supertreeshap is model-agnostic (works on any backend): leave requires default empty.
        "supertreeshap": ExplainerAlgorithmSpec({MethodFamily.SHAPLEY}),
    },
    # output_payload_kind=ExplanationPayloadKind.ATTRIBUTIONS  # optional, this is the default
)
class SuperXAIExplainer(AttributionOnlyExplainer):
    def __init__(self, algorithm: str, **init_kwargs):
        super().__init__()
        self.algorithm = algorithm
        self.init_kwargs = init_kwargs

    # check_backend_compat: inherited from AdapterMixin. Raises BackendIncompatibilityError
    # when algorithm.requires - backend.provides is non-empty. Write zero gate code here.
    # Override only for a non-capability contract, e.g. MarabouAssessor per-call setup.

    def compute_attributions(
        self,
        model: nn.Module,
        inputs: torch.Tensor,
        backend=None,
        **call_kwargs,
    ) -> torch.Tensor:
        superxai = self._lazy_import()
        with self._rethrow():
            return getattr(superxai, self.algorithm)(model, **self.init_kwargs).attribute(
                inputs, **call_kwargs
            )

```

--------------------------------

### Install RAITAP with CUDA backend

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/installing/manual.md

Use this command to install RAITAP with the CUDA hardware backend. This is for NVIDIA GPUs. Choose 'uv' or 'pip' based on your package manager.

```bash
uv add "raitap[torch-cuda]"
```

```bash
pip install "raitap[torch-cuda]"
```

--------------------------------

### Valid Conventional Commit Examples

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/pull-requests.md

Examples demonstrating valid Conventional Commit formats, including optional scopes, documentation types, and marking breaking changes with an exclamation mark.

```text
feat(transparency): add batch SHAP visualiser
```

```text
fix: correct dtype in metrics export
```

```text
docs: describe reporting PDF options
```

```text
feat(api)!: remove deprecated explainer alias
```

--------------------------------

### YAML Configuration Example

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/configuration/general.md

This YAML configuration sets up metrics for multiclass classification and defines a PGD robustness assessor using Torchattacks.

```yaml
defaults:
  - raitap_schema
  - metrics: multiclass_classification
  - _self_

metrics:
  num_classes: 1000

robustness:
  pgd:
    _target_: TorchattacksAssessor
    algorithm: PGD
    constructor:
      eps: 0.03
      alpha: 0.005
      steps: 10
    visualisers:
      - _target_: ImagePairVisualiser
```

--------------------------------

### Auto-install Dependencies with run()

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/configuration/python-api.md

Enable automatic installation of extra dependencies required by the configuration by setting auto_install_deps=True in the run function. This is opt-in.

```python
# imports omitted

cfg = # config code, omitted

run(cfg, auto_install_deps=True)
```

--------------------------------

### Configuring Baseline Defaults for a New Algorithm

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/adding/adding-an-algorithm.md

Example of using the @adapters.transparency decorator to define baseline-related configurations for a new algorithm within the Captum explainer.

```python
import pytest

from raitap.adapters import transparency
from raitap.attribution import ExplainerAlgorithmSpec, MethodFamily, Capability, BaselineCardinality, BaselineMode


@transparency(
    registry_name="captum",
    baseline_kwarg_name="baselines",
    algorithm_registry={
        "IntegratedGradients": ExplainerAlgorithmSpec(
            {MethodFamily.GRADIENT},
            baseline_default=BaselineMode.ZERO,
            baseline_cardinality=BaselineCardinality.SINGLE,
            requires={Capability.AUTOGRAD},  # gradient method
        ),
        "NewMethod": ExplainerAlgorithmSpec(
            {MethodFamily.GRADIENT},
            baseline_default=BaselineMode.ZERO,
            baseline_cardinality=BaselineCardinality.SINGLE,
            requires={Capability.AUTOGRAD},  # gradient method
        ),
    },
)
class CaptumExplainer(AttributionOnlyExplainer): ...

```

--------------------------------

### Run RAITAP demo with uv

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/get-it-running.md

Execute the RAITAP demo using 'uv run'. This command runs the built-in demo example, which includes a tiny bundled dataset and uses CPU execution.

```bash
uv run raitap --demo
```

--------------------------------

### Run RAITAP demo

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/get-it-running.md

Execute the RAITAP demo directly. This command runs the built-in demo example, which includes a tiny bundled dataset and uses CPU execution.

```bash
raitap --demo
```

--------------------------------

### Python Configuration for List of Visualizers

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/configuration/python-api.md

Configure a list of visualizers by using a separate builder for each. Pass constructor keyword arguments directly and use an optional `call` dictionary for render-time options. This example shows configuration for `captum_image`.

```python
visualisers=[captum_image(max_samples=4, call={"show_sample_names": True})]
```

--------------------------------

### Data Configuration with Preprocessing

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/data/preprocessing.md

Configures data source and preprocessing paths using RAITAP's DataConfig. This example shows how to specify separate files for general preprocessing and model input transformation.

```yaml
data:
  source: ./data/images
  preprocessing: ./preprocessing.py
  model_input_transformation: ./preprocessing.py
```

```python
from raitap.data import DataConfig

data = DataConfig(
    source="./data/images",
    preprocessing="./preprocessing.py",
    model_input_transformation="./preprocessing.py",
)
```

--------------------------------

### Execute Configuration with uv

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/configuration/general.md

Run your RAITAP configuration using `uv run raitap --config-name <your_config_name>`. RAITAP will detect dependencies and guide you through the process. This assumes your config file is named `<your_config_name>.yaml`.

```bash
uv run raitap --config-name assessment # assuming your config is `./assessment.yaml`
```

--------------------------------

### Configure Reporting Module (CLI)

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/reporting/configuration.md

Command-line interface arguments for configuring the reporting module. This example sets the reporter to PDF, customizes the filename, disables multirun reports, enables specific panel displays, and sets a maximum page count for figures.

```bash
reporting=pdf reporting.filename="my_report" reporting.multirun_report=false reporting.show_original_per_explainer=true reporting.show_redundant_robustness_panels=true reporting.call.formatting.figures_max_pages=12
```

--------------------------------

### YAML Configuration for ShapExplainer

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/transparency/frameworks-and-libraries.md

Provides a minimal and a full configuration example for ShapExplainer in YAML format. The full configuration includes various options for visualization and explainer behavior.

```yaml
transparency:
  my_shap_explainer:
    _target_: "ShapExplainer"
    algorithm: "GradientExplainer"
    constructor:
      local_smoothing: 0.0
    call:
      target: 0
    raitap:
      baseline:
        source: imagenet_samples
        n_samples: 50
      batch_size: 1
    visualisers:
      # Minimal configuration
      - _target_: "ShapImageVisualiser"
        constructor:
          max_samples: 1

      # Full configuration with all options
      - _target_: "ShapImageVisualiser"
        constructor:
          max_samples: 2
          title: "Tumour attribution"
          include_original_image: true
          show_colorbar: true
          cmap: "coolwarm"
          overlay_alpha: 0.65
        call:
          show_sample_names: true
```

--------------------------------

### Configure plugin adapter in YAML

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/using-plugins.md

Configure a plugin adapter named 'superxai' in YAML format. Use the plugin class's full import path for the '_target_' key. This example sets the 'algorithm' parameter to 'supertreeshap'.

```yaml
transparency:
  my_run:
    _target_: "raitap_superxai.SuperXAIExplainer"   # full import path — plugin classes live outside raitap.*
    algorithm: supertreeshap
```

--------------------------------

### Configure and Run Multi-Explainer

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/examples/multi-explainer.md

This Python script sets up a Raitap application to run both Captum Integrated Gradients and Captum Saliency explainers concurrently. It defines the model, dataset, metrics, and transparency configurations, then executes the run with automatic dependency installation.

```python
from raitap import AppConfig, Hardware, run
from raitap.data import DataConfig, LabelsConfig
from raitap.metrics import multiclass_classification
from raitap.models import ModelConfig
from raitap.reporting import html
from raitap.transparency import captum, captum_image

cfg = AppConfig(
    hardware=Hardware.gpu,
    experiment_name="multi-explainer",
    model=ModelConfig(source="vit_b_32"),
    data=DataConfig(
        name="imagenet_samples",
        source="imagenet_samples",
        forward_batch_size=4,
        labels=LabelsConfig(
            source="imagenet_samples",
            id_column="image",
            column="label",
        ),
    ),
    metrics=multiclass_classification(num_classes=1000, average="weighted"),
    transparency={
        "ig": captum(
            algorithm="IntegratedGradients",
            call={"target": 0},
            visualisers=[captum_image()],
        ),
        "saliency": captum(
            algorithm="Saliency",
            call={"target": 0},
            visualisers=[captum_image()],
        ),
    },
    reporting=html(filename="report"),
)
outputs = run(cfg, auto_install_deps=True)
```

--------------------------------

### SuperXAI Explainer Adapter for RAITAP

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/writing-a-plugin.md

Implement a transparency explainer adapter for RAITAP. This example shows how to use the `@adapters.transparency` decorator to register your custom explainer, define its algorithms, and handle model attribution computation. Ensure to import base classes and decorators from RAITAP.

```python
# src/raitap_superxai/__init__.py

from __future__ import annotations

from typing import TYPE_CHECKING

from raitap import adapters
from raitap.transparency.contracts import ExplainerAlgorithmSpec, MethodFamily
from raitap.transparency.explainers.base_explainer import AttributionOnlyExplainer
from raitap.types import Capability

if TYPE_CHECKING:
    import torch
    import torch.nn as nn


@adapters.transparency(
    registry_name="superxai",      # CLI `+transparency=superxai` / Python `from raitap.transparency import superxai`
    library="superxai-lib",        # real name of your PyPI package; drives `self._lazy_import()` (defaults to registry_name)
    error_patterns={
        # rewrite cryptic upstream errors at call sites
        r"some library footgun": "Do X instead.", # nicer error messages to avoid deep stack traces in RAITAP
    },
    algorithm_registry={
        # the algos your library offers; ExplainerAlgorithmSpec carries the
        # method families (+ optional baseline_default for reference-input methods)
        # and the capability requirements for the algorithm.
        # empty requires (default) = model-agnostic, runs on ONNX/forward-only backends
        "supertreeshap": ExplainerAlgorithmSpec({MethodFamily.SHAPLEY}),
        # requires={Capability.AUTOGRAD} for algorithms that need autograd,
        # e.g. gradient-based methods:
        # "supergrad": ExplainerAlgorithmSpec({MethodFamily.GRADIENT},
        #                                       requires={Capability.AUTOGRAD}),
    },
)
class SuperXAIExplainer(AttributionOnlyExplainer):
    def __init__(self, algorithm: str, **init_kwargs):
        super().__init__()              # don't omit!
        self.algorithm = algorithm
        self.init_kwargs = init_kwargs

    def compute_attributions(
        self, 
        model: nn.Module,
        inputs: torch.Tensor,
        backend=None,
        **call_kwargs,
    ) -> torch.Tensor:
        superxai = self._lazy_import()  # don't omit!
        with self._rethrow():
            return getattr(superxai, self.algorithm)(model, **self.init_kwargs).attribute(
                inputs, **call_kwargs
            )

```

--------------------------------

### Preview Configuration with --help (uv)

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/configuration/general.md

Use the `uv run raitap --config-name <your_config_name> --help` command to preview the fully parsed configuration before execution. This assumes your config file is named `<your_config_name>.yaml`.

```bash
uv run raitap --config-name assessment --help # assuming your config is at `./assessment.yaml`
```

--------------------------------

### Python Script to Run Multi-Assessor Experiment

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/examples/multi-assessor.md

This Python script initializes a Raitap AppConfig with the specified multi-assessor setup and then executes the `run` function. Ensure all necessary dependencies are installed, which can be handled by `auto_install_deps=True`.

```python
from raitap import AppConfig, Hardware, run
from raitap.data import DataConfig, LabelsConfig
from raitap.metrics import multiclass_classification
from raitap.models import ModelConfig
from raitap.reporting import html
from raitap.robustness import image_pair, torchattacks
from raitap.transparency import captum, captum_image

cfg = AppConfig(
    hardware=Hardware.gpu,
    experiment_name="multi-assessor",
    model=ModelConfig(source="vit_b_32"),
    data=DataConfig(
        name="imagenet_samples",
        source="imagenet_samples",
        forward_batch_size=4,
        labels=LabelsConfig(
            source="imagenet_samples",
            id_column="image",
            column="label",
        ),
    ),
    metrics=multiclass_classification(num_classes=1000, average="micro"),
    transparency={
        "default": captum(
            algorithm="IntegratedGradients",
            call={"target": 0},
            visualisers=[captum_image()],
        ),
    },
    robustness={
        "pgd": torchattacks(
            algorithm="PGD",
            constructor={"eps": 0.03, "alpha": 0.005, "steps": 10},
            visualisers=[image_pair()],
        ),
        "fgsm": torchattacks(
            algorithm="FGSM",
            constructor={"eps": 0.03},
            visualisers=[image_pair()],
        ),
    },
    reporting=html(filename="report"),
)
outputs = run(cfg, auto_install_deps=True)
```

--------------------------------

### Preview Configuration with --help (pip)

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/configuration/general.md

Use the `raitap --config-name <your_config_name> --help` command to preview the fully parsed configuration before execution. This assumes your config file is named `<your_config_name>.yaml`.

```bash
raitap --config-name assessment --help # assuming your config is at `./assessment.yaml`
```

--------------------------------

### Discover Available Configs with --help (uv)

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/configuration/general.md

Use `uv run raitap --config-dir <path_to_configs> --config-name <your_config_name> --help` to discover available configuration groups and the fully composed config for the current invocation. This is useful for selecting presets or verifying overrides.

```bash
uv run raitap --config-dir my-configs --config-name assessment --help
```

--------------------------------

### Discover Available Configs with --help (pip)

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/configuration/general.md

Use `raitap --config-dir <path_to_configs> --config-name <your_config_name> --help` to discover available configuration groups and the fully composed config for the current invocation. This is useful for selecting presets or verifying overrides.

```bash
raitap --config-dir my-configs --config-name assessment --help
```

--------------------------------

### Install Commit Message Hook

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/setup.md

Installs a pre-commit hook to enforce conventional commit message formatting. This ensures consistency in commit messages.

```bash
uv run pre-commit install --hook-type commit-msg
```

--------------------------------

### DatasetAttack Invoker Example

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/modules/robustness.md

Example of a module-level function used as a custom invoker for DatasetAttack. It handles the two-stage lifecycle of feeding the sample pool before executing the attack.

```python
def _dataset_attack_invoker(ctx: AttackInvokeCtx) -> torch.Tensor:
    ...
    attack.feed(fmodel, inputs_dev)   # pool population
    ...
    _raw, clipped, success = attack(fmodel, inputs_dev, targets_dev, epsilons=eps)
    return clipped.detach()
```

--------------------------------

### Format Code with Ruff

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/setup.md

Formats all Python files according to the project's configured style guide.

```shell
uv run ruff format .
```

--------------------------------

### Stop detached tracker processes

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/tracking/frameworks-and-libraries.md

Use this command to shut down background servers or UIs started by some trackers that outlive a single run.

```bash
uv run raitap tracking stop
```

--------------------------------

### Configure plugin adapter in Python

Source: https://github.com/caiivs/raitap/blob/main/docs/using-raitap/using-plugins.md

Configure a plugin adapter named 'superxai' in Python. Import the adapter and instantiate it, passing the 'algorithm' parameter. This method does not require the full import path in the instantiation.

```python
from raitap.transparency import superxai

transparency = {"my_run": superxai(algorithm="supertreeshap")}
```

--------------------------------

### Structured Payloads Metadata

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/transparency/output.md

Example JSON snippet showing the structure for describing additive diagnostics (structured payloads) within the metadata.json file.

```json
"structured_payloads": [
  {
    "name": "convergence_delta",
    "kind": "convergence_delta",
    "storage": "tensor",
    "file": "payloads/convergence_delta.pt",
    "shape": [16],
    "dtype": "torch.float32"
  }
]
```

--------------------------------

### Baseline Block in Metadata

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/transparency/output.md

Example JSON snippet detailing the 'baseline' block within metadata.json, which documents the reference input used for attribution calculations.

```json
"baseline": {
  "kwarg_name": "background_data",
  "mode": "configured",
  "source": "imagenet_samples",
  "n_samples": 50,
  "shape": [50, 3, 224, 224],
  "dtype": "torch.float32",
  "sha256": "…",
  "image_path": "baseline.png"
}
```

--------------------------------

### Directory Structure for RAITAP Robustness Output

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/robustness/output.md

This example shows the typical directory structure for robustness output, including PGD and FGSM assessor results.

```text
└── robustness/
    ├── pgd/                                # Output for the `pgd` assessor
    │   ├── robustness_data.pt              # Clean / perturbed inputs, predictions, verdicts, distances
    │   ├── ImagePairVisualiser_0.png       # Visualisation written by the first visualiser
    │   └── metadata.json                   # Assessor metadata + serialised semantics
    └── fgsm/                               # One subdirectory per named assessor
        ├── robustness_data.pt
        ├── ImagePairVisualiser_0.png
        └── metadata.json
```

--------------------------------

### Configure Detection Explanation (YAML)

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/transparency/detection.md

Use this YAML configuration to set detection-specific parameters for explainers. Defaults are applied if options are omitted.

```yaml
transparency:
  my_ig_explainer:
    _target_: "CaptumExplainer"
    algorithm: "IntegratedGradients"
    call:
      target: 0
    raitap:
      detection:
        score_threshold: 0.5
        max_boxes: 5
        iou_threshold: 0.5
    visualisers:
      - _target_: "DetectionImageVisualiser"
```

--------------------------------

### Self-Test Plugin Resolution

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/writing-a-plugin.md

Run a Python command to confirm that your plugin resolves correctly as a first-party adapter after installation. This test will only pass if discovery and version checks were successful.

```python
python -c "from raitap.transparency import superxai; print(superxai)"
```

--------------------------------

### Run Tests with pytest

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/setup.md

Executes the test suite using pytest. Note that some tests may fail depending on installed dependencies, but the CI is the definitive source for test results.

```shell
uv run pytest
```

--------------------------------

### Configure Plugin Entry Point and Version Pin

Source: https://github.com/caiivs/raitap/blob/main/docs/contributor/writing-a-plugin.md

Add the `raitap.adapters` entry point and a RAITAP dependency pin to your `pyproject.toml` file. This allows RAITAP to find and version-check your plugin.

```toml
[project]
name = "raitap-superxai"  # plugin name, not your published PyPI package
dependencies = [
    "raitap>=0.5,<0.6",   # required: RAITAP reads this pin at load time
    "superxai-lib",       # your published PyPI package
]

[project.entry-points."raitap.adapters"]
superxai = "raitap_superxai"   # name of the file in src (see Step 1), NOT YOUR PLUGIN NAME

```

--------------------------------

### YAML Configuration for Captum Visualisers

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/transparency/visualisers.md

Declare Captum visualisers for an explainer in YAML format. This example shows how to specify IntegratedGradients algorithm with image and tabular bar chart visualisers.

```yaml
transparency:
  captum_ig:
    _target_: "CaptumExplainer"
    algorithm: "IntegratedGradients"
    visualisers:
      - _target_: "CaptumImageVisualiser"
      - _target_: "TabularBarChartVisualiser"
```

--------------------------------

### SHAP Explainer Configuration (YAML and Python)

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/transparency/frameworks-and-libraries.md

Configure a SHAP explainer with constructor, call, and RAITAP-specific options. Visualisers can also be configured.

```yaml
transparency:
  my_first_explainer:
    _target_: "ShapExplainer"
    algorithm: "GradientExplainer"
    constructor:
      local_smoothing: 0.0
    call:
      target: 0
    raitap:
      baseline:
        source: imagenet_samples
      batch_size: 1
    visualisers:
      - _target_: "ShapImageVisualiser"
        call:
          max_samples: 1
```

```python
from raitap.transparency import shap, shap_image

transparency = {
    "my_first_explainer": shap(
        algorithm="GradientExplainer",
        constructor={"local_smoothing": 0.0},
        call={"target": 0},
        raitap={
            "baseline": {"source": "imagenet_samples"},
            "batch_size": 1,
        },
        visualisers=[shap_image(call={"max_samples": 1})],
    ),
}
```

--------------------------------

### Configure DetectionMetrics with Custom IoU Thresholds

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/metrics/configuration.md

Use this YAML configuration to set custom IoU thresholds for object detection metrics. This example also enables class-specific metrics.

```yaml
metrics:
  _target_: "DetectionMetrics"
  iou:
    thresholds: [0.5, 0.75]
  class_metrics: true
```

--------------------------------

### Configure Labels from Directory Structure (Python)

Source: https://github.com/caiivs/raitap/blob/main/docs/modules/data/own-vs-built-in.md

Use this Python configuration to set the data source to a directory and infer labels from the subdirectory names. Assumes a standard ImageFolder structure.

```python
from raitap.data import DIRECTORY_LABELS_SOURCE, DataConfig, LabelsConfig

data = DataConfig(
    source="./data/train",
    labels=LabelsConfig(source=DIRECTORY_LABELS_SOURCE),  # == "directory"
)
```