Metadata-Version: 2.4
Name: spotanomaly2-safe
Version: 0.1.0
Summary: Stateless anomaly scoring library for forecast-based anomaly detection
Project-URL: Documentation, https://sequential-parameter-optimization.github.io/spotanomaly2-safe/
Project-URL: Repository, https://github.com/sequential-parameter-optimization/spotanomaly2-safe
Project-URL: Issues, https://github.com/sequential-parameter-optimization/spotanomaly2-safe/issues
Author-email: bartzbeielstein <32470350+bartzbeielstein@users.noreply.github.com>
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: anomaly-detection,scoring,time-series
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Requires-Python: >=3.13
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Provides-Extra: dev
Requires-Dist: bandit<2.0,>=1.8.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: reuse>=6.2.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2026 bartzbeielstein
SPDX-License-Identifier: AGPL-3.0-or-later
-->

# spotanomaly2-safe

## Features

### Version & License

[![Python Version](https://img.shields.io/badge/python-3.13%2B-blue)](https://www.python.org/downloads/)
[![GitHub Release](https://img.shields.io/github/v/release/sequential-parameter-optimization/spotanomaly2-safe)](https://github.com/sequential-parameter-optimization/spotanomaly2-safe/releases)
[![PyPI Version](https://img.shields.io/pypi/v/spotanomaly2-safe)](https://pypi.org/project/spotanomaly2-safe/)

[![License](https://img.shields.io/github/license/sequential-parameter-optimization/spotanomaly2-safe)](LICENSE)

### Downloads

[![PyPI Downloads](https://img.shields.io/pypi/dm/spotanomaly2-safe)](https://pypi.org/project/spotanomaly2-safe/)
[![Total Downloads](https://static.pepy.tech/badge/spotanomaly2-safe)](https://pepy.tech/project/spotanomaly2-safe)

### Quality

[![EU AI Act](https://img.shields.io/badge/EU%20AI%20Act-Ready-success)](MODEL_CARD.md)
[![Dependencies](https://img.shields.io/badge/dependencies-minimal-blue)](pyproject.toml)
[![Audit](https://img.shields.io/badge/audit-whitebox-brightgreen)](MODEL_CARD.md)
[![Reliability](https://img.shields.io/badge/robustness-fail--safe-orange)](MODEL_CARD.md)
[![Security](https://img.shields.io/badge/security-policy-blue)](https://github.com/sequential-parameter-optimization/spotanomaly2-safe/security/)

### Testing

[![Build Status](https://img.shields.io/github/actions/workflow/status/sequential-parameter-optimization/spotanomaly2-safe/ci.yml?branch=main&label=Tests)](https://github.com/sequential-parameter-optimization/spotanomaly2-safe/actions/workflows/ci.yml)
[![REUSE status](https://api.reuse.software/badge/github.com/sequential-parameter-optimization/spotanomaly2-safe)](https://api.reuse.software/info/github.com/sequential-parameter-optimization/spotanomaly2-safe)

### Scores

[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9999/badge)](https://www.bestpractices.dev/projects/9999)
[![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/sequential-parameter-optimization/spotanomaly2-safe)](https://scorecard.dev/viewer/?uri=github.com/sequential-parameter-optimization/spotanomaly2-safe)

### Status

[![Maintenance](https://img.shields.io/badge/maintenance-active-green)](https://github.com/sequential-parameter-optimization/spotanomaly2-safe)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)


## Safety-Critical Design Goals

`spotanomaly2-safe` is a stateless anomaly scoring library for forecast-based anomaly detection in safety-critical production environments.

Unlike general-purpose anomaly detection frameworks, it follows a strict Safety-First architecture by design. However, users must independently verify that these features meet their specific regulatory requirements:

- **Zero Side Effects**: Takes DataFrames of predictions + true values, returns anomaly scores + flags as DataFrames. Zero I/O, zero config files, zero data fetching.
- **Deterministic Logic**: The scoring algorithms are designed to be purely mathematical and deterministic.
- **Fail-Safe Operation**: The system is designed to favor explicit errors over silent failures when encountering invalid data.
- **EU AI Act Support**: The architecture supports transparency and data governance, helping users build compliant high-risk AI components.
- **Minimal Dependencies**: Only numpy, pandas, scikit-learn, and scipy — no unnecessary external packages.

For a detailed technical overview of our safety mechanisms, see [MODEL_CARD.md](MODEL_CARD.md).

## Installation

```bash
uv add spotanomaly2-safe
```

## Usage

```python
from spotanomaly2_safe import ForecastingAnomalyDetector

detector = ForecastingAnomalyDetector(
    scorer_name="KMeansScorer",
    scorer_params={"n_clusters": 3},
    high_quantile=0.99,
    normalize_scores=True,
    normalization_quantile=0.99,
)
scores_df, flags_df = detector.fit_score_detect(
    y_true_train=train_true_df,
    y_pred_train=train_pred_df,
    y_true_test=test_true_df,
    y_pred_test=test_pred_df,
)
```

## Disclaimer & Liability

IMPORTANT: This software is provided "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed.

In no event shall the authors, copyright holders, or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

The use of this software in safety-critical systems is at the sole risk of the user.

## Documentation

Documentation (API) will be available at: [https://sequential-parameter-optimization.github.io/spotanomaly2-safe/](https://sequential-parameter-optimization.github.io/spotanomaly2-safe/)

## Contributing

We welcome contributions to spotanomaly2-safe! Please read our [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on:

- Development setup and coding standards
- Testing and documentation requirements
- Commit message conventions
- Pull request process
- SPDX license header requirements

## License

`spotanomaly2-safe` software: [AGPL-3.0-or-later License](LICENSE)
