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

ins_pricing/README.md

@@ -1,74 +1,92 @@
-# Ins-Pricing
-
-Distribution name: Ins-Pricing (import package is `ins_pricing`, legacy alias `user_packages` still works).
-
-Reusable modelling and pricing utilities organized as a small toolbox with clear boundaries
-between modelling, production, governance, and reporting.
-
-## Architecture
-
-- `cli/`: CLI entry points + shared utilities.
+# ins_pricing
+
+Distribution name: ins_pricing (import package is `ins_pricing`; legacy alias `user_packages` still works).
+
+Reusable modelling and pricing utilities organized as a small toolbox with clear boundaries
+between modelling, production, governance, and reporting.
+
+## Architecture
+
+- `cli/`: CLI entry points and shared utilities.
 - `modelling/`
-  - `core/`: BayesOpt training core (GLM / XGB / ResNet / FT / GNN).
+  - `bayesopt/`: BayesOpt training core (GLM / XGB / ResNet / FT / GNN).
   - `plotting/`: model-agnostic curves and geo visualizations.
   - `explain/`: permutation, gradients, and SHAP helpers.
-- `docs/modelling/`: modelling documentation.
-- `examples/modelling/`: demo configs + notebooks (repo only; not packaged).
-- `pricing/`: factor tables, calibration, exposure, monitoring.
-- `production/`: scoring, metrics, drift/PSI.
-- `governance/`: registry, release, audit, approval workflow.
-- `reporting/`: report builder + scheduler.
-
-## Call flow (typical)
-
-1. Model training
-   - Python API: `from ins_pricing.modelling import BayesOptModel`
-   - CLI: `python ins_pricing/cli/BayesOpt_entry.py --config-json ...`
-2. Evaluation & visualization
-   - Curves: `from ins_pricing.plotting import curves`
-   - Importance: `from ins_pricing.plotting import importance`
-   - Geo: `from ins_pricing.plotting import geo`
-3. Explainability
-   - `from ins_pricing.explain import permutation_importance, integrated_gradients_torch`
-4. Pricing loop
-   - `from ins_pricing.pricing import build_factor_table, rate_premium`
-5. Production & governance
+  - `evaluation.py`: calibration, metrics, and evaluation utilities.
+- `examples/`: demo configs and notebooks (repo only; not packaged).
+- `pricing/`: factor tables, calibration, exposure, monitoring.
+- `production/`: scoring, metrics, drift/PSI.
+- `governance/`: registry, approval, audit workflows.
+- `reporting/`: report builder and scheduler.
+
+## Call flow (typical)
+
+1. Model training
+   - Python API: `from ins_pricing.modelling import BayesOptModel`
+   - CLI: `python ins_pricing/cli/BayesOpt_entry.py --config-json ...`
+2. Evaluation and visualization
+   - Curves: `from ins_pricing.plotting import curves`
+   - Importance: `from ins_pricing.plotting import importance`
+   - Geo: `from ins_pricing.plotting import geo`
+3. Explainability
+   - `from ins_pricing.explain import permutation_importance, integrated_gradients_torch`
+4. Pricing loop
+   - `from ins_pricing.pricing import build_factor_table, rate_premium`
+5. Production and governance
    - `from ins_pricing.production import batch_score, psi_report`
+   - Inference: `from ins_pricing.production import load_predictor_from_config`
    - `from ins_pricing.governance import ModelRegistry, ReleaseManager`
-6. Reporting
-   - `from ins_pricing.reporting import build_report, write_report, schedule_daily`
-
+6. Reporting
+   - `from ins_pricing.reporting import build_report, write_report, schedule_daily`
+
 ## Import notes
 
-- `ins_pricing` exposes lightweight lazy imports so that `pricing/production/governance`
+- `ins_pricing` exposes lightweight lazy imports so that pricing/production/governance
   can be used without installing heavy ML dependencies.
-- Migration note: CLI entry points now live under `ins_pricing/cli/` and demo assets are under
-  `ins_pricing/examples/modelling/`. Update any scripts that referenced `ins_pricing/modelling/cli/*` or
-  `ins_pricing/modelling/examples/*`.
-- Demo notebooks/configs live in the repo under `ins_pricing/examples/modelling/` and are not shipped in the PyPI package.
+- Demo notebooks/configs live in the repo under `examples/` and are not shipped
+  in the PyPI package.
 - Heavy dependencies are only required when you import or use the related modules:
   - BayesOpt: `torch`, `optuna`, `xgboost`, etc.
   - Explain: `torch` (gradients), `shap` (SHAP).
   - Geo plotting on basemap: `contextily`.
   - Plotting: `matplotlib`.
+  - Inference: `torch` only when loading FT/ResNet/GNN models.
 
-## Multi-platform & GPU installation notes
+## Inference interface (new)
 
-- **Install PyTorch first**: Use the correct PyTorch build for your platform/GPU (CUDA/ROCm/MPS)
-  before installing the `bayesopt`, `explain`, or `gnn` extras. This avoids incompatible wheels.
-- **GNN dependencies**: `torch-geometric` and its companion packages are platform-specific. Follow
-  the official PyG install guide for your CUDA/ROCm/CPU environment, then install
-  `ins_pricing[gnn]`.
-- **Multi-GPU**: Training utilities will select CUDA/MPS/CPU automatically. Multi-GPU uses DDP or
-  DataParallel when supported; on Windows, CUDA DDP is disabled and will fall back to single-GPU or
-  DataParallel where available.
+- `production.inference` provides a small registry-based interface so inference
+  does not hard-code model loaders:
+  - `ModelSpec` describes the saved model location and config.
+  - `PredictorRegistry` lets you plug in custom model loaders.
+  - `load_predictor_from_config` remains backward compatible.
 
-## Backward-compatible imports
+Example:
 
-Legacy import paths continue to work:
+```
+from ins_pricing.production import load_predictor_from_config
 
-- `import user_packages`
-- `import user_packages.bayesopt`
-- `import user_packages.plotting`
-- `import user_packages.explain`
-- `import user_packages.BayesOpt`
+predictor = load_predictor_from_config(
+    "config.json",
+    "resn",
+    device="cuda",  # or "mps"/"cpu"
+)
+preds = predictor.predict(df)
+```
+
+## Multi-platform and GPU notes
+
+- Install the correct PyTorch build for your platform/GPU before installing extras.
+- Torch Geometric requires platform-specific wheels; follow the official PyG install guide.
+- Multi-GPU uses DDP or DataParallel where supported; Windows disables CUDA DDP.
+  CLI usage prefers `python -m ins_pricing.cli.BayesOpt_entry ...` but the
+  direct script path (`python ins_pricing/cli/BayesOpt_entry.py ...`) still works.
+
+## Backward-compatible imports
+
+Legacy import paths continue to work:
+
+- `import user_packages`
+- `import user_packages.bayesopt`
+- `import user_packages.plotting`
+- `import user_packages.explain`
+- `import user_packages.BayesOpt`

ins_pricing/__init__.py

@@ -1,94 +1,146 @@
-from __future__ import annotations
-
-from importlib import import_module
-from pathlib import Path
-import sys
-import types
-
-_ROOT_SUBPACKAGES = {
-    "modelling": "ins_pricing.modelling",
-    "pricing": "ins_pricing.pricing",
-    "production": "ins_pricing.production",
-    "governance": "ins_pricing.governance",
-    "reporting": "ins_pricing.reporting",
-}
-
-_MODELLING_EXPORTS = {
-    "BayesOptConfig",
-    "BayesOptModel",
-    "IOUtils",
-    "TrainingUtils",
-    "free_cuda",
-}
-
+from __future__ import annotations
+
+from importlib import import_module
+from pathlib import Path
+import sys
+import types
+
+_ROOT_SUBPACKAGES = {
+    "modelling": "ins_pricing.modelling",
+    "pricing": "ins_pricing.pricing",
+    "production": "ins_pricing.production",
+    "governance": "ins_pricing.governance",
+    "reporting": "ins_pricing.reporting",
+}
+
+_MODELLING_EXPORTS = {
+    "BayesOptConfig",
+    "BayesOptModel",
+}
+
+_BAYESOPT_EXPORTS = {
+    "BayesOptConfig",
+    "DatasetPreprocessor",
+    "OutputManager",
+    "VersionManager",
+    "BayesOptModel",
+    "FeatureTokenizer",
+    "FTTransformerCore",
+    "FTTransformerSklearn",
+    "GraphNeuralNetSklearn",
+    "MaskedTabularDataset",
+    "ResBlock",
+    "ResNetSequential",
+    "ResNetSklearn",
+    "ScaledTransformerEncoderLayer",
+    "SimpleGraphLayer",
+    "SimpleGNN",
+    "TabularDataset",
+    "FTTrainer",
+    "GLMTrainer",
+    "GNNTrainer",
+    "ResNetTrainer",
+    "TrainerBase",
+    "XGBTrainer",
+    "_xgb_cuda_available",
+}
+
+_LEGACY_EXPORTS = {
+    "IOUtils": "ins_pricing.utils",
+    "DeviceManager": "ins_pricing.utils",
+    "GPUMemoryManager": "ins_pricing.utils",
+    "MetricFactory": "ins_pricing.utils",
+    "EPS": "ins_pricing.utils",
+    "set_global_seed": "ins_pricing.utils",
+    "compute_batch_size": "ins_pricing.utils",
+    "tweedie_loss": "ins_pricing.utils",
+    "infer_factor_and_cate_list": "ins_pricing.utils",
+    "DistributedUtils": "ins_pricing.modelling.bayesopt.utils",
+    "TrainingUtils": "ins_pricing.modelling.bayesopt.utils",
+    "free_cuda": "ins_pricing.modelling.bayesopt.utils",
+    "TorchTrainerMixin": "ins_pricing.modelling.bayesopt.utils",
+}
+
 _LAZY_SUBMODULES = {
-    "bayesopt": "ins_pricing.modelling.core.bayesopt",
+    "bayesopt": "ins_pricing.modelling.bayesopt",
     "plotting": "ins_pricing.modelling.plotting",
     "explain": "ins_pricing.modelling.explain",
-    "BayesOpt": "ins_pricing.modelling.core.BayesOpt",
-}
-
-_PACKAGE_PATHS = {
-    "bayesopt": Path(__file__).resolve().parent / "modelling" / "core" / "bayesopt",
-    "plotting": Path(__file__).resolve().parent / "modelling" / "plotting",
-    "explain": Path(__file__).resolve().parent / "modelling" / "explain",
 }
-
-__all__ = sorted(
-    set(_ROOT_SUBPACKAGES)
-    | set(_MODELLING_EXPORTS)
-    | set(_LAZY_SUBMODULES)
-)
-
-
-def _lazy_module(name: str, target: str, package_path: Path | None = None) -> types.ModuleType:
-    proxy = types.ModuleType(name)
-    if package_path is not None:
-        proxy.__path__ = [str(package_path)]
-
-    def _load():
-        module = import_module(target)
-        sys.modules[name] = module
-        return module
-
-    def __getattr__(attr: str):
-        module = _load()
-        return getattr(module, attr)
-
-    def __dir__() -> list[str]:
-        module = _load()
-        return sorted(set(dir(module)))
-
-    proxy.__getattr__ = __getattr__  # type: ignore[attr-defined]
-    proxy.__dir__ = __dir__  # type: ignore[attr-defined]
-    return proxy
-
-
-def _install_proxy(alias: str, target: str) -> None:
-    module_name = f"{__name__}.{alias}"
-    if module_name in sys.modules:
-        return
-    proxy = _lazy_module(module_name, target, _PACKAGE_PATHS.get(alias))
-    sys.modules[module_name] = proxy
-    globals()[alias] = proxy
-
-
-for _alias, _target in _LAZY_SUBMODULES.items():
-    _install_proxy(_alias, _target)
-
-
-def __getattr__(name: str):
-    if name in _ROOT_SUBPACKAGES:
-        module = import_module(_ROOT_SUBPACKAGES[name])
-        globals()[name] = module
-        return module
-    if name in _MODELLING_EXPORTS:
-        module = import_module("ins_pricing.modelling")
-        value = getattr(module, name)
-        globals()[name] = value
-        return value
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-
-
-def __dir__() -> list[str]:
-    return sorted(set(__all__) | set(globals().keys()))
+
+_PACKAGE_PATHS = {
+    "bayesopt": Path(__file__).resolve().parent / "modelling" / "bayesopt",
+    "plotting": Path(__file__).resolve().parent / "modelling" / "plotting",
+    "explain": Path(__file__).resolve().parent / "modelling" / "explain",
+}
+
+__all__ = sorted(
+    set(_ROOT_SUBPACKAGES)
+    | set(_MODELLING_EXPORTS)
+    | set(_BAYESOPT_EXPORTS)
+    | set(_LEGACY_EXPORTS)
+    | set(_LAZY_SUBMODULES)
+)
+
+
+def _lazy_module(name: str, target: str, package_path: Path | None = None) -> types.ModuleType:
+    proxy = types.ModuleType(name)
+    if package_path is not None:
+        proxy.__path__ = [str(package_path)]
+
+    def _load():
+        module = import_module(target)
+        sys.modules[name] = module
+        return module
+
+    def __getattr__(attr: str):
+        module = _load()
+        return getattr(module, attr)
+
+    def __dir__() -> list[str]:
+        module = _load()
+        return sorted(set(dir(module)))
+
+    proxy.__getattr__ = __getattr__  # type: ignore[attr-defined]
+    proxy.__dir__ = __dir__  # type: ignore[attr-defined]
+    return proxy
+
+
+def _install_proxy(alias: str, target: str) -> None:
+    module_name = f"{__name__}.{alias}"
+    if module_name in sys.modules:
+        return
+    proxy = _lazy_module(module_name, target, _PACKAGE_PATHS.get(alias))
+    sys.modules[module_name] = proxy
+    globals()[alias] = proxy
+
+
+for _alias, _target in _LAZY_SUBMODULES.items():
+    _install_proxy(_alias, _target)
+
+
+def __getattr__(name: str):
+    if name in _ROOT_SUBPACKAGES:
+        module = import_module(_ROOT_SUBPACKAGES[name])
+        globals()[name] = module
+        return module
+    if name in _MODELLING_EXPORTS:
+        module = import_module("ins_pricing.modelling")
+        value = getattr(module, name)
+        globals()[name] = value
+        return value
+    if name in _BAYESOPT_EXPORTS:
+        module = import_module("ins_pricing.modelling.bayesopt")
+        value = getattr(module, name)
+        globals()[name] = value
+        return value
+    legacy_module = _LEGACY_EXPORTS.get(name)
+    if legacy_module:
+        module = import_module(legacy_module)
+        value = getattr(module, name)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(set(__all__) | set(globals().keys()))

ins_pricing/cli/BayesOpt_entry.py

@@ -1,56 +1,58 @@
-"""Thin wrapper for the BayesOpt CLI entry point.
-
-The main implementation lives in bayesopt_entry_runner.py.
-"""
-
-from __future__ import annotations
-
+"""Thin wrapper for the BayesOpt CLI entry point.
+
+The main implementation lives in bayesopt_entry_runner.py.
+"""
+
+from __future__ import annotations
+
 from pathlib import Path
+import importlib.util
 import json
 import os
 import sys
 
 if __package__ in {None, ""}:
-    repo_root = Path(__file__).resolve().parents[2]
-    if str(repo_root) not in sys.path:
-        sys.path.insert(0, str(repo_root))
-
-def _apply_env_from_config(argv: list[str]) -> None:
-    if "--config-json" not in argv:
-        return
-    idx = argv.index("--config-json")
-    if idx + 1 >= len(argv):
-        return
-    raw_path = argv[idx + 1]
-    try:
-        cfg_path = Path(raw_path).expanduser()
-        if not cfg_path.is_absolute():
-            cfg_path = cfg_path.resolve()
-        if not cfg_path.exists():
-            script_dir = Path(__file__).resolve().parents[1]
-            candidate = (script_dir / raw_path).resolve()
-            if candidate.exists():
-                cfg_path = candidate
-        if not cfg_path.exists():
-            return
-        cfg = json.loads(cfg_path.read_text(encoding="utf-8", errors="replace"))
-        env = cfg.get("env", {})
-        if isinstance(env, dict):
-            for key, value in env.items():
-                if key is None:
-                    continue
-                os.environ.setdefault(str(key), str(value))
-    except Exception:
-        return
-
-_apply_env_from_config(sys.argv)
-
-try:
-    from .bayesopt_entry_runner import main
-except Exception:  # pragma: no cover
-    from ins_pricing.cli.bayesopt_entry_runner import main
-
-__all__ = ["main"]
-
-if __name__ == "__main__":
-    main()
+    if importlib.util.find_spec("ins_pricing") is None:
+        repo_root = Path(__file__).resolve().parents[2]
+        if str(repo_root) not in sys.path:
+            sys.path.insert(0, str(repo_root))
+
+def _apply_env_from_config(argv: list[str]) -> None:
+    if "--config-json" not in argv:
+        return
+    idx = argv.index("--config-json")
+    if idx + 1 >= len(argv):
+        return
+    raw_path = argv[idx + 1]
+    try:
+        cfg_path = Path(raw_path).expanduser()
+        if not cfg_path.is_absolute():
+            cfg_path = cfg_path.resolve()
+        if not cfg_path.exists():
+            script_dir = Path(__file__).resolve().parents[1]
+            candidate = (script_dir / raw_path).resolve()
+            if candidate.exists():
+                cfg_path = candidate
+        if not cfg_path.exists():
+            return
+        cfg = json.loads(cfg_path.read_text(encoding="utf-8", errors="replace"))
+        env = cfg.get("env", {})
+        if isinstance(env, dict):
+            for key, value in env.items():
+                if key is None:
+                    continue
+                os.environ.setdefault(str(key), str(value))
+    except Exception:
+        return
+
+_apply_env_from_config(sys.argv)
+
+try:
+    from ins_pricing.cli.bayesopt_entry_runner import main
+except Exception:  # pragma: no cover
+    from ins_pricing.cli.bayesopt_entry_runner import main
+
+__all__ = ["main"]
+
+if __name__ == "__main__":
+    main()