ins-pricing 0.3.3__tar.gz → 0.4.0__tar.gz

{ins_pricing-0.3.3 → ins_pricing-0.4.0}/PKG-INFO

@@ -1,162 +1,162 @@
-Metadata-Version: 2.4
-Name: ins_pricing
-Version: 0.3.3
-Summary: Reusable modelling, pricing, governance, and reporting utilities.
-Author: meishi125478
-License: Proprietary
-Keywords: pricing,insurance,bayesopt,ml
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
-Classifier: License :: Other/Proprietary License
-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; 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: statsmodels>=0.13; extra == "bayesopt"
-Requires-Dist: joblib>=1.2; extra == "bayesopt"
-Requires-Dist: matplotlib>=3.5; extra == "bayesopt"
-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; 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; extra == "gnn"
-Requires-Dist: pynndescent>=0.5; extra == "gnn"
-Requires-Dist: torch-geometric>=2.3; extra == "gnn"
-Provides-Extra: all
-Requires-Dist: torch>=1.13; 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: statsmodels>=0.13; extra == "all"
-Requires-Dist: joblib>=1.2; extra == "all"
-Requires-Dist: matplotlib>=3.5; 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"
-
-# Insurance-Pricing
-
-A reusable toolkit for insurance modeling, pricing, governance, and reporting.
-
-## Overview
-
-Insurance-Pricing (ins_pricing) is an enterprise-grade Python library designed for machine learning model training, pricing calculations, and model governance workflows in the insurance industry.
-
-### Core Modules
-
-| Module | Description |
-|--------|-------------|
-| **modelling** | ML model training (GLM, XGBoost, ResNet, FT-Transformer, GNN) and model interpretability (SHAP, permutation importance) |
-| **pricing** | Factor table construction, numeric binning, premium calibration, exposure calculation, PSI monitoring |
-| **production** | Model prediction, batch scoring, data drift detection, production metrics monitoring |
-| **governance** | Model registry, version management, approval workflows, audit logging |
-| **reporting** | Report generation (Markdown format), report scheduling |
-| **utils** | Data validation, performance profiling, device management, logging configuration |
-
-### Quick Start
-
-```python
-# Model training with Bayesian optimization
-from ins_pricing import bayesopt as ropt
-
-model = ropt.BayesOptModel(
-    train_data, test_data,
-    model_name='my_model',
-    resp_nme='target',
-    weight_nme='weight',
-    factor_nmes=feature_list,
-    cate_list=categorical_features,
-)
-model.bayesopt_xgb(max_evals=100)      # Train XGBoost
-model.bayesopt_resnet(max_evals=50)    # Train ResNet
-model.bayesopt_ft(max_evals=50)        # Train FT-Transformer
-
-# Pricing: build factor table
-from ins_pricing.pricing import build_factor_table
-factors = build_factor_table(
-    df,
-    factor_col='age_band',
-    loss_col='claim_amount',
-    exposure_col='exposure',
-)
-
-# Production: batch scoring
-from ins_pricing.production import batch_score
-scores = batch_score(model.trainers['xgb'].predict, df)
-
-# Model governance
-from ins_pricing.governance import ModelRegistry
-registry = ModelRegistry('models.json')
-registry.register(model_name, version, metrics=metrics)
-```
-
-### Project Structure
-
-```
-ins_pricing/
-├── cli/                    # Command-line entry points
-├── modelling/
-│   ├── core/bayesopt/     # ML model training core
-│   ├── explain/           # Model interpretability
-│   └── plotting/          # Model visualization
-├── pricing/               # Insurance pricing module
-├── production/            # Production deployment module
-├── governance/            # Model governance
-├── reporting/             # Report generation
-├── utils/                 # Utilities
-└── tests/                 # Test suite
-```
-
-### Installation
-
-```bash
-# Basic installation
-pip install ins_pricing
-
-# Full installation (all optional dependencies)
-pip install ins_pricing[all]
-
-# Install specific extras
-pip install ins_pricing[bayesopt]    # Model training
-pip install ins_pricing[explain]     # Model explanation
-pip install ins_pricing[plotting]    # Visualization
-pip install ins_pricing[gnn]         # Graph neural networks
-```
-
-#### Multi-platform & GPU installation notes
-
-- **PyTorch (CPU/GPU/MPS)**: Install the correct PyTorch build for your platform/GPU first (CUDA on
-  Linux/Windows, ROCm on supported AMD platforms, or MPS on Apple Silicon). Then install the
-  optional extras you need (e.g., `bayesopt`, `explain`, or `gnn`). This avoids pip pulling a
-  mismatched wheel.
-- **Torch Geometric (GNN)**: `torch-geometric` often requires platform-specific wheels (e.g.,
-  `torch-scatter`, `torch-sparse`). Follow the official PyG installation instructions for your
-  CUDA/ROCm/CPU environment, then install `ins_pricing[gnn]`.
-- **Multi-GPU**: Training code will use CUDA when available and can enable multi-GPU via
-  `torch.distributed`/`DataParallel` where supported. On Windows, CUDA DDP is not supported and will
-  fall back to single-GPU or DataParallel where possible.
-
-### Requirements
-
-- Python >= 3.9
-- Core dependencies: numpy >= 1.20, pandas >= 1.4
-
-### License
-
-Proprietary
+Metadata-Version: 2.4
+Name: ins_pricing
+Version: 0.4.0
+Summary: Reusable modelling, pricing, governance, and reporting utilities.
+Author: meishi125478
+License: Proprietary
+Keywords: pricing,insurance,bayesopt,ml
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: License :: Other/Proprietary License
+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; 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: statsmodels>=0.13; extra == "bayesopt"
+Requires-Dist: joblib>=1.2; extra == "bayesopt"
+Requires-Dist: matplotlib>=3.5; extra == "bayesopt"
+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; 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; extra == "gnn"
+Requires-Dist: pynndescent>=0.5; extra == "gnn"
+Requires-Dist: torch-geometric>=2.3; extra == "gnn"
+Provides-Extra: all
+Requires-Dist: torch>=1.13; 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: statsmodels>=0.13; extra == "all"
+Requires-Dist: joblib>=1.2; extra == "all"
+Requires-Dist: matplotlib>=3.5; 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"
+
+# Insurance-Pricing
+
+A reusable toolkit for insurance modeling, pricing, governance, and reporting.
+
+## Overview
+
+Insurance-Pricing (ins_pricing) is an enterprise-grade Python library designed for machine learning model training, pricing calculations, and model governance workflows in the insurance industry.
+
+### Core Modules
+
+| Module | Description |
+|--------|-------------|
+| **modelling** | ML model training (GLM, XGBoost, ResNet, FT-Transformer, GNN) and model interpretability (SHAP, permutation importance) |
+| **pricing** | Factor table construction, numeric binning, premium calibration, exposure calculation, PSI monitoring |
+| **production** | Model prediction, batch scoring, data drift detection, production metrics monitoring |
+| **governance** | Model registry, version management, approval workflows, audit logging |
+| **reporting** | Report generation (Markdown format), report scheduling |
+| **utils** | Data validation, performance profiling, device management, logging configuration |
+
+### Quick Start
+
+```python
+# Model training with Bayesian optimization
+from ins_pricing import bayesopt as ropt
+
+model = ropt.BayesOptModel(
+    train_data, test_data,
+    model_name='my_model',
+    resp_nme='target',
+    weight_nme='weight',
+    factor_nmes=feature_list,
+    cate_list=categorical_features,
+)
+model.bayesopt_xgb(max_evals=100)      # Train XGBoost
+model.bayesopt_resnet(max_evals=50)    # Train ResNet
+model.bayesopt_ft(max_evals=50)        # Train FT-Transformer
+
+# Pricing: build factor table
+from ins_pricing.pricing import build_factor_table
+factors = build_factor_table(
+    df,
+    factor_col='age_band',
+    loss_col='claim_amount',
+    exposure_col='exposure',
+)
+
+# Production: batch scoring
+from ins_pricing.production import batch_score
+scores = batch_score(model.trainers['xgb'].predict, df)
+
+# Model governance
+from ins_pricing.governance import ModelRegistry
+registry = ModelRegistry('models.json')
+registry.register(model_name, version, metrics=metrics)
+```
+
+### Project Structure
+
+```
+ins_pricing/
+├── cli/                    # Command-line entry points
+├── modelling/
+│   ├── core/bayesopt/     # ML model training core
+│   ├── explain/           # Model interpretability
+│   └── plotting/          # Model visualization
+├── pricing/               # Insurance pricing module
+├── production/            # Production deployment module
+├── governance/            # Model governance
+├── reporting/             # Report generation
+├── utils/                 # Utilities
+└── tests/                 # Test suite
+```
+
+### Installation
+
+```bash
+# Basic installation
+pip install ins_pricing
+
+# Full installation (all optional dependencies)
+pip install ins_pricing[all]
+
+# Install specific extras
+pip install ins_pricing[bayesopt]    # Model training
+pip install ins_pricing[explain]     # Model explanation
+pip install ins_pricing[plotting]    # Visualization
+pip install ins_pricing[gnn]         # Graph neural networks
+```
+
+#### Multi-platform & GPU installation notes
+
+- **PyTorch (CPU/GPU/MPS)**: Install the correct PyTorch build for your platform/GPU first (CUDA on
+  Linux/Windows, ROCm on supported AMD platforms, or MPS on Apple Silicon). Then install the
+  optional extras you need (e.g., `bayesopt`, `explain`, or `gnn`). This avoids pip pulling a
+  mismatched wheel.
+- **Torch Geometric (GNN)**: `torch-geometric` often requires platform-specific wheels (e.g.,
+  `torch-scatter`, `torch-sparse`). Follow the official PyG installation instructions for your
+  CUDA/ROCm/CPU environment, then install `ins_pricing[gnn]`.
+- **Multi-GPU**: Training code will use CUDA when available and can enable multi-GPU via
+  `torch.distributed`/`DataParallel` where supported. On Windows, CUDA DDP is not supported and will
+  fall back to single-GPU or DataParallel where possible.
+
+### Requirements
+
+- Python >= 3.9
+- Core dependencies: numpy >= 1.20, pandas >= 1.4
+
+### License
+
+Proprietary

ins_pricing-0.4.0/ins_pricing/docs/LOSS_FUNCTIONS.md

@@ -0,0 +1,78 @@
+LOSS FUNCTIONS
+
+Overview
+This document describes the loss-function changes in ins_pricing. The training
+stack now supports multiple regression losses (not just Tweedie deviance) and
+propagates the selected loss into tuning, training, and inference.
+
+Supported loss_name values
+- auto (default): keep legacy behavior based on model name
+- tweedie: Tweedie deviance (uses tw_power / tweedie_variance_power when tuning)
+- poisson: Poisson deviance (power=1)
+- gamma: Gamma deviance (power=2)
+- mse: mean squared error
+- mae: mean absolute error
+
+Loss name mapping (all options)
+- Tweedie deviance -> tweedie
+- Poisson deviance -> poisson
+- Gamma deviance -> gamma
+- Mean squared error -> mse
+- Mean absolute error -> mae
+- Classification log loss -> logloss (classification only)
+- Classification BCE -> bce (classification only)
+
+Classification tasks
+- loss_name can be auto, logloss, or bce
+- training continues to use BCEWithLogits for torch models; evaluation uses logloss
+
+Where to set loss_name
+Add to any BayesOpt config JSON:
+
+{
+  "task_type": "regression",
+  "loss_name": "mse"
+}
+
+Behavior changes
+1) Tuning and metrics
+   - When loss_name is mse/mae, tuning does not sample Tweedie power.
+   - When loss_name is poisson/gamma, power is fixed (1.0/2.0).
+   - When loss_name is tweedie, power is sampled as before.
+
+2) Torch training (ResNet/FT/GNN)
+   - Loss computation is routed by loss_name.
+   - For tweedie/poisson/gamma, predictions are clamped positive.
+   - For mse/mae, no Tweedie power is used.
+
+3) XGBoost objective
+   - loss_name controls XGB objective:
+     - tweedie -> reg:tweedie
+     - poisson -> count:poisson
+     - gamma -> reg:gamma
+     - mse -> reg:squarederror
+     - mae -> reg:absoluteerror
+
+4) Inference
+   - ResNet/GNN constructors now receive loss_name.
+   - When loss_name is not tweedie, tw_power is not applied at inference.
+
+Legacy defaults (auto)
+- If loss_name is omitted, behavior is unchanged:
+  - model name contains "f" -> poisson
+  - model name contains "s" -> gamma
+  - otherwise -> tweedie
+
+Examples
+- ResNet direct training (MSE):
+  "loss_name": "mse"
+
+- FT embed -> ResNet (MSE):
+  "loss_name": "mse"
+
+- XGB direct training (unchanged):
+  omit loss_name or set "loss_name": "auto"
+
+Notes
+- loss_name is global per config. If you need different losses for different
+  models, split into separate configs and run them independently.

{ins_pricing-0.3.3 → ins_pricing-0.4.0}/ins_pricing/docs/modelling/BayesOpt_USAGE.md

@@ -75,13 +75,13 @@ Under `ins_pricing/modelling/core/bayesopt/`:
 
 1) **Tools and utilities**
 
-- `IOUtils / TrainingUtils / PlotUtils`: I/O, training utilities (batch size, tweedie loss, free_cuda), plotting helpers
+- `IOUtils / TrainingUtils / PlotUtils`: I/O, training utilities (batch size, loss functions, free_cuda), plotting helpers
 - `DistributedUtils`: DDP init, rank/world_size helpers
 
 2) **TorchTrainerMixin (common components for torch tabular training)**
 
 - DataLoader: `_build_dataloader()` / `_build_val_dataloader()` (prints batch/accum/workers)
-- Loss: `_compute_losses()` / `_compute_weighted_loss()` (regression uses tweedie; classification uses BCEWithLogits)
+- Loss: `_compute_losses()` / `_compute_weighted_loss()` (regression supports tweedie/poisson/gamma/mse/mae; classification uses BCEWithLogits)
 - Early stop: `_early_stop_update()`
 
 3) **Sklearn-style model classes (core training objects)**
@@ -292,7 +292,7 @@ FT role is controlled by `ft_role` (from config or CLI `--ft-role`):
 ### 4.1 Supervised models (GLM/XGB/ResNet/FT-as-model)
 
 - `TrainerBase.tune()` calls each trainer's `cross_val()` and minimizes validation metric (default direction `minimize`)
-- Regression typically uses Tweedie deviance or related loss; classification uses logloss
+- Regression loss is configurable (tweedie/poisson/gamma/mse/mae); classification uses logloss
 
 ### 4.2 FT self-supervised (`unsupervised_embedding`)
 

ins_pricing-0.4.0/ins_pricing/frontend/QUICKSTART.md

@@ -0,0 +1,152 @@
+# Quick Start Guide
+
+Get started with the Insurance Pricing Model Training Frontend in 3 easy steps.
+
+## Prerequisites
+
+1. Install the `ins_pricing` package
+2. Install Gradio:
+   ```bash
+   pip install gradio>=4.0.0
+   ```
+
+## Step 1: Launch the Application
+
+### On Windows:
+Double-click `start_app.bat` or run:
+```bash
+python -m ins_pricing.frontend.app
+```
+
+### On Linux/Mac:
+Run the shell script:
+```bash
+./start_app.sh
+```
+
+Or use Python directly:
+```bash
+python -m ins_pricing.frontend.app
+```
+
+The web interface will automatically open at `http://localhost:7860`
+
+## Step 2: Configure Your Model
+
+### Option A: Upload Existing Config (Recommended)
+1. Go to the **Configuration** tab
+2. Click **"Upload JSON Config File"**
+3. Select a config file (e.g., `config_xgb_direct.json` from `examples/`)
+4. Click **"Load Config"**
+
+### Option B: Manual Configuration
+1. Go to the **Configuration** tab
+2. Scroll to **"Manual Configuration"**
+3. Fill in the required fields:
+   - **Data Directory**: Path to your data folder
+   - **Model List**: Model name(s)
+   - **Target Column**: Your target variable
+   - **Weight Column**: Your weight variable
+   - **Feature List**: Comma-separated features
+   - **Categorical Features**: Comma-separated categorical features
+4. Adjust other settings as needed
+5. Click **"Build Configuration"**
+
+## Step 3: Run Training
+
+1. Switch to the **Run Task** tab
+2. Click **"Run Task"**
+3. Watch real-time logs appear below
+
+Training will start automatically and logs will update in real-time!
+
+## New Features
+
+### FT Two-Step Workflow
+
+For advanced FT-Transformer → XGB/ResN training:
+
+1. **Prepare Base Config**: Create or load a base configuration
+2. **Go to FT Two-Step Workflow tab**
+3. **Step 1 - FT Embedding Generation**:
+   - Configure DDP settings
+   - Click "Prepare Step 1 Config"
+   - Copy the config to Configuration tab
+   - Run it in "Run Task" tab
+4. **Step 2 - Train XGB/ResN**:
+   - After Step 1 completes, click "Prepare Step 2 Configs"
+   - Choose which models to train (XGB, ResN, or both)
+   - Copy the generated configs and run them
+
+### Open Results Folder
+
+- In the **Run Task** tab, click **"📁 Open Results Folder"**
+- Automatically opens the output directory in your file explorer
+- Works on Windows, macOS, and Linux
+
+## Example Configuration
+
+Here's a minimal example to get started:
+
+```json
+{
+  "data_dir": "./Data",
+  "model_list": ["od"],
+  "model_categories": ["bc"],
+  "target": "response",
+  "weight": "weights",
+  "feature_list": ["age", "gender", "region"],
+  "categorical_features": ["gender", "region"],
+  "runner": {
+    "mode": "entry",
+    "model_keys": ["xgb"],
+    "max_evals": 50
+  }
+}
+```
+
+Save this as `my_first_config.json` and upload it!
+
+## Tips
+
+- **Save Your Config**: After building a configuration, save it using the "Save Configuration" button for reuse
+- **Check Logs**: Training logs update in real-time - watch for errors or progress indicators
+- **GPU Usage**: Toggle "Use GPU" checkbox in Training Settings to enable/disable GPU acceleration
+- **Model Selection**: Specify which models to train in "Model Keys" (xgb, resn, ft, gnn)
+- **Open Results**: Use the "📁 Open Results Folder" button to quickly access output files
+- **FT Workflow**: Use the dedicated FT tab for automated two-step FT → XGB/ResN training
+
+## Troubleshooting
+
+**Problem**: Interface doesn't load
+- **Solution**: Check that port 7860 is not in use, or specify a different port
+
+**Problem**: Configuration validation fails
+- **Solution**: Ensure all required fields are filled and feature lists are properly formatted
+
+**Problem**: Training doesn't start
+- **Solution**: Verify data paths exist and configuration is valid
+
+**Problem**: Results folder won't open
+- **Solution**: Make sure the task has run at least once to create the output directory
+
+**Problem**: Step 2 configs fail to generate
+- **Solution**: Ensure Step 1 completed successfully and embedding files exist
+
+## Next Steps
+
+- Explore advanced options in the Configuration tab
+- Try the FT Two-Step Workflow for better model performance
+- Experiment with different model combinations (xgb, resn, ft)
+- Try different split strategies
+- Use the Explain mode for model interpretability
+- Check the full [README.md](README.md) for detailed documentation
+
+## Support
+
+For issues or questions, refer to:
+- Full documentation: [README.md](README.md)
+- Example configs: `ins_pricing/examples/`
+- Package documentation: `ins_pricing/docs/`
+
+Happy modeling!