open-rating-engine 0.1.0__py3-none-any.whl

open_rating_engine/__init__.py

@@ -0,0 +1,67 @@
+"""open-rating-engine: a DAG-based insurance/banking rating engine.
+
+Names below are loaded on first access (see ``_lazy.py``), so ``import
+open_rating_engine`` is cheap and pulls in mlflow only once the pipeline or a layer
+is actually used.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING
+
+from ._lazy import attach
+
+try:
+    __version__ = version("open-rating-engine")
+except PackageNotFoundError:  # running from a source checkout that isn't installed
+    __version__ = "0+unknown"
+
+__getattr__, __dir__, _exports = attach(
+    __name__,
+    exports={
+        ".rating_engine.pricing_pipeline": ["PyfuncPricingPipeline"],
+        ".rating_engine.pricing_layers": [
+            "BasePricingLayer",
+            "ColumnCalculation",
+            "CustomLayer",
+            "DropColumns",
+            "GlmScoring",
+            "H2OScoringParameter",
+            "OnnxScoring",
+            "RatingTablesLayer",
+            "RenameColumns",
+            "SourceColumn",
+            "TableAggregation",
+            "TableDrop",
+            "TableJoin",
+            "TableTransform",
+            "DependencyError",
+            "LayerCalculationError",
+        ],
+        ".data_processing.data_aging": ["apply_aging", "AgingRuleError"],
+    },
+    submodules=["data_processing", "optimization", "rating_engine"],
+)
+__all__ = ["__version__", *_exports]
+
+if TYPE_CHECKING:
+    from . import data_processing, optimization, rating_engine
+    from .data_processing.data_aging import AgingRuleError, apply_aging
+    from .rating_engine.pricing_layers import (
+        BasePricingLayer,
+        ColumnCalculation,
+        CustomLayer,
+        DependencyError,
+        DropColumns,
+        GlmScoring,
+        H2OScoringParameter,
+        LayerCalculationError,
+        OnnxScoring,
+        RatingTablesLayer,
+        RenameColumns,
+        SourceColumn,
+        TableAggregation,
+        TableDrop,
+        TableJoin,
+        TableTransform,
+    )
+    from .rating_engine.pricing_pipeline import PyfuncPricingPipeline

open_rating_engine/_lazy.py

@@ -0,0 +1,58 @@
+"""Lazy re-exports for package ``__init__`` modules (PEP 562).
+
+A package ``__init__`` that eagerly imports its submodules makes every import of
+anything in the package pay for all of them: ``from open_rating_engine.rating_engine
+.binning import ...`` would load mlflow just to run the parent ``__init__``. Instead
+each ``__init__`` declares which names it re-exports from which submodule, and the
+submodule is imported the first time one of those names is accessed.
+
+Each ``__init__`` also repeats the re-exports under ``if TYPE_CHECKING:`` so IDEs and
+type checkers see real imports. ``tests/test_public_api.py`` keeps the two in sync.
+"""
+
+import sys
+from importlib import import_module
+
+
+def attach(package, exports, submodules=()):
+    """Return ``(__getattr__, __dir__, __all__)`` for ``package``.
+
+    Parameters
+    ----------
+    package : str
+        The package's ``__name__``.
+    exports : dict[str, list[str]]
+        Maps a module path relative to ``package`` (e.g. ``".pricing_layers"``) to
+        the public names re-exported from it.
+    submodules : iterable of str
+        Child module names (e.g. ``"optimization"``) made reachable as attributes,
+        so ``open_rating_engine.optimization`` works after a bare
+        ``import open_rating_engine``.
+    """
+    name_to_module = {}
+    for module, names in exports.items():
+        for name in names:
+            if name in name_to_module:
+                raise ValueError(
+                    f"{package}: {name!r} is exported from both "
+                    f"{name_to_module[name]!r} and {module!r}"
+                )
+            name_to_module[name] = module
+    submodules = frozenset(submodules)
+    __all__ = sorted(set(name_to_module) | submodules)
+
+    def __getattr__(name):
+        if name in name_to_module:
+            value = getattr(import_module(name_to_module[name], package), name)
+        elif name in submodules:
+            value = import_module(f".{name}", package)
+        else:
+            raise AttributeError(f"module {package!r} has no attribute {name!r}")
+        # Cache on the package so __getattr__ runs at most once per name.
+        setattr(sys.modules[package], name, value)
+        return value
+
+    def __dir__():
+        return list(__all__)
+
+    return __getattr__, __dir__, __all__

open_rating_engine/data_processing/__init__.py

@@ -0,0 +1,13 @@
+"""Data preparation applied before scoring. Loaded lazily; see ``.._lazy``."""
+
+from typing import TYPE_CHECKING
+
+from .._lazy import attach
+
+__getattr__, __dir__, __all__ = attach(
+    __name__,
+    exports={".data_aging": ["apply_aging", "AgingRuleError"]},
+)
+
+if TYPE_CHECKING:
+    from .data_aging import AgingRuleError, apply_aging

open_rating_engine/data_processing/data_aging.py

@@ -0,0 +1,96 @@
+"""Aging preprocessor — applies SourceColumn aging rules to input frames.
+
+One step forward in time per call. A single-cycle score path invokes this
+once between ``input_frames = {table: pd.DataFrame(...)}`` construction
+and ``pipeline.predict(...)``. A multi-year driver wraps the predict in a
+loop and calls this once per cycle.
+
+The function is pure (no DB, no I/O) and operates on dicts that the
+caller has already resolved into ``layer_configs`` and ``input_frames``.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+__all__ = [
+    "apply_aging",
+    "AgingRuleError",
+]
+
+
+SOURCE_COLUMN_LAYER_TYPE = "SourceColumn"
+
+
+def apply_aging(
+    layer_configs: dict[str, dict],
+    input_frames: dict[str, pd.DataFrame],
+) -> dict[str, pd.DataFrame]:
+    """Mutate ``input_frames`` in place by applying each enabled SourceColumn
+    aging rule. Returns the same dict for chaining.
+
+    For every layer config of type ``SourceColumn`` with an
+    ``aging_rule.enabled == True`` and a non-empty ``expression``, the
+    expression is evaluated with ``{df, np, pd}`` in scope where ``df`` is
+    ``input_frames[source_table]``. The result is assigned to
+    ``df[source_column]`` in place. Layers without a rule, with the rule
+    disabled, or whose ``source_table`` is absent from ``input_frames`` are
+    silently skipped.
+
+    Order of evaluation within a single call is dict-insertion order.
+    Cross-column reads between aged columns are undefined within a cycle —
+    use a ``ColumnCalculation`` layer if you need ordering guarantees.
+    """
+    for layer_name, cfg in layer_configs.items():
+        if cfg.get("type") != SOURCE_COLUMN_LAYER_TYPE:
+            continue
+        rule = cfg.get("aging_rule")
+        if not isinstance(rule, dict):
+            continue
+        if not rule.get("enabled", True):
+            continue
+        expression = rule.get("expression")
+        if not isinstance(expression, str) or not expression:
+            continue
+
+        table = cfg.get("source_table")
+        column = cfg.get("source_column")
+        if not isinstance(table, str) or not table:
+            continue
+        if not isinstance(column, str) or not column:
+            continue
+        if table not in input_frames:
+            continue
+
+        df = input_frames[table]
+        try:
+            result = eval(expression, {"df": df, "np": np, "pd": pd})
+        except Exception as exc:
+            raise AgingRuleError(
+                f"aging rule on '{table}.{column}' raised: {exc}"
+            ) from exc
+
+        if not isinstance(result, pd.Series):
+            try:
+                result = pd.Series(result, index=df.index)
+            except Exception as exc:
+                raise AgingRuleError(
+                    f"aging rule on '{table}.{column}' returned "
+                    f"{type(result).__name__}; expected pandas Series or "
+                    f"a scalar broadcastable to one ({exc})"
+                ) from exc
+
+        if len(result) != len(df):
+            raise AgingRuleError(
+                f"aging rule on '{table}.{column}' returned a Series of "
+                f"length {len(result)}; expected {len(df)} (matching df)"
+            )
+
+        df[column] = result
+
+    return input_frames
+
+
+class AgingRuleError(ValueError):
+    """Raised when an aging expression fails to evaluate or returns an
+    incompatible shape."""

open_rating_engine/optimization/__init__.py

@@ -0,0 +1,35 @@
+"""Price optimisers that run on top of a pricing pipeline. Loaded lazily; see ``.._lazy``."""
+
+from typing import TYPE_CHECKING
+
+from .._lazy import attach
+
+__getattr__, __dir__, __all__ = attach(
+    __name__,
+    exports={
+        ".individual_price_optimizer": ["PriceOptimizerIndividual"],
+        ".rating_factor_price_optimizer": ["PriceOptimizerRatingFactor"],
+        ".multi_period_individual_price_optimizer": [
+            "PriceOptimizerIndividualMultiPeriod",
+            "make_log_multiplier_penalty",
+        ],
+        ".multi_period_rating_factor_price_optimizer": [
+            "PriceOptimizerRatingFactorMultiPeriod",
+            "make_log_multiplier_regularizer",
+        ],
+        ".simulate_adjustment_grid": ["simulate_adjustment_grid", "make_demand_emulation"],
+    },
+)
+
+if TYPE_CHECKING:
+    from .individual_price_optimizer import PriceOptimizerIndividual
+    from .multi_period_individual_price_optimizer import (
+        PriceOptimizerIndividualMultiPeriod,
+        make_log_multiplier_penalty,
+    )
+    from .multi_period_rating_factor_price_optimizer import (
+        PriceOptimizerRatingFactorMultiPeriod,
+        make_log_multiplier_regularizer,
+    )
+    from .rating_factor_price_optimizer import PriceOptimizerRatingFactor
+    from .simulate_adjustment_grid import make_demand_emulation, simulate_adjustment_grid