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
• Agent quick rules: AGENTS.md
• Status: PROGRESS.md

Install

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

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

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

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/ 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.

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:

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

Dev

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