ins-pricing 0.4.4__py3-none-any.whl → 0.4.5__py3-none-any.whl

ins_pricing/docs/modelling/README.md

@@ -1,34 +0,0 @@
-# ins_pricing
-
-This directory contains reusable production-grade tooling and training frameworks, with a focus on the BayesOpt series.
-
-Key contents:
-- `core/bayesopt/`: core subpackage (data preprocessing, trainers, models, plotting, explainability)
-- `plotting/`: standalone plotting helpers (lift/roc/importance/geo)
-- `explain/`: explainability helpers (Permutation/Integrated Gradients/SHAP)
-- `core/BayesOpt.py`: compatibility entry point for legacy imports
-- `cli/BayesOpt_entry.py`: batch training CLI
-- `cli/BayesOpt_incremental.py`: incremental training CLI
-- `cli/utils/cli_common.py` / `cli/utils/notebook_utils.py`: shared CLI and notebook utilities
-- `examples/modelling/config_template.json` / `examples/modelling/config_incremental_template.json`: config templates
-- `cli/Explain_entry.py` / `cli/Explain_Run.py`: explainability entry points (load trained models)
-- `examples/modelling/config_explain_template.json` / `examples/modelling/Explain_Run.ipynb`: explainability demo
-
-Note: `examples/modelling/` is kept in the repo only and is not shipped in the PyPI package.
-Migration note: CLI entry points now live under `cli/` and demo assets are under `examples/modelling/`.
-
-Common usage:
-- CLI: `python ins_pricing/cli/BayesOpt_entry.py --config-json ...`
-- Notebook: `from ins_pricing.bayesopt import BayesOptModel`
-
-Explainability (load trained models under `Results/model` and explain a validation set):
-- CLI: `python ins_pricing/cli/Explain_entry.py --config-json ins_pricing/examples/modelling/config_explain_template.json`
-- Notebook: open `ins_pricing/examples/modelling/Explain_Run.ipynb` and run it
-
-Notes:
-- Models load from `output_dir/model` by default (override with `explain.model_dir`).
-- Validation data can be specified via `explain.validation_path`.
-
-Operational notes:
-- Training outputs are written to `plot/`, `Results/`, and `model/` by default.
-- Keep large data and secrets outside the repo and use environment variables or `.env`.

ins_pricing/frontend/QUICKSTART.md

@@ -1,152 +0,0 @@
-# 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!

ins_pricing/modelling/core/bayesopt/PHASE2_REFACTORING_SUMMARY.md

@@ -1,449 +0,0 @@
-# Phase 2 Refactoring: Simplified BayesOptModel API
-
-**Completion Date**: 2026-01-15
-**Status**: ✅ COMPLETE
-**Backward Compatibility**: 100% maintained
-
----
-
-## Executive Summary
-
-**Goal**: Simplify BayesOptModel instantiation by accepting a configuration object instead of 56+ individual parameters.
-
-**Impact**:
-- **Before**: 56 individual parameters (overwhelming for users)
-- **After**: Single `config` parameter (clean, maintainable)
-- **Compatibility**: Both old and new APIs work; old API shows deprecation warning
-
----
-
-## What Changed
-
-### 1. New Recommended API (Config-Based)
-
-**Before (Old API - 56 parameters)**:
-```python
-model = BayesOptModel(
-    train_data, test_data,
-    model_nme="my_model",
-    resp_nme="target",
-    weight_nme="weight",
-    factor_nmes=["feat1", "feat2", "feat3"],
-    task_type="regression",
-    epochs=100,
-    use_gpu=True,
-    use_resn_ddp=True,
-    output_dir="./models",
-    optuna_storage="sqlite:///optuna.db",
-    cv_strategy="stratified",
-    cv_splits=5,
-    final_ensemble=True,
-    final_ensemble_k=3,
-    # ... 40+ more parameters
-)
-```
-
-**After (New API - Single Config Object)**:
-```python
-config = BayesOptConfig(
-    model_nme="my_model",
-    resp_nme="target",
-    weight_nme="weight",
-    factor_nmes=["feat1", "feat2", "feat3"],
-    task_type="regression",
-    epochs=100,
-    use_gpu=True,
-    use_resn_ddp=True,
-    output_dir="./models",
-    optuna_storage="sqlite:///optuna.db",
-    cv_strategy="stratified",
-    cv_splits=5,
-    final_ensemble=True,
-    final_ensemble_k=3,
-    # All other parameters with sensible defaults
-)
-
-model = BayesOptModel(train_data, test_data, config=config)
-```
-
-### 2. Benefits of New API
-
-1. **Cleaner Code**: Configuration is separated from model instantiation
-2. **Reusability**: Config objects can be saved, loaded, and reused
-3. **IDE Support**: Better auto-completion and type hints
-4. **Validation**: Config validation happens at construction time
-5. **Serialization**: Easy to serialize/deserialize configurations
-6. **Testing**: Easier to mock and test with config objects
-
-### 3. Backward Compatibility
-
-The old API **continues to work** but shows a deprecation warning:
-
-```
-DeprecationWarning: Passing individual parameters to BayesOptModel.__init__
-is deprecated. Use the 'config' parameter with a BayesOptConfig instance instead:
-  config = BayesOptConfig(model_nme=..., resp_nme=..., ...)
-  model = BayesOptModel(train_data, test_data, config=config)
-Individual parameters will be removed in v0.4.0.
-```
-
----
-
-## Migration Guide
-
-### Step 1: Identify Current Usage
-
-Search your codebase for:
-```python
-BayesOptModel(train_data, test_data, model_nme=..., resp_nme=..., ...)
-```
-
-### Step 2: Convert to New API
-
-**Option A: Direct Conversion** (Recommended)
-```python
-# Before
-model = BayesOptModel(
-    train_data, test_data,
-    model_nme="model1",
-    resp_nme="target",
-    weight_nme="weight",
-    factor_nmes=features,
-    epochs=50,
-    use_gpu=True
-)
-
-# After
-config = BayesOptConfig(
-    model_nme="model1",
-    resp_nme="target",
-    weight_nme="weight",
-    factor_nmes=features,
-    epochs=50,
-    use_gpu=True
-)
-model = BayesOptModel(train_data, test_data, config=config)
-```
-
-**Option B: Load from File**
-```python
-# Load config from JSON/CSV/TSV
-config = BayesOptConfig.from_file("config.json")
-model = BayesOptModel(train_data, test_data, config=config)
-```
-
-**Option C: Modify Existing Config**
-```python
-# Start with defaults, override specific values
-config = BayesOptConfig(
-    model_nme="model1",
-    resp_nme="target",
-    weight_nme="weight",
-    factor_nmes=features
-)
-
-# Modify for specific experiment
-config.epochs = 100
-config.use_resn_ddp = True
-config.final_ensemble = True
-
-model = BayesOptModel(train_data, test_data, config=config)
-```
-
-### Step 3: Test
-
-Run your code and verify:
-1. ✓ No errors during model creation
-2. ✓ Same behavior as before
-3. ✓ Deprecation warning appears (if using old API)
-
----
-
-## Technical Implementation Details
-
-### File Modified
-
-- **[core.py:50-292](ins_pricing/modelling/core/bayesopt/core.py#L50-L292)**: `BayesOptModel.__init__` method
-
-### Changes Made
-
-1. **New Parameter**: Added `config: Optional[BayesOptConfig] = None` as first parameter
-2. **Required Parameters**: Made `model_nme`, `resp_nme`, `weight_nme` optional (None by default)
-3. **Detection Logic**: Added if/else to detect which API is being used:
-   - If `config` is provided → use it directly
-   - If `config` is None → construct from individual parameters (old API)
-4. **Validation**: Added type checking for config parameter
-5. **Deprecation Warning**: Added warning when old API is used
-6. **Error Messages**: Added helpful error messages for missing required params
-7. **Documentation**: Updated docstring with examples of both APIs
-
-### Code Structure
-
-```python
-def __init__(self, train_data, test_data,
-             config: Optional[BayesOptConfig] = None,
-             # All 56 individual parameters with defaults
-             model_nme=None, resp_nme=None, ...):
-    """Docstring with examples."""
-
-    if config is not None:
-        # New API path
-        if isinstance(config, BayesOptConfig):
-            cfg = config
-        else:
-            raise TypeError("config must be BayesOptConfig")
-    else:
-        # Old API path (backward compatibility)
-        warnings.warn("Individual parameters deprecated...", DeprecationWarning)
-
-        # Validate required params
-        if model_nme is None:
-            raise ValueError("model_nme required")
-        # ... validate other required params
-
-        # Infer categorical features
-        inferred_factors, inferred_cats = infer_factor_and_cate_list(...)
-
-        # Construct config from individual params
-        cfg = BayesOptConfig(
-            model_nme=model_nme,
-            resp_nme=resp_nme,
-            # ... all 56 parameters
-        )
-
-    # Rest of initialization (unchanged)
-    self.config = cfg
-    self.model_nme = cfg.model_nme
-    # ...
-```
-
----
-
-## Testing
-
-### Automated Tests
-
-Created [test_bayesopt_api.py](test_bayesopt_api.py) with 5 test scenarios:
-
-1. ✅ **New API**: Config-based instantiation (no warnings)
-2. ✅ **Old API**: Individual parameters (shows deprecation warning)
-3. ✅ **Equivalence**: Both APIs produce identical results
-4. ✅ **Error Handling**: Missing required params raise ValueError
-5. ✅ **Type Validation**: Invalid config type raises TypeError
-
-### Manual Verification
-
-Run syntax validation:
-```bash
-python -m py_compile ins_pricing/modelling/core/bayesopt/core.py
-```
-Result: ✅ No syntax errors
-
----
-
-## Impact Analysis
-
-### Files Affected
-
-**Direct Changes**:
-- `ins_pricing/modelling/core/bayesopt/core.py` - Modified `BayesOptModel.__init__`
-
-**No Changes Required** (backward compatible):
-- All trainer classes (GLMTrainer, XGBTrainer, ResNetTrainer, FTTrainer, GNNTrainer)
-- All model classes (GraphNeuralNetSklearn, etc.)
-- All existing user code and scripts
-
-### Breaking Changes
-
-**None**. This refactoring is 100% backward compatible.
-
-- Old code continues to work (with deprecation warning)
-- Deprecation warnings can be suppressed if needed
-- Removal planned for v0.4.0 (future major version)
-
----
-
-## Metrics
-
-### Code Simplification
-
-| Metric | Before | After | Change |
-|--------|--------|-------|--------|
-| Required positional params | 58 | 3 | -95% |
-| Function signature length | 56 lines | 61 lines | +9% (temp for compat) |
-| User code complexity | High | Low | Significantly improved |
-| Type safety | Weak | Strong | Config is type-checked |
-| Reusability | None | High | Config objects reusable |
-
-### Future Cleanup (v0.4.0)
-
-When old API is removed:
-- Function signature: 61 lines → 5 lines (-92%)
-- Complexity: Removed 100+ lines of parameter-to-config mapping
-- Maintenance: Single source of truth (BayesOptConfig)
-
----
-
-## Examples
-
-### Example 1: Basic Usage
-
-```python
-from ins_pricing.modelling.core.bayesopt import BayesOptModel, BayesOptConfig
-import pandas as pd
-
-# Load data
-train_df = pd.read_csv("train.csv")
-test_df = pd.read_csv("test.csv")
-
-# Create configuration
-config = BayesOptConfig(
-    model_nme="insurance_pricing",
-    resp_nme="premium",
-    weight_nme="exposure",
-    factor_nmes=["age", "vehicle_type", "region"],
-    task_type="regression"
-)
-
-# Create model
-model = BayesOptModel(train_df, test_df, config=config)
-
-# Tune and train
-model.tune(n_trials=100)
-results = model.train()
-```
-
-### Example 2: Reusing Configuration
-
-```python
-# Base configuration for all experiments
-base_config = BayesOptConfig(
-    model_nme="experiment",
-    resp_nme="target",
-    weight_nme="weight",
-    factor_nmes=feature_list,
-    task_type="regression",
-    epochs=50,
-    use_gpu=True
-)
-
-# Experiment 1: Default settings
-model1 = BayesOptModel(train_df, test_df, config=base_config)
-
-# Experiment 2: Enable DDP for ResNet
-config2 = BayesOptConfig(**asdict(base_config))
-config2.use_resn_ddp = True
-model2 = BayesOptModel(train_df, test_df, config=config2)
-
-# Experiment 3: Enable ensemble
-config3 = BayesOptConfig(**asdict(base_config))
-config3.final_ensemble = True
-config3.final_ensemble_k = 5
-model3 = BayesOptModel(train_df, test_df, config=config3)
-```
-
-### Example 3: Loading from File
-
-```python
-# config.json
-{
-    "model_nme": "production_model",
-    "resp_nme": "claim_amount",
-    "weight_nme": "exposure",
-    "factor_nmes": ["age", "gender", "vehicle_age"],
-    "task_type": "regression",
-    "epochs": 100,
-    "use_gpu": true,
-    "cv_strategy": "stratified",
-    "cv_splits": 5,
-    "final_ensemble": true
-}
-
-# Python code
-config = BayesOptConfig.from_file("config.json")
-model = BayesOptModel(train_df, test_df, config=config)
-```
-
----
-
-## Rollback Plan
-
-If issues arise:
-
-1. **Code is backward compatible** - no changes needed to existing code
-2. **Old API still works** - can continue using individual parameters
-3. **Deprecation warnings can be suppressed**:
-   ```python
-   import warnings
-   warnings.filterwarnings("ignore", category=DeprecationWarning)
-   ```
-
-4. **Revert changes** (if absolutely necessary):
-   ```bash
-   git revert <commit_hash>
-   ```
-
----
-
-## Future Work
-
-### v0.3.x (Current)
-- ✅ Both APIs supported
-- ✅ Deprecation warnings shown
-- ✅ Documentation complete
-
-### v0.4.0 (Future Major Release)
-- 🔄 Remove old API entirely
-- 🔄 Clean up function signature
-- 🔄 Remove parameter-to-config mapping code
-- 🔄 Update all examples and documentation
-
----
-
-## Success Criteria
-
-- ✅ **Functionality**: Both APIs produce identical results
-- ✅ **Compatibility**: All existing code works without changes
-- ✅ **Warnings**: Deprecation warnings guide users to new API
-- ✅ **Documentation**: Clear migration guide and examples
-- ✅ **Type Safety**: Config parameter validated at runtime
-- ✅ **Testing**: Comprehensive test coverage
-- ✅ **Syntax**: No Python syntax errors
-- ✅ **Code Quality**: Clean, maintainable implementation
-
----
-
-## Related Documentation
-
-- [Phase 1 Refactoring: Utils Module Split](REFACTORING_SUMMARY.md)
-- [BayesOptConfig Reference](config_preprocess.py)
-- [Migration Examples](test_bayesopt_api.py)
-- [Original Refactoring Plan](~/.claude/plans/linked-percolating-sketch.md)
-
----
-
-## Changelog Entry
-
-### v0.2.10 (Upcoming)
-
-**Added**:
-- New config-based API for BayesOptModel initialization
-- BayesOptModel now accepts `config` parameter with BayesOptConfig instance
-
-**Deprecated**:
-- Individual parameter passing to BayesOptModel.__init__ (use config instead)
-- Old API will be removed in v0.4.0
-
-**Migration**:
-```python
-# Old (deprecated but still works)
-model = BayesOptModel(train_df, test_df, model_nme="...", resp_nme="...", ...)
-
-# New (recommended)
-config = BayesOptConfig(model_nme="...", resp_nme="...", ...)
-model = BayesOptModel(train_df, test_df, config=config)
-```
-
----
-
-**End of Phase 2 Refactoring Summary**