Metadata-Version: 2.4
Name: ins_pricing
Version: 0.11.1
Summary: Complete insurance model training, evaluation, pricing, prediction, and reporting tools.
Author: meishi125478
License-Expression: LicenseRef-Proprietary
Keywords: pricing,insurance,bayesopt,ml
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20
Requires-Dist: pandas>=1.4
Provides-Extra: bayesopt
Requires-Dist: torch>=1.13.1; extra == "bayesopt"
Requires-Dist: optuna>=3.0; extra == "bayesopt"
Requires-Dist: xgboost>=1.6; extra == "bayesopt"
Requires-Dist: scikit-learn>=1.1; extra == "bayesopt"
Requires-Dist: joblib>=1.2; extra == "bayesopt"
Requires-Dist: matplotlib>=3.5; extra == "bayesopt"
Requires-Dist: pyarrow<21,>=15; extra == "bayesopt"
Requires-Dist: glum<3.0,>=2.7; extra == "bayesopt"
Requires-Dist: tabmat>=3.1; extra == "bayesopt"
Provides-Extra: workflows
Requires-Dist: pyarrow<21,>=15; extra == "workflows"
Provides-Extra: plotting
Requires-Dist: matplotlib>=3.5; extra == "plotting"
Requires-Dist: scikit-learn>=1.1; extra == "plotting"
Provides-Extra: explain
Requires-Dist: torch>=1.13.1; extra == "explain"
Requires-Dist: shap>=0.41; extra == "explain"
Requires-Dist: scikit-learn>=1.1; extra == "explain"
Provides-Extra: geo
Requires-Dist: contextily>=1.3; extra == "geo"
Requires-Dist: matplotlib>=3.5; extra == "geo"
Provides-Extra: gnn
Requires-Dist: torch>=1.13.1; extra == "gnn"
Requires-Dist: pynndescent>=0.5; extra == "gnn"
Requires-Dist: torch-geometric>=2.3; extra == "gnn"
Provides-Extra: multi
Provides-Extra: multi-torch
Requires-Dist: torch>=1.13.1; extra == "multi-torch"
Requires-Dist: optuna>=3.0; extra == "multi-torch"
Provides-Extra: multi-ray
Requires-Dist: ray>=2.9; extra == "multi-ray"
Provides-Extra: multi-dask
Requires-Dist: dask[distributed]>=2024.1; extra == "multi-dask"
Provides-Extra: multi-spark
Requires-Dist: pyspark>=3.5; extra == "multi-spark"
Provides-Extra: multi-all
Requires-Dist: torch>=1.13.1; extra == "multi-all"
Requires-Dist: optuna>=3.0; extra == "multi-all"
Requires-Dist: ray>=2.9; extra == "multi-all"
Requires-Dist: dask[distributed]>=2024.1; extra == "multi-all"
Requires-Dist: pyspark>=3.5; extra == "multi-all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
Provides-Extra: all
Requires-Dist: torch>=1.13.1; extra == "all"
Requires-Dist: optuna>=3.0; extra == "all"
Requires-Dist: xgboost>=1.6; extra == "all"
Requires-Dist: scikit-learn>=1.1; extra == "all"
Requires-Dist: joblib>=1.2; extra == "all"
Requires-Dist: matplotlib>=3.5; extra == "all"
Requires-Dist: pyarrow<21,>=15; extra == "all"
Requires-Dist: shap>=0.41; extra == "all"
Requires-Dist: contextily>=1.3; extra == "all"
Requires-Dist: pynndescent>=0.5; extra == "all"
Requires-Dist: torch-geometric>=2.3; extra == "all"
Requires-Dist: glum<3.0,>=2.7; extra == "all"
Requires-Dist: tabmat>=3.1; extra == "all"

# ins_pricing

[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/ins_pricing)](https://pypi.org/project/ins_pricing/)
[![License: Proprietary](https://img.shields.io/badge/license-Proprietary-red)]()

A complete insurance modelling toolkit for model training, evaluation, pricing,
prediction, reporting, and config-driven FT, plot, explain, and compare workflows.

Core dependencies are `numpy` and `pandas`. Heavy modelling and workflow
dependencies are optional extras and are imported lazily where practical.

## Published Package Boundary

The PyPI distribution is named `ins_pricing` and publishes two import-package
families:

- `ins_pricing*`: modelling, pricing, production prediction, reporting,
  workflows, CLI, and shared utilities.
- `ins_pricing_multi*`: optional local, torchrun, Ray, Dask, and Spark
  orchestration helpers.

`ins_pricing.frontend`, `ins_pricing.governance`, and `model_manage_tool` are not
part of the published package. The wheel exposes exactly three model commands:
`ins-pricing-run`, `ins-pricing-incremental`, and `ins-pricing-explain`.

`model_processing/`, `model_processing_multi/`, tests, logs, build outputs, and
runtime data are repository resources, not installed package content.

## Installation

```bash
pip install ins_pricing                       # core: numpy + pandas
pip install ins_pricing[bayesopt]             # training and hyperparameter search
pip install ins_pricing[workflows]            # parquet-backed workflow data
pip install ins_pricing[plotting]             # model plots and diagnostics
pip install ins_pricing[explain]              # permutation, SHAP, gradients
pip install ins_pricing[geo]                  # geospatial plots
pip install ins_pricing[gnn]                  # graph neural networks
pip install ins_pricing[multi-all]            # all multi-backend launchers
pip install -e ".[dev,plotting,workflows]"    # lightweight development
pip install ins_pricing[all]                  # complete single-runtime model stack
```

Install the appropriate PyTorch build for the target CPU/GPU platform before
installing Torch-dependent extras. Torch Geometric can require platform-specific
wheels. Distributed training uses DDP with NCCL on Linux and Gloo where needed.

## Capabilities

| Area | What it provides |
|---|---|
| `modelling` | BayesOpt training for GLM, XGBoost, ResNet, FT-Transformer, and GNN; calibration, lift, bootstrap evaluation, explainability, and plotting. |
| `pricing` | Exposure-aware factor tables, numeric binning, premium rating, calibration, data quality, and PSI. |
| `production` | Predictor loading, preprocessing, batch scoring, drift checks, and production metrics. |
| `reporting` | Reusable model and pricing report builders and scheduling helpers. |
| `workflows` | Config-driven FT two-step, plot, explain, predict, compare, and notebook orchestration without a web UI. |
| `cli` | Training, incremental training, and explanation commands. |
| `utils` | Validation, loss resolution, metrics, device handling, logging, paths, prediction caches, and model artifact IO. |
| `ins_pricing_multi` | Optional local, torchrun, Ray, Dask, and Spark launchers. |

## Quick Start

### Train models

```python
from ins_pricing.modelling import BayesOptModel
from ins_pricing.modelling.bayesopt import BayesOptConfig

config = BayesOptConfig.from_file("config.json")
model = BayesOptModel(train_data, test_data, config=config)
model.optimize_model("xgb", max_evals=100)
model.optimize_model("resn", max_evals=50)
model.optimize_model("ft", max_evals=50)
```

### Build pricing factors

```python
from ins_pricing.pricing import build_factor_table, compute_base_rate, rate_premium

base_rate = compute_base_rate(df, loss_col="claim_amt", exposure_col="exposure")
age_factors = build_factor_table(
    df,
    factor_col="age_band",
    loss_col="claim_amt",
    exposure_col="exposure",
    base_rate=base_rate,
)
premium = rate_premium(
    df,
    exposure_col="exposure",
    base_rate=base_rate,
    factor_tables={"age_band": age_factors},
)
```

### Predict and report

```python
from ins_pricing.production import batch_score, load_predictor_from_config
from ins_pricing.reporting import ReportPayload, write_report

predictor = load_predictor_from_config("config.json", "xgb", device="cuda")
scored = batch_score(predictor.predict, df, batch_size=10_000)

payload = ReportPayload(
    model_name="pricing_xgb",
    model_version="v2",
    metrics={"rmse": 0.11, "loss_ratio": 0.63},
)
write_report(payload, "reports/monthly.md")
```

## Model CLI

```bash
ins-pricing-run --config-json config.json
ins-pricing-incremental --config-json config_incremental.json
ins-pricing-explain --config-json config_explain.json

# Direct module entrypoints remain useful for torchrun and debugging.
python -m ins_pricing.cli.bayesopt_entry_runner --config-json config.json
torchrun --nproc_per_node=2 -m ins_pricing.cli.bayesopt_entry_runner --config-json config.json
python -m ins_pricing.cli.Explain_entry --config-json config_explain.json
```

`config.runner.mode` selects `entry`, `incremental`, `explain`, or the internal
`watchdog` wrapper. The published console surface remains limited to the three
model commands above.

## FT Two-Step Workflow

Reusable orchestration lives under `ins_pricing.workflows`; notebooks and JSON
templates live under `model_processing/`.

Step A produces mean-pooled token embeddings. For vector feature export, one
final encoder is fitted on the full training split and that same encoder creates
both train and test embeddings. Vector embeddings must never be assembled from
OOF or fold-specific encoders. Cross-validation may estimate the final training
epoch count, but it does not publish vector features.

Step B combines the aligned embedding columns with the remaining raw features,
removes FT-only configuration fields, and trains the downstream XGBoost or
ResNet model. Preserve `_row_id`, split-cache alignment, and identical embedding
column order across train and test.

The same workflow package provides plot, explain, prediction, lift, double-lift,
and multi-model compare helpers.

## Project Structure

```text
ins_pricing/
  modelling/            Training, evaluation, explainability, and plots
  pricing/              Exposure, factors, calibration, and data quality
  production/           Predictor loading, scoring, and monitoring
  reporting/            Report builders and scheduling
  workflows/            FT, plot, explain, predict, compare, notebook helpers
  cli/                  Three published model commands plus internal runners
  utils/                Shared validation, metrics, paths, caches, and artifact IO
ins_pricing_multi/       Packaged multi-backend orchestration helpers
tests/                   Tests mirroring the supported package surface
model_processing/        Single-runtime notebooks and JSON templates
model_processing_multi/  Multi-runtime notebooks and templates
```

## Model Artifacts

Training outputs keep model artifacts under `Results/Models/...` and derived
plot, explain, compare, and report artifacts under `Results/Artifacts/...`.

Torch checkpoints expose a logical `.pth` active pointer. Each save publishes
an immutable same-stem `.pth`, `.json`, and `.manifest.json` triplet, validates
it, and atomically switches the pointer. Resolve active files with
`load_torch_artifact`, `validate_torch_artifact_files`, or
`torch_artifact_paths`; do not pass the logical pointer directly to
`torch.load`. Manifest hashes verify integrity, not provenance, so load only
trusted application-generated artifacts.

## Development

See `docs/development_setup.md` for environment and repository setup and
`docs/hooks.md` for local checks.

```bash
python -m pip install -e ".[dev,plotting,workflows]"
python scripts/hooks/check_package_config.py
python -m pytest tests -v
make build
python scripts/hooks/check_wheel_boundary.py dist/*.whl
make check
```

## Engineering Release

Publishing the `ins_pricing` Python distribution to PyPI and pushing the
corresponding source commit to GitHub is the engineering release workflow. It is
separate from the removed model registry, approval, promotion, and rollback
features.

```bash
# Linux / macOS
export TWINE_PASSWORD='your_pypi_token'
make build && make check && make upload

# Windows
set TWINE_PASSWORD=your_pypi_token
python -m build
upload_to_pypi.bat
```

Before publishing, verify the version, full retained test suite, wheel boundary,
`twine check`, and the intended Git commit. After publishing, verify PyPI and
GitHub independently.
