Initial build

Author: Morgan Squire

Diff for: README.md

@@ -1,2 +1,41 @@
 # pyrateer
 Python rating engine
+
+# Structure
+
+## Expression Tree
+
+Pyrateer converts a rating formula into a type of binary tree called an algebraic expression tree where terminal nodes are one of three rating factor classes: NumericFactor, CategoricalFactor, or Constant Factor. All non-terminal nodes are CompoundFactors that apply an arithmetic operator. For example, the formula `Asset Size * (Limit - Retention) * Industry * Loss Cost Factor` gets converted to the following expression tree.
+
+```mermaid
+graph TB
+    p1[Product] --> p2[Product]
+    p1 --> LC[Loss Cost Factor]
+    p2 --> p3[Product]
+    p2 --> I[Industry]
+    p3 --> A[Asset Size]
+    p3 --> D[Difference]
+    D --> R[Retention]
+    D --> L[Limit]
+```
+When the `calculate()` method is called on the root object, it calls the `calculate()` method on its child nodes. When a terminal node is reached, the factor is returned and when a non-terminal node is reached, the CompoundFactor calls the `calculate()` method on its children.
+
+## Rating Factors
+
+Each rating factor must be initialized with a lookup table in the form of a dictionary to map input values to a factor value. For example, asset size would be initalized with a dictionary that lists base rates for each asset size. For numeric inputs, values between listed values can be calculated using linear interpolation. Categorical factors must have a value in the lookup that matches the input. Constant factors don't require an input and will always return the same factor.
+
+# Implementation
+
+Including the full lookup tables in the script for each factor can be cumbersome and create unnecessarily long Python files. To allow for reuse of a rate plan after it is defined, there are a few options
+
+## Pickling
+
+Use the pickle package to serialize the rate plan object for quick import and use. The `example.py` file creates the rate plan and rates a JSON string input. It then saves the rate plan to a pickle file. The `example_pickle.py` script loads the pickled rate plan, and rates the same JSON string.
+
+## JSON Rate Plans
+
+Future development could implement a JSON format for saving rate plan information. This is better than pickling because when the pyrateer package is updated, it could make it difficult to unpickle files that were created with older versions of pyrateer (or older versions of pickle). The JSON format is just data so updated versions of pyrateer would import the JSON into the updated package with fewer issues.
+
+## Rate Database
+
+Future development could also allow for pyrateer to read rating factor tables from a database and create the rate plan from those tables. Using this strategy would allow for the rating tables to be accessed for other purposes whereas the JSON could be more difficult to use in different applications. However, issues with versioning the rate tables would need to be solved and this may end up being more complicated.

Diff for: environment.yml

@@ -0,0 +1,7 @@
+name: pyrateer
+dependencies:
+  - python>=3.11
+  - pip
+  - pip:
+    - -r requirements.txt
+    - -r requirements-dev.txt

Diff for: example.py

@@ -0,0 +1,106 @@
+from pyrateer.factors import NumericFactor, CategoricalFactor, ConstantFactor
+import pickle
+
+
+asset_size = NumericFactor(
+    "Asset Size",
+    {
+        1: 1065,
+        1_000_000: 1_819,
+        2_500_000: 3_966,
+        5_000_000: 3_619,
+        10_000_000: 4_291,
+        15_000_000: 4_905,
+        20_000_000: 5_120,
+        25_000_000: 5_499,
+        50_000_000: 6_279,
+        75_000_000: 6_966,
+        100_000_000: 7_156,
+        250_000_000: 8_380,
+    }
+)
+
+limit_retention_dict = {
+   0: -0.760,
+    1_000: -0.600,
+    2_500: -0.510,
+    5_000: -0.406,
+    7_500: -0.303,
+    10_000: -0.231,
+    15_000: -0.128,
+    20_000: -0.064,
+    25_000: 0.000,
+    35_000: 0.105,
+    50_000: 0.175,
+    75_000: 0.277,
+    100_000: 0.350,
+    125_000: 0.406,
+    150_000: 0.452,
+    175_000: 0.491,
+    200_000: 0.525,
+    225_000: 0.555,
+    250_000: 0.581,
+    275_000: 0.605,
+    300_000: 0.627,
+    325_000: 0.648,
+    350_000: 0.666,
+    375_000: 0.684,
+    400_000: 0.700,
+    425_000: 0.715,
+    450_000: 0.730,
+    475_000: 0.743,
+    500_000: 0.756,
+    525_000: 0.807,
+    550_000: 0.819,
+    575_000: 0.831,
+    600_000: 0.842,
+    625_000: 0.853,
+    650_000: 0.864,
+    675_000: 0.874,
+    700_000: 0.883,
+    725_000: 0.893,
+    750_000: 0.902,
+    775_000: 0.910,
+    800_000: 0.919,
+    825_000: 0.927,
+    850_000: 0.935,
+    875_000: 0.943,
+    900_000: 0.950,
+    925_000: 0.957,
+    950_000: 0.964,
+    975_000: 0.971,
+    1_000_000: 1.000,
+    2_000_000: 1.415,
+    2_500_000: 1.526,
+    3_000_000: 1.637,
+    4_000_000: 1.820,
+    5_000_000: 1.986,
+}
+
+limit = NumericFactor("Limit", limit_retention_dict)
+retention = NumericFactor("Retention", limit_retention_dict)
+industry = CategoricalFactor(
+    "Industry",
+    {
+        "Hazard Group 1": 1.0,
+        "Hazard Group 2": 1.25,
+        "Hazard Group 3": 1.5,
+    }
+)
+loss_cost = ConstantFactor("Loss Cost", 1.7)
+
+rate_plan = asset_size * (limit - retention) * industry * loss_cost
+
+json_input = {
+    "Asset Size": 1_200_000,
+    "Limit": 5_000_000,
+    "Retention": 1_000_000,
+    "Industry": "Hazard Group 2",
+}
+
+rate = rate_plan.calculate(**json_input)
+
+print(rate)
+
+with open("rate_plan.pkl", "wb") as f:
+    pickle.dump(rate_plan, f)

Diff for: example_pickle.py

@@ -0,0 +1,15 @@
+import pickle
+
+with open("rate_plan.pkl", "rb") as fp:
+    rate_plan = pickle.load(fp)
+
+json_input = {
+    "Asset Size": 1_200_000,
+    "Limit": 5_000_000,
+    "Retention": 1_000_000,
+    "Industry": "Hazard Group 2",
+}
+
+rate = rate_plan.calculate(**json_input)
+
+print(rate)

Diff for: pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "pyrateer"
+version = "0.0.1"
+authors = [
+    {name="Morgan Squire", email="[email protected]"},
+]
+description = "Python rating engine"
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
+]
+dynamic = ["dependencies"]
+
+[project.urls]
+"Homepage" = "https://github.com/mosquire/pyrateer"
+
+[tool.setuptools.dynamic]
+dependencies = {file = ["requirements.txt"]}

Diff for: rate_plan.pkl

@@ -0,0 +1,3 @@
+build
+pytest
+black

Diff for: requirements-dev.txt

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

Diff for: requirements.txt

@@ -0,0 +1,79 @@
+from abc import ABC, abstractmethod
+
+
+class RatingFactor(ABC):
+    def __init__(self, name, lookup):
+        self.name = name
+        self.lookup = lookup
+
+    @abstractmethod
+    def calculate(self):
+        pass
+
+    def __add__(self, other):
+        return CompoundFactor(self, other, operator="+")
+
+    def __sub__(self, other):
+        return CompoundFactor(self, other, operator="-")
+
+    def __mul__(self, other):
+        return CompoundFactor(self, other, operator="*")
+
+
+class NumericFactor(RatingFactor):
+    def calculate(self, input):
+        if input in self.lookup:
+            return self.lookup[input]
+        elif input < min(self.lookup.keys()):
+            return self.lookup[min(self.lookup.keys())]
+        elif input > max(self.lookup.keys()):
+            return self.lookup[max(self.lookup.keys())]
+        else:
+            return linterp(input, self.lookup)
+
+
+class CategoricalFactor(RatingFactor):
+    def calculate(self, input):
+        return self.lookup[input]
+
+
+class ConstantFactor(RatingFactor):
+    def calculate(self, input=None):
+        if input is not None:
+            raise ValueError("Constant factor should not have an input")
+        return self.lookup
+
+
+class CompoundFactor(RatingFactor):
+    def __init__(self, lhs, rhs, operator):
+        self.lhs = lhs
+        self.rhs = rhs
+        self.operator = operator
+
+    def calculate(self, **rate_params):
+        if isinstance(self.lhs, CompoundFactor):
+            lhs_value = self.lhs.calculate(**rate_params)
+        else:
+            lhs_value = self.lhs.calculate(rate_params.get(self.lhs.name))
+        if isinstance(self.rhs, CompoundFactor):
+            rhs_value = self.rhs.calculate(**rate_params)
+        else:
+            rhs_value = self.rhs.calculate(rate_params.get(self.rhs.name))
+        if self.operator == "+":
+            return lhs_value + rhs_value
+        elif self.operator == "-":
+            return lhs_value - rhs_value
+        elif self.operator == "*":
+            return lhs_value * rhs_value
+        else:
+            raise NotImplementedError(f"Operator {self.operator} not implemented")
+
+
+def linterp(input, lookup):
+    keys = sorted(lookup.keys())
+    for i in range(len(keys) - 1):
+        if keys[i] <= input < keys[i + 1]:
+            pct_traveled = (input - keys[i]) / (keys[i + 1] - keys[i])
+            return lookup[keys[i]] + pct_traveled * (
+                lookup[keys[i + 1]] - lookup[keys[i]]
+            )

Diff for: setup.py

@@ -0,0 +1,26 @@
+import pytest
+from pyrateer.factors import CategoricalFactor, NumericFactor, ConstantFactor
+
+@pytest.fixture
+def cat_factor():
+    cat_factor = CategoricalFactor(
+        name = "cat",
+        lookup = {"a": 1.0, "b": 1.25, "c": 1.5}
+    )
+    return cat_factor
+
+@pytest.fixture
+def num_factor():
+    num_factor = NumericFactor(
+        name = "num",
+        lookup = {100_000: 1.0, 250_000: 1.25, 500_000: 1.5}
+    )
+    return num_factor
+
+@pytest.fixture
+def const_factor():
+    const_factor = ConstantFactor(
+        name="const",
+        lookup=10
+    )
+    return const_factor

Diff for: src/pyrateer/__init__.py

@@ -0,0 +1,58 @@
+import pytest
+from pyrateer.factors import CompoundFactor
+
+
+class TestCategoricalFactor():
+    def test_cat_factor_lookup(self, cat_factor):
+        assert cat_factor.calculate("a") == 1.0
+        assert cat_factor.calculate("b") == 1.25
+        assert cat_factor.calculate("c") == 1.5
+
+class TestNumericFactor():
+    def test_num_factor_lookup_values(self, num_factor):
+        assert num_factor.calculate(50_000) == 1.0
+        assert num_factor.calculate(200_000) == pytest.approx(1.1666667)
+        assert num_factor.calculate(250_000) == 1.25
+        assert num_factor.calculate(700_000) == 1.5
+
+class TestConstantFactor():
+    def test_const_factor_return_value(self, const_factor):
+        assert const_factor.calculate() == 10
+
+class TestCompoundFactor():
+    def test_compound_constructor(self, cat_factor, num_factor):
+        sum_factor = cat_factor + num_factor
+        assert isinstance(sum_factor, CompoundFactor)
+        assert sum_factor.operator == "+"
+        assert sum_factor.lhs == cat_factor
+        assert sum_factor.rhs == num_factor
+
+    def test_sum_numeric_cat(self, cat_factor, num_factor):
+        sum_factor = cat_factor + num_factor
+        rate_params = {"cat": "c", "num": 130_000}
+        assert sum_factor.calculate(**rate_params) == 2.55
+    
+    def test_sum_numeric_const(self, num_factor, const_factor):
+        sum_factor = num_factor + const_factor
+        rate_params = {"num": 130_000}
+        assert sum_factor.calculate(**rate_params) == 11.05
+        
+    def test_product_numeric_cat(self, cat_factor, num_factor):
+        product_factor = cat_factor * num_factor
+        rate_params = {"cat": "c", "num": 250_000}
+        assert product_factor.calculate(**rate_params) == 1.875
+        
+    def test_product_numeric_const(self, num_factor, const_factor):
+        sum_factor = num_factor * const_factor
+        rate_params = {"num": 130_000}
+        assert sum_factor.calculate(**rate_params) == 10.5
+
+    def test_product_numeric_cat(self, cat_factor, num_factor):
+        difference_factor = cat_factor - num_factor
+        rate_params = {"cat": "c", "num": 250_000}
+        assert difference_factor.calculate(**rate_params) == 0.25
+        
+    def test_product_numeric_const(self, num_factor, const_factor):
+        difference_factor = num_factor - const_factor
+        rate_params = {"num": 130_000}
+        assert difference_factor.calculate(**rate_params) == -8.95