Metadata-Version: 2.4
Name: autosafe
Version: 1.2.1
Summary: Reference implementation of the autoSAFE spec
Author: Johann Christensen
Author-email: Johann Christensen <johann.christensen@dlr.de>
License-Expression: MIT
License-File: LICENSES/CC-BY-4.0.txt
License-File: LICENSES/CC-BY-NC-ND-3.0.txt
License-File: LICENSES/CC-BY-NC-SA-4.0.txt
License-File: LICENSES/CC-BY-SA-4.0.txt
License-File: LICENSES/CC0-1.0.txt
License-File: LICENSES/MIT.txt
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: annotated-types>=0.7.0
Requires-Dist: faiss-cpu>=1.13.2
Requires-Dist: jax[cuda13]>=0.6.2 ; sys_platform == 'linux'
Requires-Dist: jax>=0.6.2 ; sys_platform != 'linux'
Requires-Dist: jaxtyping>=0.3.7
Requires-Dist: jsonschema>=4.25.1
Requires-Dist: loguru>=0.7.3
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: msgspec>=0.20.0
Requires-Dist: numpy>=2.2.6
Requires-Dist: orjson>=3.11.4
Requires-Dist: polars>=1.34.0
Requires-Dist: polytope>=0.2.5
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: pyarrow>=22.0.0
Requires-Dist: rich>=14.1.0
Requires-Dist: scikit-learn>=1.7.2
Requires-Dist: scipy>=1.15.3
Requires-Dist: tqdm>=4.67.1
Requires-Dist: typer>=0.16.1
Requires-Python: >=3.10
Project-URL: Documentation, https://autosafe.readthedocs.io/
Project-URL: Homepage, https://github.com/DLR-KI/autosafe/
Project-URL: Source, https://github.com/DLR-KI/autosafe/
Project-URL: Tracker, https://github.com/DLR-KI/autosafe/issues
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2026 German Aerospace Center (DLR e.V.) <https://dlr.de>

SPDX-License-Identifier: CC-BY-SA-4.0
-->

<!-- markdownlint-disable MD033 -->
<h1 align="center">
<img src="./docs/_static/autoSAFE.svg" alt="autoSAFE logo" width="300">
</h1><br>
<!-- markdownlint-enable MD033 -->

[![The latest version of autosafe can be found on PyPI.](https://img.shields.io/pypi/v/autosafe.svg)](https://pypi.python.org/pypi/autosafe)
[![Information on what versions of Python autosafe supports can be found on PyPI.](https://img.shields.io/pypi/pyversions/autosafe.svg)](https://pypi.python.org/pypi/autosafe)
[![Python tests (pytest)](https://github.com/DLR-KI/autosafe/actions/workflows/pytest.yaml/badge.svg)](https://github.com/DLR-KI/autosafe/actions/workflows/pytest.yaml)
[![Docs status](https://readthedocs.org/projects/autosafe/badge/)](https://autosafe.readthedocs.io/)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
[![prek](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/j178/prek/master/docs/assets/badge-v0.json)](https://github.com/DLR-KI/autosafe)
[![REUSE status](https://api.reuse.software/badge/github.com/DLR-KI/autosafe)](https://api.reuse.software/info/github.com/DLR-KI/autosafe)
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
[![Benchmark results archive DOI: TBD, not yet published](https://img.shields.io/badge/benchmark_results_DOI-TBD-lightgrey.svg)](./REPRODUCTION.md)

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](https://astral.sh/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](https://pypi.org/project/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:

```shell
uv run autosafe --help
```

This will list all available commands and options.
They are described in detail in the [documentation](https://autosafe.readthedocs.io/).

### Common CLI Commands

Here are the most frequently used commands:

#### Monte Carlo Sampling and Evaluation

```bash
# 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

```bash
# 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

```bash
# 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:

```python
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`](docs/pages/deduplication.rst) for the full policy and pipeline details:

```python
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](https://github.com/j178/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:

```shell
uv run prek install
```

### Tests

We use [pytest](https://pytest.org/) for testing.
To run the test suite, execute the following command from the project root:

```shell
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`](./REPRODUCTION.md).

## License

Copyright and license information are provided in accordance to the [REUSE Specification 3.3](https://reuse.software/spec-3.3/).
