ins-pricing 0.1.6__py3-none-any.whl

ins_pricing/README.md

@@ -0,0 +1,60 @@
+# 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
+
+- `modelling/`
+  - `bayesopt/`: BayesOpt training core (GLM / XGB / ResNet / FT / GNN).
+  - `plotting/`: model-agnostic curves and geo visualizations.
+  - `explain/`: permutation, gradients, and SHAP helpers.
+  - `BayesOpt_entry.py`: CLI runner for batch training.
+  - `BayesOpt_incremental.py`: CLI for incremental runs.
+  - `Pricing_Run.py`: lightweight pricing orchestration.
+- `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/modelling/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
+   - `from ins_pricing.production import batch_score, psi_report`
+   - `from ins_pricing.governance import ModelRegistry, ReleaseManager`
+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`
+  can be used without installing heavy ML dependencies.
+- Demo notebooks/configs live in the repo under `ins_pricing/modelling/demo/` 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`.
+
+## 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

@@ -0,0 +1,102 @@
+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",
+}
+
+_LAZY_SUBMODULES = {
+    "bayesopt": "ins_pricing.modelling.bayesopt",
+    "plotting": "ins_pricing.modelling.plotting",
+    "explain": "ins_pricing.modelling.explain",
+    "BayesOpt": "ins_pricing.modelling.BayesOpt",
+    "BayesOpt_entry": "ins_pricing.modelling.BayesOpt_entry",
+    "BayesOpt_incremental": "ins_pricing.modelling.BayesOpt_incremental",
+    "Explain_entry": "ins_pricing.modelling.Explain_entry",
+    "Explain_Run": "ins_pricing.modelling.Explain_Run",
+    "Pricing_Run": "ins_pricing.modelling.Pricing_Run",
+    "cli_common": "ins_pricing.modelling.cli_common",
+    "notebook_utils": "ins_pricing.modelling.notebook_utils",
+    "watchdog_run": "ins_pricing.modelling.watchdog_run",
+}
+
+_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(_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()))

ins_pricing/governance/README.md

@@ -0,0 +1,18 @@
+# governance
+
+Lightweight model registry, approval, audit log, and release management.
+
+Example (deploy + rollback):
+
+```python
+from ins_pricing.governance import ModelRegistry, ReleaseManager
+
+registry = ModelRegistry("Registry/models.json")
+release = ReleaseManager("Registry/deployments", registry=registry)
+
+registry.register("pricing_ft", "v1", metrics={"rmse": 0.12})
+release.deploy("prod", "pricing_ft", "v1", actor="ops")
+
+# rollback to previous active version
+release.rollback("prod", actor="ops")
+```

ins_pricing/governance/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from .approval import ApprovalAction, ApprovalRequest, ApprovalStore
+from .audit import AuditEvent, AuditLogger
+from .registry import ModelArtifact, ModelRegistry, ModelVersion
+from .release import DeploymentState, ModelRef, ReleaseManager
+
+__all__ = [
+    "ApprovalAction",
+    "ApprovalRequest",
+    "ApprovalStore",
+    "AuditEvent",
+    "AuditLogger",
+    "ModelArtifact",
+    "ModelRegistry",
+    "ModelVersion",
+    "DeploymentState",
+    "ModelRef",
+    "ReleaseManager",
+]

ins_pricing/governance/approval.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+
+@dataclass
+class ApprovalAction:
+    actor: str
+    decision: str
+    timestamp: str
+    comment: Optional[str] = None
+
+
+@dataclass
+class ApprovalRequest:
+    model_name: str
+    model_version: str
+    requested_by: str
+    requested_at: str
+    status: str = "pending"
+    actions: List[ApprovalAction] = field(default_factory=list)
+
+
+class ApprovalStore:
+    """Simple approval workflow stored as JSON."""
+
+    def __init__(self, store_path: str | Path):
+        self.store_path = Path(store_path)
+        self.store_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def _load(self) -> List[dict]:
+        if not self.store_path.exists():
+            return []
+        with self.store_path.open("r", encoding="utf-8") as fh:
+            return json.load(fh)
+
+    def _save(self, payload: List[dict]) -> None:
+        with self.store_path.open("w", encoding="utf-8") as fh:
+            json.dump(payload, fh, indent=2, ensure_ascii=True)
+
+    def request(self, model_name: str, model_version: str, requested_by: str) -> ApprovalRequest:
+        payload = self._load()
+        req = ApprovalRequest(
+            model_name=model_name,
+            model_version=model_version,
+            requested_by=requested_by,
+            requested_at=datetime.utcnow().isoformat(),
+        )
+        payload.append(asdict(req))
+        self._save(payload)
+        return req
+
+    def list_requests(self, model_name: Optional[str] = None) -> List[ApprovalRequest]:
+        payload = self._load()
+        requests = [ApprovalRequest(**entry) for entry in payload]
+        if model_name is None:
+            return requests
+        return [req for req in requests if req.model_name == model_name]
+
+    def act(
+        self,
+        model_name: str,
+        model_version: str,
+        *,
+        actor: str,
+        decision: str,
+        comment: Optional[str] = None,
+    ) -> ApprovalRequest:
+        payload = self._load()
+        found = None
+        for entry in payload:
+            if entry["model_name"] == model_name and entry["model_version"] == model_version:
+                found = entry
+                break
+        if found is None:
+            raise ValueError("Approval request not found.")
+        action = ApprovalAction(
+            actor=actor,
+            decision=decision,
+            timestamp=datetime.utcnow().isoformat(),
+            comment=comment,
+        )
+        found["actions"].append(asdict(action))
+        if decision.lower() in {"approve", "approved"}:
+            found["status"] = "approved"
+        elif decision.lower() in {"reject", "rejected"}:
+            found["status"] = "rejected"
+        self._save(payload)
+        return ApprovalRequest(**found)

ins_pricing/governance/audit.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class AuditEvent:
+    action: str
+    actor: str
+    timestamp: str
+    metadata: Dict[str, Any]
+    note: Optional[str] = None
+
+
+class AuditLogger:
+    """Append-only JSONL audit log."""
+
+    def __init__(self, log_path: str | Path):
+        self.log_path = Path(log_path)
+        self.log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def log(self, action: str, actor: str, *, metadata: Optional[Dict[str, Any]] = None,
+            note: Optional[str] = None) -> AuditEvent:
+        event = AuditEvent(
+            action=action,
+            actor=actor,
+            timestamp=datetime.utcnow().isoformat(),
+            metadata=metadata or {},
+            note=note,
+        )
+        with self.log_path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(asdict(event), ensure_ascii=True) + "\n")
+        return event

ins_pricing/governance/registry.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+@dataclass
+class ModelArtifact:
+    path: str
+    description: Optional[str] = None
+
+
+@dataclass
+class ModelVersion:
+    name: str
+    version: str
+    created_at: str
+    metrics: Dict[str, float] = field(default_factory=dict)
+    tags: Dict[str, str] = field(default_factory=dict)
+    artifacts: List[ModelArtifact] = field(default_factory=list)
+    status: str = "candidate"
+    notes: Optional[str] = None
+
+
+class ModelRegistry:
+    """Lightweight JSON-based model registry."""
+
+    def __init__(self, registry_path: str | Path):
+        self.registry_path = Path(registry_path)
+        self.registry_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def _load(self) -> Dict[str, List[dict]]:
+        if not self.registry_path.exists():
+            return {}
+        with self.registry_path.open("r", encoding="utf-8") as fh:
+            return json.load(fh)
+
+    def _save(self, payload: Dict[str, List[dict]]) -> None:
+        with self.registry_path.open("w", encoding="utf-8") as fh:
+            json.dump(payload, fh, indent=2, ensure_ascii=True)
+
+    def register(
+        self,
+        name: str,
+        version: str,
+        *,
+        metrics: Optional[Dict[str, float]] = None,
+        tags: Optional[Dict[str, str]] = None,
+        artifacts: Optional[List[ModelArtifact]] = None,
+        status: str = "candidate",
+        notes: Optional[str] = None,
+    ) -> ModelVersion:
+        payload = self._load()
+        created_at = datetime.utcnow().isoformat()
+        entry = ModelVersion(
+            name=name,
+            version=version,
+            created_at=created_at,
+            metrics=metrics or {},
+            tags=tags or {},
+            artifacts=artifacts or [],
+            status=status,
+            notes=notes,
+        )
+        payload.setdefault(name, []).append(asdict(entry))
+        self._save(payload)
+        return entry
+
+    def list_versions(self, name: str) -> List[ModelVersion]:
+        payload = self._load()
+        versions = payload.get(name, [])
+        return [ModelVersion(**v) for v in versions]
+
+    def get_version(self, name: str, version: str) -> Optional[ModelVersion]:
+        for entry in self.list_versions(name):
+            if entry.version == version:
+                return entry
+        return None
+
+    def promote(
+        self, name: str, version: str, *, new_status: str = "production"
+    ) -> None:
+        payload = self._load()
+        if name not in payload:
+            raise ValueError("Model not found in registry.")
+        updated = False
+        for entry in payload[name]:
+            if entry["version"] == version:
+                entry["status"] = new_status
+                updated = True
+            elif new_status == "production":
+                if entry.get("status") == "production":
+                    entry["status"] = "archived"
+        if not updated:
+            raise ValueError("Version not found in registry.")
+        self._save(payload)

ins_pricing/governance/release.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+from .audit import AuditLogger
+from .registry import ModelRegistry
+
+
+@dataclass
+class ModelRef:
+    name: str
+    version: str
+    activated_at: str
+    actor: Optional[str] = None
+    note: Optional[str] = None
+
+
+@dataclass
+class DeploymentState:
+    env: str
+    active: Optional[ModelRef] = None
+    history: List[ModelRef] = field(default_factory=list)
+    updated_at: Optional[str] = None
+
+
+class ReleaseManager:
+    """Environment release manager with rollback support."""
+
+    def __init__(
+        self,
+        state_dir: str | Path,
+        *,
+        registry: Optional[ModelRegistry] = None,
+        audit_logger: Optional[AuditLogger] = None,
+    ):
+        self.state_dir = Path(state_dir)
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+        self.registry = registry
+        self.audit_logger = audit_logger
+
+    def _state_path(self, env: str) -> Path:
+        return self.state_dir / f"{env}.json"
+
+    def _load(self, env: str) -> DeploymentState:
+        path = self._state_path(env)
+        if not path.exists():
+            return DeploymentState(env=env)
+        with path.open("r", encoding="utf-8") as fh:
+            payload = json.load(fh)
+        active = payload.get("active")
+        history = payload.get("history", [])
+        return DeploymentState(
+            env=payload.get("env", env),
+            active=ModelRef(**active) if active else None,
+            history=[ModelRef(**item) for item in history],
+            updated_at=payload.get("updated_at"),
+        )
+
+    def _save(self, state: DeploymentState) -> None:
+        payload = {
+            "env": state.env,
+            "active": asdict(state.active) if state.active else None,
+            "history": [asdict(item) for item in state.history],
+            "updated_at": state.updated_at,
+        }
+        path = self._state_path(state.env)
+        with path.open("w", encoding="utf-8") as fh:
+            json.dump(payload, fh, indent=2, ensure_ascii=True)
+
+    def get_active(self, env: str) -> Optional[ModelRef]:
+        state = self._load(env)
+        return state.active
+
+    def list_history(self, env: str) -> List[ModelRef]:
+        return self._load(env).history
+
+    def deploy(
+        self,
+        env: str,
+        name: str,
+        version: str,
+        *,
+        actor: Optional[str] = None,
+        note: Optional[str] = None,
+        update_registry_status: bool = True,
+        registry_status: str = "production",
+    ) -> DeploymentState:
+        state = self._load(env)
+        if state.active and state.active.name == name and state.active.version == version:
+            return state
+
+        if state.active is not None:
+            state.history.append(state.active)
+
+        now = datetime.utcnow().isoformat()
+        state.active = ModelRef(
+            name=name,
+            version=version,
+            activated_at=now,
+            actor=actor,
+            note=note,
+        )
+        state.updated_at = now
+        self._save(state)
+
+        if self.registry and update_registry_status:
+            self.registry.promote(name, version, new_status=registry_status)
+
+        if self.audit_logger:
+            self.audit_logger.log(
+                "deploy",
+                actor or "unknown",
+                metadata={"env": env, "name": name, "version": version},
+                note=note,
+            )
+
+        return state
+
+    def rollback(
+        self,
+        env: str,
+        *,
+        actor: Optional[str] = None,
+        note: Optional[str] = None,
+        update_registry_status: bool = False,
+        registry_status: str = "production",
+    ) -> DeploymentState:
+        state = self._load(env)
+        if not state.history:
+            raise ValueError("No history available to rollback.")
+
+        previous = state.history.pop()
+        now = datetime.utcnow().isoformat()
+        state.active = ModelRef(
+            name=previous.name,
+            version=previous.version,
+            activated_at=now,
+            actor=actor or previous.actor,
+            note=note or previous.note,
+        )
+        state.updated_at = now
+        self._save(state)
+
+        if self.registry and update_registry_status:
+            self.registry.promote(previous.name, previous.version, new_status=registry_status)
+
+        if self.audit_logger:
+            self.audit_logger.log(
+                "rollback",
+                actor or "unknown",
+                metadata={"env": env, "name": previous.name, "version": previous.version},
+                note=note,
+            )
+
+        return state