Metadata-Version: 2.4
Name: riskit
Version: 1.0.0
Summary: A library providing implementations of various risk metrics for risk-aware trajectory planning.
Author-email: Zurab Mujirishvili <zurab.mu@gmail.com>
License-File: LICENSE
Keywords: autonomous systems,risk metrics,robotics,safety,trajectory planning,uncertainty quantification
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: jaxtyping>=0.3.6
Requires-Dist: lazy-loader>=0.5
Requires-Dist: numtypes>=0.5.1
Provides-Extra: accelerated
Requires-Dist: jax>=0.9.0; extra == 'accelerated'
Provides-Extra: test
Requires-Dist: anyio>=4.13.0; extra == 'test'
Requires-Dist: pyneedy>=1.4.0; extra == 'test'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'test'
Requires-Dist: pytest>=9.0.3; extra == 'test'
Requires-Dist: scipy>=1.17.1; extra == 'test'
Provides-Extra: type-checking
Requires-Dist: beartype>=0.22.9; extra == 'type-checking'
Provides-Extra: visualization
Requires-Dist: anyio>=4.13.0; extra == 'visualization'
Requires-Dist: kaleido>=1.3.0; extra == 'visualization'
Requires-Dist: plotly>=6.7.0; extra == 'visualization'
Requires-Dist: rich>=15.0.0; extra == 'visualization'
Requires-Dist: scipy>=1.17.1; extra == 'visualization'
Description-Content-Type: text/markdown

[![CI](https://gitlab.com/risk-metrics/riskit/badges/main/pipeline.svg)](https://gitlab.com/risk-metrics/riskit/-/pipelines) [![Coverage](https://codecov.io/gl/risk-metrics/riskit/graph/badge.svg)](https://codecov.io/gl/risk-metrics/riskit) [![PyPI](https://img.shields.io/pypi/v/riskit)](https://pypi.org/project/riskit/) [![Python](https://img.shields.io/pypi/pyversions/riskit)](https://pypi.org/project/riskit/) [![License](https://img.shields.io/pypi/l/riskit)](https://gitlab.com/risk-metrics/riskit/-/blob/main/LICENSE)

# RisKit: Risk Metrics for Risk-Aware Planning

RisKit provides implementations of common risk metrics used in risk-aware trajectory planning, intended for researchers who need reliable risk quantification under uncertainty.

The library provides the following metrics:
- Expected Value, 
- Mean-Variance, 
- Value at Risk (VaR), 
- Conditional Value at Risk (CVaR), and
- Entropic Risk metrics, 

with built-in support for both NumPy and JAX backends (can easily be extended to other backends, e.g. PyTorch). The API is type-safe, but offers automatic backend inference based on the type annotations of the cost function (uncertain variable transform).

> RisKit is being actively developed. Some features may be missing and some of the API might change. You can help by [reporting issues](https://gitlab.com/risk-metrics/riskit/-/issues) or contributing fixes and features.

## Installation

Python 3.13+ is required.

```bash
pip install riskit
```

## Quick Start

```python
import numpy as np
from numtypes import array, Dim2
from riskit import (
    risk, distribution,
    NumPyInputAndState, NumPyUncertaintySamples, NumPyCosts,
)

# A cost function takes typed trajectories and uncertainty samples,
# and returns a costs array of shape (T, M, N). You're free to use
# any type you want though, as long as it supports the necessary operations.
def distance_cost(
    *,
    trajectories: NumPyInputAndState,
    uncertainties: NumPyUncertaintySamples[Dim2],
) -> NumPyCosts:
    x = trajectories.x          # (T, D_x, M)
    xi = uncertainties           # (V, D, N)
    T, _, M = x.shape
    _, _, N = xi.shape
    return np.tile((x[:, 0, :, None] - xi[0, 0, None, :]) ** 2, (1, 1, 1)).reshape(T, M, N)

# The factory infers the NumPy backend from the cost function's return type.
metric = risk.cvar_of(distance_cost, alpha=0.1)

# Create an uncertainty distribution.
uncertainties = distribution.numpy.gaussian(
    mean=array([[0.0]], shape=(1, 1)),
    covariance=array([[[1.0]]], shape=(1, 1, 1)),
    seed=42,
)

# Compute risk over trajectories and uncertainty samples.
results = metric.compute(trajectories=..., uncertainties=uncertainties)
```

If the cost function in your case works with JAX and returns a JAX array, you can just use the appropriate type annotation and the JAX backend will be automatically inferred.

## Risk Metrics

| Metric          | Factory                               | Description                            |
|-----------------|---------------------------------------|----------------------------------------|
| Expected Value  | `risk.expected_value_of(f)`           | Mean cost across samples               |
| Mean-Variance   | `risk.mean_variance_of(f, gamma=...)` | Mean + γ · Variance tradeoff           |
| Value at Risk   | `risk.var_of(f, alpha=...)`           | α-quantile of the cost distribution    |
| Conditional VaR | `risk.cvar_of(f, alpha=...)`          | Expected cost in the worst α-fraction  |
| Entropic Risk   | `risk.entropic_risk_of(f, theta=...)` | Exponential utility-based risk measure |

## Features

- **Multiple risk metrics** with a consistent, protocol-based API
- **NumPy and JAX backends** with automatic inference from type annotations
- **Monte Carlo sampling** with built-in distributions, or custom sampling strategies

## Documentation

To build the Typst-based documentation, install the custom Typst packages locally:

```bash
typi --project-directory=documents
```

`typi` is available after you've set up the project environment with `uv sync`.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT, see [LICENSE](LICENSE).
