Reference implementation of the autoSAFE specification.

autoSAFE can derive semantically correct Operational Design Domains (ODDs) purely from data. This allows to automatically generate ODDs for machine learning-based functions. The use cases range from data-driven ODD definition over ODD monitoring to retrofitting existing functions with ODDs. Moreover, if no ODD is given for a certain dataset, autoSAFE can derive one automatically to ensure safe operations of the resulting AI-based system

Installation

We recommend using uv to manage the virtual environment and dependencies. Simply running uv sync will create a virtual environment and install all dependencies as specified in pyproject.toml.

CVXOPT

Users might want to optionally install CVXOPT for enhanced performance. However, as CVXOPT is licensed under GPL-v3, it is not included as a dependency by default. Moreover, CVXOPT is not compatible with Python versions >= 3.14 or free-threaded builds as of now.

Usage

CLI

autoSAFE provides a command-line interface (CLI) for easy interaction. After installing the package, you can use the autosafe command in your terminal:

uv run autosafe --help

This will list all available commands and options. They are described in detail in the documentation.

Common CLI Commands

Here are the most frequently used commands:

Monte Carlo Sampling and Evaluation

# Run Monte Carlo sampling with default 2D box ODD
autosafe montecarlo sample --dim 2 --odd-limits 5.0 --samples 1000 --filename mc_results.json

# Evaluate results and generate precision/recall plots
autosafe montecarlo evaluate mc_results.json

ODD Comparison Methods

# Quick comparison with default parameters
autosafe comparison quick data/WineQT.csv --export results.json

# Full comparison with custom parameters
autosafe comparison evaluate data/WineQT.csv \
    --methods knn kmeans density \
    --knn-k 5 --kmeans-clusters 4 --density-gamma 0.01

Custom ODD with Inequalities

# Use YAML config for polytope with inequality constraints
autosafe montecarlo sample --odd-config odd_config.yaml

API

autoSAFE also offers a Python API for more advanced usage. To start, you can read your data from a CSV file and create an autoSAFE ODD as follows:

import autosafe as af
import numpy as np

# Load data from a CSV file
odd = af.from_csv(af.ROOT_FOLDER / "data" / "iris.csv")

# Query the ODD for a new data point
affinity_threshold = 0.8
data_point = np.array([[5.1, 3.5, 1.4, 0.2]])
is_within_odd = odd(data_point) >= affinity_threshold
print(f"The data point is within the ODD: {is_within_odd}")

De-duplication of repeated-visit anchors is OFF by default (enabling it changes the anchor set, so previously computed results are not comparable); see docs/pages/deduplication.rst for the full policy and pipeline details:

from autosafe.deduplication import exact_equality_policy

policy = exact_equality_policy(n_dims=4)
odd = af.from_csv(af.ROOT_FOLDER / "data" / "iris.csv", dedup_policy=policy)

Developing

Pre-Commit Hooks

We use prek to manage pre-commit hooks for code quality and consistency. To install the pre-commit hooks, run the following command from the project root:

uv run prek install

Tests

We use pytest for testing. To run the test suite, execute the following command from the project root:

uv run pytest

Reproducing the paper's results

The result artifacts underlying every figure and table in the paper, the archive record (once published), and the exact commands to regenerate them from scratch are documented in REPRODUCTION.md.

License

Copyright and license information are provided in accordance to the REUSE Specification 3.3.