Metadata-Version: 2.3
Name: azoic
Version: 0.5.0
Summary: scikit-learn-compatible toolkit for non-life technical tariff (pure premium) modelling
Author: thomas-bury
Author-email: thomas-bury <thomas.bury@yuzzu.be>
License: MIT
Requires-Dist: numpy>=2.0
Requires-Dist: pandas>=3.0
Requires-Dist: scikit-learn>=1.6
Requires-Dist: glum>=3.0
Requires-Dist: lightgbm>=4.3
Requires-Dist: pyarrow>=15.0
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Requires-Dist: matplotlib>=3.8
Requires-Dist: openpyxl>=3.1
Requires-Dist: s3fs>=2024.6 ; extra == 'aws'
Requires-Dist: mlflow>=2.14 ; extra == 'mlops'
Requires-Dist: plotly>=6.9.0 ; extra == 'plot'
Requires-Dist: optuna>=3.6 ; extra == 'tune'
Requires-Python: >=3.12
Project-URL: Repository, https://github.com/ThomasBury/azoic
Project-URL: Issues, https://github.com/ThomasBury/azoic/issues
Project-URL: Documentation, https://thomasbury.github.io/azoic/
Provides-Extra: aws
Provides-Extra: mlops
Provides-Extra: plot
Provides-Extra: tune
Description-Content-Type: text/markdown

# Azoic

A scikit-learn-compatible Python toolkit for non-life technical tariff (pure
premium) modelling: actuarial preprocessing, GLM (glum) + GBM (LightGBM),
frequency-severity decomposition, actuarial diagnostics, reproducible runs,
GBM-to-GLM distillation, and multiplicative tariff export.

- Documentation: <https://thomasbury.github.io/azoic/>
- Hosted tutorial series: <https://thomasbury.github.io/azoic/tutorial/index.html>
- Full spec and conventions: [`PRD.md`](PRD.md)
- Agent quick rules: [`AGENTS.md`](AGENTS.md)
- Status: [`PROGRESS.md`](PROGRESS.md)

## Install

Requires Python 3.12 or newer. In your own uv project:

```bash
uv add azoic==0.5.0
uv run azoic --help
```

For development or the executable tutorial, clone this repository and run:

```bash
uv sync --no-dev                    # runtime only
uv sync                             # default development environment
uv sync --all-extras --all-groups   # everything
```

## Correctness conventions

Frequency models use `claim_count / exposure` with `sample_weight=exposure`.
`deviance_test` is exposure-weighted mean Tweedie deviance with fixed
`power=1.5`. Gini is a concentration Gini for ranking; equal prediction scores
are evaluated as tied blocks.

Temporal holdouts never split equal timestamps. Tuning selects parameters on an
inner split of the outer training partition, then refits on outer training data
and reports the untouched outer test. Exported tariffs reject unknown categorical
levels and non-finite numeric inputs.

Positive-objective GBMs can be exported through `azoic export-tariff
--distill`; the workbook reproduces the distilled GLM student, not the teacher.

## Executable tutorial series

The numbered Quarto book under [`examples/`](examples/) runs the complete
technical-tariff workflow on pinned OpenML data and then covers tuning,
temporal stability, protected-group audit, and manual tariff recipes. Install
the Jupyter kernel plus the MLflow, Plotly, and tuning extras; install Quarto
separately and ensure its `quarto` executable is on `PATH`.

```bash
uv sync --group demo --extra mlops --extra plot --extra tune
just demo
```

The render produces the ignored book under `examples/_book/`; fetched data,
the tariff workbook, reports, and local MLflow files stay under the ignored
`examples/_artifacts/`. To inspect the recorded run afterward:

```bash
uv run mlflow ui \
  --backend-store-uri sqlite:///examples/_artifacts/fremtpl2/mlflow.db
```

## Dev

```bash
just check          # ruff + ty + pytest
just test           # pytest -x
just lint
just format
uv run ty check     # production source types
```
