ibnr 0.2.0__py3-none-any.whl

ibnr/__init__.py

@@ -0,0 +1,7 @@
+"""ibnr: gallery-centric probabilistic loss reserving on a long-format triangle layer."""
+
+from ibnr.triangle import Triangle, TriangleMeta
+
+__version__ = "0.1.0"
+
+__all__ = ["Triangle", "TriangleMeta", "__version__"]

ibnr/data/__init__.py

@@ -0,0 +1,3 @@
+from ibnr.data.schedule_p import load_schedule_p
+
+__all__ = ["load_schedule_p"]

ibnr/data/schedule_p.py

@@ -0,0 +1,297 @@
+"""Adapter for the CAS Schedule P gold mart (cas-schedule-p-data-model repo).
+
+The data pipeline lives in that repo; this package only consumes its published
+gold mart. The mart of record is ``mart_reserving_model_training``: long-format
+loss observations keyed by company x line_of_business x accident_year x
+development_age x statement_year. Schema (verified 2026-06-12 rebuild):
+
+    company_code, company_name, line_of_business, statement_year, accident_year,
+    development_age (years, 1-10), calendar_age, incurred_loss, cum_paid_loss,
+    bulk_loss, earned_prem_net, earned_prem_direct, case_reserve, loss_ratio,
+    paid_to_incurred_ratio, ata_factor_into_this_age, publish_id
+
+Note: the mart's ``incurred_loss`` is gross of bulk+IBNR and its
+``case_reserve`` is incurred - paid (so it also contains bulk). The adapter
+derives ``reported_loss`` = incurred_loss - bulk_loss (paid + true case),
+which is what Meyers' monograph calls "incurred".
+
+Two ways to point this adapter at data (either directly or via the
+IBNR_SCHEDULE_P_WAREHOUSE environment variable; when neither is given the
+default is ``DEFAULT_SOURCE`` — the newest GitHub release, ``@latest``
+resolved to its concrete publish_id up front):
+
+1. a local warehouse directory — parquet under ``warehouse/`` with the active
+   publish chosen by ``warehouse/_active_manifest.json`` (the sibling checkout
+   of cas-schedule-p-data-model);
+2. a GitHub release spec ``github://<owner>/<repo>@<publish_id>`` — the data
+   repo publishes each gold promote as a release tagged with its publish_id,
+   carrying every gold table plus a ``manifest.json`` (asset name, sha256,
+   bytes per table). Assets are downloaded once via the ``gh`` CLI (which
+   supplies auth for the private repo) into a local cache
+   (``~/.cache/ibnr`` or IBNR_CACHE_DIR), sha256-verified, then read locally.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import ibis
+
+from ibnr.triangle.core import Triangle
+from ibnr.triangle.io import from_long, resolve_backend
+
+ENV_VAR = "IBNR_SCHEDULE_P_WAREHOUSE"
+CACHE_ENV_VAR = "IBNR_CACHE_DIR"
+GITHUB_SCHEME = "github://"
+TRAINING_MART = "mart_reserving_model_training"
+
+#: where the data comes from when nothing else is specified: the newest gold
+#: publish on GitHub. ``@latest`` resolves to a concrete publish_id through gh
+#: before anything is cached or read, so results artifacts always stamp the
+#: exact publish even in default-configured dev.
+DEFAULT_SOURCE = "github://EKtheSage/cas-schedule-p-data-model@latest"
+LATEST = "latest"
+
+#: mart column -> triangle field name. Loss fields are cumulative; premiums,
+#: reserves and bulk are eval-date snapshots carried along as fields.
+DEFAULT_FIELDS = {
+    "cum_paid_loss": "paid_loss",
+    "incurred_loss": "incurred_loss",  # gross of bulk+IBNR
+    "bulk_loss": "bulk_loss",
+    "case_reserve": "case_reserve",
+    "earned_prem_net": "earned_premium",
+    "earned_prem_direct": "earned_premium_direct",
+}
+
+#: derived field: triangle field name -> ibis expression over the mart table
+DERIVED_FIELDS = {
+    # Meyers' "incurred": net of bulk+IBNR, i.e. paid + case reserves
+    "reported_loss": lambda t: t.incurred_loss - t.bulk_loss,
+}
+
+SEGMENTS = ["company_code", "company_name", "line_of_business"]
+
+
+def active_mart_path(warehouse: str | Path | None = None, mart: str = TRAINING_MART) -> Path:
+    """Resolve a mart's parquet path — from a local warehouse's active-publish
+    manifest, or from a cached (downloading if needed) GitHub release when
+    ``warehouse`` is a ``github://owner/repo@publish_id`` spec."""
+    source = _resolve_source(warehouse)
+    if _is_github_spec(source):
+        repo, tag = _parse_github_spec(str(source))
+        return _release_asset(repo, tag, mart)
+    warehouse = Path(source)
+    manifest = json.loads((warehouse / "_active_manifest.json").read_text())
+    rel = Path(manifest["tables"][mart])
+    # manifest paths are relative to the data-model repo root ("warehouse\...")
+    return warehouse.parent / rel
+
+
+def active_publish_id(warehouse: str | Path | None = None) -> str:
+    """The gold publish's version stamp — stamp this into every results
+    artifact so figures trace back to an exact data publish."""
+    source = _resolve_source(warehouse)
+    if _is_github_spec(source):
+        repo, tag = _parse_github_spec(str(source))
+        manifest, _ = _release_manifest(repo, tag)
+        return str(manifest["publish_id"])
+    warehouse = Path(source)
+    manifest = json.loads((warehouse / "_active_manifest.json").read_text())
+    return str(manifest["publish_id"])
+
+
+def _resolve_source(warehouse: str | Path | None) -> str | Path:
+    """Explicit argument > env var > the GitHub data repo's newest publish."""
+    if warehouse is None:
+        warehouse = os.environ.get(ENV_VAR) or DEFAULT_SOURCE
+    return warehouse
+
+
+def pinned_source(warehouse: str | Path | None = None, mart: str = TRAINING_MART) -> str:
+    """Resolve a warehouse argument to a CONCRETE, worker-safe source string.
+
+    For a GitHub spec, ``@latest`` is pinned to its publish_id and the mart
+    asset is downloaded into the cache up front. The parallel harness hands
+    THIS string to its workers, so they never re-resolve ``@latest`` (a race
+    against a release published mid-run would split the study across two data
+    versions) and never call gh concurrently — they only read the local cache.
+    Local warehouse paths pass through unchanged.
+    """
+    source = _resolve_source(warehouse)
+    if _is_github_spec(source):
+        repo, tag = _parse_github_spec(str(source))
+        _release_asset(repo, tag, mart)  # warm the cache before workers spawn
+        return f"{GITHUB_SCHEME}{repo}@{tag}"
+    return str(source)
+
+
+# -- GitHub release consumption ---------------------------------------------------
+#
+# The data repo publishes each gold promote as an immutable release tagged with
+# its publish_id; assets are the gold tables plus manifest.json. We download
+# through the gh CLI (it carries auth for the private repo), cache per
+# (repo, publish_id), and verify sha256 against the manifest.
+
+
+def _is_github_spec(source: str | Path) -> bool:
+    return isinstance(source, str) and source.startswith(GITHUB_SCHEME)
+
+
+def _parse_github_spec(spec: str) -> tuple[str, str]:
+    """``github://owner/repo@publish_id`` -> (``owner/repo``, ``publish_id``).
+
+    ``@latest`` is resolved to the repo's newest release tag (one gh call,
+    cached per process) so caching and provenance always see a concrete id.
+    """
+    body = spec[len(GITHUB_SCHEME) :]
+    repo, _, tag = body.partition("@")
+    if not tag or repo.count("/") != 1 or not all(repo.split("/")):
+        raise ValueError(
+            f"bad GitHub release spec {spec!r}; expected {GITHUB_SCHEME}owner/repo@publish_id"
+        )
+    if tag == LATEST:
+        tag = _latest_tag(repo)
+    return repo, tag
+
+
+_LATEST_TAGS: dict[str, str] = {}
+
+
+def _latest_tag(repo: str) -> str:
+    if repo not in _LATEST_TAGS:
+        if shutil.which("gh") is None:
+            raise RuntimeError(
+                f"resolving @{LATEST} for {repo} needs the GitHub CLI (gh); "
+                "install it and run `gh auth login`, or pin a publish_id"
+            )
+        result = subprocess.run(
+            ["gh", "release", "view", "--repo", repo, "--json", "tagName", "--jq", ".tagName"],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0 or not result.stdout.strip():
+            raise RuntimeError(
+                f"could not resolve the latest release of {repo}: "
+                f"{result.stderr.strip() or result.stdout.strip()}"
+            )
+        _LATEST_TAGS[repo] = result.stdout.strip()
+    return _LATEST_TAGS[repo]
+
+
+def _cache_dir(repo: str, tag: str) -> Path:
+    root = os.environ.get(CACHE_ENV_VAR)
+    root = Path(root) if root else Path.home() / ".cache" / "ibnr"
+    return root / repo.replace("/", "__") / tag
+
+
+def _gh_download(repo: str, tag: str, pattern: str, dest: Path) -> None:
+    if shutil.which("gh") is None:
+        raise RuntimeError(
+            "the GitHub CLI (gh) is required to fetch data releases from the "
+            f"private {repo} repo; install it and run `gh auth login`"
+        )
+    dest.mkdir(parents=True, exist_ok=True)
+    result = subprocess.run(
+        [
+            "gh",
+            "release",
+            "download",
+            tag,
+            "--repo",
+            repo,
+            "--pattern",
+            pattern,
+            "--dir",
+            str(dest),
+            "--clobber",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"gh release download failed for {repo}@{tag} ({pattern}): "
+            f"{result.stderr.strip() or result.stdout.strip()}"
+        )
+
+
+def _release_manifest(repo: str, tag: str) -> tuple[dict, Path]:
+    cache = _cache_dir(repo, tag)
+    path = cache / "manifest.json"
+    if not path.exists():
+        _gh_download(repo, tag, "manifest.json", cache)
+    manifest = json.loads(path.read_text())
+    if str(manifest["publish_id"]) != tag:
+        raise ValueError(
+            f"release {repo}@{tag} carries manifest for publish "
+            f"{manifest['publish_id']!r} — publishes are immutable, refusing to mix"
+        )
+    return manifest, cache
+
+
+def _release_asset(repo: str, tag: str, table: str) -> Path:
+    manifest, cache = _release_manifest(repo, tag)
+    try:
+        entry = manifest["tables"][table]
+    except KeyError:
+        raise KeyError(
+            f"release {repo}@{tag} has no table {table!r}; available: {sorted(manifest['tables'])}"
+        ) from None
+    path = cache / entry["asset"]
+    if not path.exists() or path.stat().st_size != int(entry["bytes"]):
+        _gh_download(repo, tag, entry["asset"], cache)
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        if digest != entry["sha256"]:
+            path.unlink(missing_ok=True)
+            raise RuntimeError(
+                f"sha256 mismatch for {entry['asset']} from {repo}@{tag}: "
+                f"got {digest}, manifest says {entry['sha256']}"
+            )
+    return path
+
+
+def load_schedule_p(
+    warehouse: str | Path | None = None,
+    *,
+    lines: list[str] | None = None,
+    companies: list[str] | None = None,
+    fields: dict[str, str] | None = None,
+    derived: dict | None = None,
+    backend: str | None = None,
+) -> Triangle:
+    """Load the reserving training mart as a Triangle.
+
+    Mapping: origin_period = Jan 1 of accident_year; dev_lag = development_age
+    in months; eval_date = Dec 31 of statement_year (annual statement date).
+    Values are USD thousands. ``lines``/``companies`` filter line_of_business /
+    company_code before materializing.
+    """
+    fields = fields or DEFAULT_FIELDS
+    derived = DERIVED_FIELDS if derived is None else derived
+    con = resolve_backend(backend)
+    t = con.read_parquet(str(active_mart_path(warehouse)))
+    if lines:
+        t = t.filter(t.line_of_business.isin(lines))
+    if companies:
+        t = t.filter(t.company_code.isin(companies))
+    t = t.select(
+        *SEGMENTS,
+        origin_period=ibis.date(t.accident_year, 1, 1),
+        dev_lag=(t.development_age * 12).cast("int64"),
+        eval_date=ibis.date(t.statement_year, 12, 31),
+        **{new: t[old] for old, new in fields.items()},
+        **{name: expr(t) for name, expr in derived.items()},
+    )
+    return from_long(
+        t,
+        fields=[*fields.values(), *derived],
+        measure="cumulative",
+        origin_grain="Y",
+        dev_grain="Y",
+        units="USD thousands",
+    )

ibnr/gallery/__init__.py

@@ -0,0 +1,29 @@
+"""The model gallery. Public API: list(), get(), fit()."""
+
+from __future__ import annotations
+
+import builtins
+
+from ibnr.gallery import registry as _registry
+
+# importing the subpackages self-registers their entries
+from ibnr.gallery import statistical as _statistical  # noqa: F401
+from ibnr.gallery.bayesian import clark_growth_curve as _clark_growth_curve  # noqa: F401
+from ibnr.gallery.bayesian import compartmental as _compartmental  # noqa: F401
+from ibnr.gallery.bayesian import england_verrall_odp as _england_verrall_odp  # noqa: F401
+from ibnr.gallery.bayesian import meyers_ccl as _meyers_ccl  # noqa: F401
+from ibnr.gallery.bayesian import meyers_csr as _meyers_csr  # noqa: F401
+from ibnr.gallery.entry import GalleryEntry
+from ibnr.gallery.nn import transformer as _nn_transformer  # noqa: F401
+from ibnr.gallery.nn import transformer_ml as _nn_transformer_ml  # noqa: F401
+
+get = _registry.get
+fit = _registry.fit
+
+
+def list() -> builtins.list[str]:  # noqa: A001 - mirrors the designed public API
+    """Names of all registered gallery entries."""
+    return sorted(_registry.entries())
+
+
+__all__ = ["GalleryEntry", "fit", "get", "list"]

ibnr/gallery/bayesian/_toolchain.py

@@ -0,0 +1,70 @@
+"""Windows C++ toolchain wiring shared by the Bayesian backends.
+
+Both cmdstan (via cmdstanpy) and PyMC (via PyTensor) need a C/C++ compiler on
+Windows. Modern RTools installs (43/44/45) ship a plain ``make`` and a g++ under
+``x86_64-w64-mingw32.static.posix``; these helpers put them on PATH so the
+backends can compile. No-ops on non-Windows or when a toolchain is already set.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+from pathlib import Path
+
+# RTools roots newest-first; each carries a posix g++ and a usr/bin make.
+_RTOOLS_ROOTS = ("C:/rtools45", "C:/rtools44", "C:/rtools43", "C:/rtools40")
+
+
+def _rtools_bindirs() -> tuple[Path, Path] | None:
+    for root in _RTOOLS_ROOTS:
+        gxx = Path(root) / "x86_64-w64-mingw32.static.posix" / "bin"
+        mk = Path(root) / "usr" / "bin"
+        if gxx.exists() and mk.exists():
+            return gxx, mk
+    return None
+
+
+def ensure_stan_toolchain() -> None:
+    """Best-effort: put an RTools g++/make on PATH so cmdstan can compile.
+
+    cmdstanpy assumes mingw32-make/RTools40; modern RTools ship plain ``make``,
+    so we also set ``MAKE``.
+    """
+    if platform.system() != "Windows":
+        return
+    if shutil.which("g++") and (shutil.which("mingw32-make") or shutil.which("make")):
+        os.environ.setdefault("MAKE", "mingw32-make" if shutil.which("mingw32-make") else "make")
+        return
+    dirs = _rtools_bindirs()
+    if dirs is not None:
+        gxx, mk = dirs
+        os.environ["PATH"] = f"{gxx};{mk};{os.environ['PATH']}"
+        os.environ.setdefault("MAKE", "make")
+
+
+def ensure_pytensor_cxx() -> str | None:
+    """Point PyTensor at an RTools g++ so it compiles C ops instead of falling
+    back to the (very slow) Python evaluation path.
+
+    Returns the g++ path configured, or None if nothing was needed/found.
+    Idempotent: a no-op once ``pytensor.config.cxx`` is already set.
+    """
+    if platform.system() != "Windows":
+        return None
+    import pytensor
+
+    if pytensor.config.cxx:
+        return pytensor.config.cxx
+    dirs = _rtools_bindirs()
+    if dirs is None:
+        return None
+    gxx, mk = dirs
+    gxx_exe = gxx / "g++.exe"
+    if not gxx_exe.exists():
+        return None
+    if str(gxx) not in os.environ["PATH"]:
+        os.environ["PATH"] = f"{gxx};{mk};{os.environ['PATH']}"
+    pytensor.config.cxx = str(gxx_exe)
+    return str(gxx_exe)

ibnr/gallery/bayesian/clark_growth_curve/__init__.py

@@ -0,0 +1,3 @@
+from ibnr.gallery.bayesian.clark_growth_curve.model import ClarkGrowthCurve
+
+__all__ = ["ClarkGrowthCurve"]

ibnr/gallery/bayesian/clark_growth_curve/card.md

@@ -0,0 +1,70 @@
+# clark_growth_curve — Bayesian Clark (Cape Cod)
+
+**Family:** bayesian · **Reference:** Clark, "LDF Curve-Fitting and
+Stochastic Reserving: A Maximum Likelihood Approach", *CAS Forum* (Fall
+2003) for the likelihood. **There is no published Stan ground truth for a
+Bayesian Clark** — the priors below are this package's specification, and
+the milestone-5 NumPyro/PyMC ports must hold them (and the plug-in phi)
+constant. The statistical `clark` entry is the MLE twin sharing the exact
+likelihood, parameterization, and age convention.
+
+## Model
+
+Incremental paid losses:
+
+```
+X[w,d] ~ ODP:  E[X] = elr * premium[w] * (G(x_hi) - G(x_lo)),  Var[X] = phi * E[X]
+G = loglogistic (default) or weibull, ages from the average accident date
+    (x = 12d - 6 for annual grains, first period starts at 0)
+```
+
+Cape Cod form only — one ELR against earned premium, Clark's recommendation
+for triangle-sized data. A free-ultimates (LDF) Bayesian variant is a
+scaffold exercise: eject this entry and swap `logelr` for a vector.
+
+Priors:
+
+| parameter | prior | rationale |
+|---|---|---|
+| logelr | normal(-0.4, sqrt(10)) | the Meyers-family variance-10 ELR prior |
+| omega | lognormal(log 1.5, 0.5) | curve shape; mass on ~0.6–4 |
+| theta | lognormal(log(4 * grain), 1) | curve scale; median at 4 dev periods, tracks the grain |
+
+## Dispersion phi — plug-in from the MLE twin
+
+`fit()` first runs the statistical `clark` entry (same curve, cape_cod) and
+passes its Pearson scale into Stan as data — the same treatment as
+`england_verrall_odp`'s phi. With phi fixed, the ODP quasi-likelihood is a
+proper likelihood for `(logelr, omega, theta)` up to a constant.
+
+## Data contract
+
+`kernels.contract.odp_stan_data` (incremental cells, premium required,
+negative increments rejected). The Stan data block additionally carries the
+per-cell `age_lo`/`age_hi` and the curve code — ages are data, not model
+logic, so ports cannot drift on the convention.
+
+## Predictive distribution
+
+Posterior draws of `(logelr, omega, theta)` × scaled-Poisson process draws
+`phi * Poisson(mu/phi)` per future cell, truncated at the triangle's final
+age (no tail), paid-to-date anchored — identical mechanics to the MLE twin
+with the posterior replacing the delta-method MVN. Fully-developed origins
+are constant.
+
+## Validation
+
+Retrospective Meyers protocol on paid: `scripts/meyers_validation.py
+--model clark_growth_curve`. Results in
+`analysis/results/clark_growth_curve_validation.csv`. No monograph bar
+exists; compare against the paid panel (england_verrall_odp, meyers_csr,
+clark MLE) on identical cohorts.
+
+**Result (2026-07-20, loglogistic, 96/200 completed — the rest rejected for
+negative paid increments): combined KS D = 63.4* vs crit 13.9, percentiles
+piled at ~0 — within noise of the MLE twin's 61.3*, confirming the
+posterior tracks the MLE.** The failure is the model, not the inference:
+the post-1997 settlement speedup plus the loglogistic tail mass (see the
+MLE twin's card for the weibull ablation, D = 49.6*). In the gallery this
+entry is the growth-curve baseline for ELPD/stacking; meyers_csr (D = 4.1,
+passes) is what calibrated paid reserving looks like in this window.