repaykit 1.0.0__py3-none-any.whl

repaykit/methods/constant_principal.py

@@ -0,0 +1,77 @@
+"""Constant-principal repayment allocation."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+
+from repaykit.methods.base import RepaymentMethod
+from repaykit.money import ZERO, max_decimal
+from repaykit.policies.rounding import RoundingPolicy
+from repaykit.results import ScheduleRow
+
+
+@dataclass(frozen=True, slots=True)
+class ConstantPrincipalAllocation(RepaymentMethod):
+    name: str = "constant_principal"
+
+    def payment_amount(
+        self,
+        *,
+        principal: Decimal,
+        annual_rate: Decimal,
+        term_years: Decimal,
+        periods: int,
+        periods_per_year: Decimal,
+        rounding: RoundingPolicy,
+    ) -> Decimal:
+        periodic_rate = annual_rate / periods_per_year
+        first_profit = principal * periodic_rate
+        return rounding.round_money(principal / Decimal(periods) + first_profit)
+
+    def iter_schedule(
+        self,
+        *,
+        principal: Decimal,
+        annual_rate: Decimal,
+        term_years: Decimal,
+        periods: int,
+        periods_per_year: Decimal,
+        start_date: date,
+        due_dates: Iterable[date],
+        rounding: RoundingPolicy,
+    ) -> Iterator[ScheduleRow]:
+        periodic_rate = annual_rate / periods_per_year
+        base_principal = rounding.round_money(principal / Decimal(periods))
+        balance = principal
+        allocated_principal = ZERO
+
+        for period, due_date in enumerate(due_dates, start=1):
+            profit_part = rounding.round_money(balance * periodic_rate)
+            if period == periods:
+                principal_part = max_decimal(principal - allocated_principal)
+            else:
+                principal_part = base_principal
+            installment = rounding.round_money(principal_part + profit_part)
+            closing = max_decimal(balance - principal_part)
+            yield ScheduleRow(
+                period=period,
+                due_date=due_date,
+                opening_balance=rounding.round_money(balance),
+                principal=rounding.round_money(principal_part),
+                profit=profit_part,
+                installment=installment,
+                closing_balance=rounding.round_money(closing),
+                metadata={
+                    "method": self.name,
+                    "allocation": "constant_principal",
+                    "periodic_rate": periodic_rate,
+                },
+            )
+            balance = closing
+            allocated_principal += principal_part
+
+    def unearned_profit_rebate(self, rows: list[ScheduleRow], as_of: date) -> Decimal:
+        return ZERO

repaykit/methods/flat_rate.py

@@ -0,0 +1,93 @@
+"""Flat-rate financing allocation."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+
+from repaykit.methods.base import RepaymentMethod
+from repaykit.money import ZERO, max_decimal
+from repaykit.policies.rounding import RoundingPolicy
+from repaykit.results import ScheduleRow
+
+
+@dataclass(frozen=True, slots=True)
+class FlatRateAllocation(RepaymentMethod):
+    name: str = "flat_rate"
+
+    def total_profit(
+        self,
+        principal: Decimal,
+        annual_rate: Decimal,
+        term_years: Decimal,
+    ) -> Decimal:
+        return principal * annual_rate * term_years
+
+    def payment_amount(
+        self,
+        *,
+        principal: Decimal,
+        annual_rate: Decimal,
+        term_years: Decimal,
+        periods: int,
+        periods_per_year: Decimal,
+        rounding: RoundingPolicy,
+    ) -> Decimal:
+        total = principal + self.total_profit(principal, annual_rate, term_years)
+        return rounding.round_money(total / Decimal(periods))
+
+    def iter_schedule(
+        self,
+        *,
+        principal: Decimal,
+        annual_rate: Decimal,
+        term_years: Decimal,
+        periods: int,
+        periods_per_year: Decimal,
+        start_date: date,
+        due_dates: Iterable[date],
+        rounding: RoundingPolicy,
+    ) -> Iterator[ScheduleRow]:
+        total_profit = rounding.round_money(self.total_profit(principal, annual_rate, term_years))
+        installment = self.payment_amount(
+            principal=principal,
+            annual_rate=annual_rate,
+            term_years=term_years,
+            periods=periods,
+            periods_per_year=periods_per_year,
+            rounding=rounding,
+        )
+        base_profit = rounding.round_money(total_profit / Decimal(periods))
+        balance = principal
+        allocated_principal = ZERO
+        allocated_profit = ZERO
+
+        for period, due_date in enumerate(due_dates, start=1):
+            if period == periods:
+                principal_part = max_decimal(principal - allocated_principal)
+                profit_part = max_decimal(total_profit - allocated_profit)
+                installment_part = rounding.round_money(principal_part + profit_part)
+            else:
+                profit_part = base_profit
+                principal_part = rounding.round_money(installment - profit_part)
+                installment_part = installment
+            closing = max_decimal(balance - principal_part)
+            yield ScheduleRow(
+                period=period,
+                due_date=due_date,
+                opening_balance=rounding.round_money(balance),
+                principal=rounding.round_money(principal_part),
+                profit=rounding.round_money(profit_part),
+                installment=rounding.round_money(installment_part),
+                closing_balance=rounding.round_money(closing),
+                metadata={
+                    "method": self.name,
+                    "allocation": "straight_line",
+                    "total_profit": total_profit,
+                },
+            )
+            balance = closing
+            allocated_principal += principal_part
+            allocated_profit += profit_part

repaykit/methods/reducing_balance.py

@@ -0,0 +1,85 @@
+"""Reducing-balance amortization."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+
+from repaykit.methods.base import RepaymentMethod
+from repaykit.money import ZERO, max_decimal
+from repaykit.policies.rounding import RoundingPolicy
+from repaykit.results import ScheduleRow
+
+
+@dataclass(frozen=True, slots=True)
+class ReducingBalanceAllocation(RepaymentMethod):
+    name: str = "reducing_balance"
+
+    def payment_amount(
+        self,
+        *,
+        principal: Decimal,
+        annual_rate: Decimal,
+        term_years: Decimal,
+        periods: int,
+        periods_per_year: Decimal,
+        rounding: RoundingPolicy,
+    ) -> Decimal:
+        periodic_rate = annual_rate / periods_per_year
+        if periodic_rate == ZERO:
+            return rounding.round_money(principal / Decimal(periods))
+        factor = (Decimal("1") + periodic_rate) ** periods
+        installment = principal * periodic_rate * factor / (factor - Decimal("1"))
+        return rounding.round_money(installment)
+
+    def iter_schedule(
+        self,
+        *,
+        principal: Decimal,
+        annual_rate: Decimal,
+        term_years: Decimal,
+        periods: int,
+        periods_per_year: Decimal,
+        start_date: date,
+        due_dates: Iterable[date],
+        rounding: RoundingPolicy,
+    ) -> Iterator[ScheduleRow]:
+        periodic_rate = annual_rate / periods_per_year
+        installment = self.payment_amount(
+            principal=principal,
+            annual_rate=annual_rate,
+            term_years=term_years,
+            periods=periods,
+            periods_per_year=periods_per_year,
+            rounding=rounding,
+        )
+        balance = principal
+        for period, due_date in enumerate(due_dates, start=1):
+            profit_part = rounding.round_money(balance * periodic_rate)
+            if period == periods:
+                principal_part = balance
+                installment_part = rounding.round_money(principal_part + profit_part)
+            else:
+                principal_part = max_decimal(installment - profit_part)
+                installment_part = installment
+            closing = max_decimal(balance - principal_part)
+            yield ScheduleRow(
+                period=period,
+                due_date=due_date,
+                opening_balance=rounding.round_money(balance),
+                principal=rounding.round_money(principal_part),
+                profit=rounding.round_money(profit_part),
+                installment=rounding.round_money(installment_part),
+                closing_balance=rounding.round_money(closing),
+                metadata={
+                    "method": self.name,
+                    "allocation": "amortized",
+                    "periodic_rate": periodic_rate,
+                },
+            )
+            balance = closing
+
+    def unearned_profit_rebate(self, rows: list[ScheduleRow], as_of: date) -> Decimal:
+        return ZERO

repaykit/methods/sum_of_digits.py

@@ -0,0 +1,96 @@
+"""Rule of 78 / sum-of-digits allocation generalized to any period count."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+
+from repaykit.exceptions import ValidationError
+from repaykit.methods.flat_rate import FlatRateAllocation
+from repaykit.money import ZERO, max_decimal
+from repaykit.policies.rounding import RoundingPolicy
+from repaykit.results import ScheduleRow
+
+
+@dataclass(frozen=True, slots=True)
+class SumOfDigitsAllocation(FlatRateAllocation):
+    name: str = "sum_of_digits"
+
+    @staticmethod
+    def denominator(periods: int) -> int:
+        if periods <= 0:
+            raise ValidationError("periods must be positive")
+        return periods * (periods + 1) // 2
+
+    @staticmethod
+    def remaining_weight(periods: int, completed_periods: int) -> int:
+        if periods <= 0:
+            raise ValidationError("periods must be positive")
+        if completed_periods < 0:
+            raise ValidationError("completed_periods cannot be negative")
+        remaining = periods - completed_periods
+        if remaining < 0:
+            return 0
+        return remaining * (remaining + 1) // 2
+
+    def iter_schedule(
+        self,
+        *,
+        principal: Decimal,
+        annual_rate: Decimal,
+        term_years: Decimal,
+        periods: int,
+        periods_per_year: Decimal,
+        start_date: date,
+        due_dates: Iterable[date],
+        rounding: RoundingPolicy,
+    ) -> Iterator[ScheduleRow]:
+        total_profit = rounding.round_money(self.total_profit(principal, annual_rate, term_years))
+        installment = self.payment_amount(
+            principal=principal,
+            annual_rate=annual_rate,
+            term_years=term_years,
+            periods=periods,
+            periods_per_year=periods_per_year,
+            rounding=rounding,
+        )
+        denominator = Decimal(self.denominator(periods))
+        balance = principal
+        allocated_principal = ZERO
+        allocated_profit = ZERO
+
+        for period, due_date in enumerate(due_dates, start=1):
+            if period == periods:
+                profit_part = max_decimal(total_profit - allocated_profit)
+                principal_part = max_decimal(principal - allocated_principal)
+                installment_part = rounding.round_money(principal_part + profit_part)
+            else:
+                weight = Decimal(periods - period + 1)
+                profit_part = rounding.round_money(total_profit * weight / denominator)
+                principal_part = rounding.round_money(installment - profit_part)
+                installment_part = installment
+            closing = max_decimal(balance - principal_part)
+            yield ScheduleRow(
+                period=period,
+                due_date=due_date,
+                opening_balance=rounding.round_money(balance),
+                principal=rounding.round_money(principal_part),
+                profit=rounding.round_money(profit_part),
+                installment=rounding.round_money(installment_part),
+                closing_balance=rounding.round_money(closing),
+                metadata={
+                    "method": self.name,
+                    "allocation": "sum_of_digits",
+                    "denominator": int(denominator),
+                    "weight": periods - period + 1,
+                    "total_profit": total_profit,
+                },
+            )
+            balance = closing
+            allocated_principal += principal_part
+            allocated_profit += profit_part
+
+    def unearned_profit_rebate(self, rows: list[ScheduleRow], as_of: date) -> Decimal:
+        return sum((row.profit for row in rows if row.due_date > as_of), Decimal("0"))

repaykit/money.py

@@ -0,0 +1,37 @@
+"""Decimal helpers for money-safe calculations."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any
+
+from repaykit.exceptions import ValidationError
+
+ZERO = Decimal("0")
+ONE = Decimal("1")
+
+
+def decimal(value: Any) -> Decimal:
+    """Convert a value to ``Decimal`` without accepting binary floats."""
+
+    if isinstance(value, Decimal):
+        return value
+    if isinstance(value, bool):
+        raise ValidationError("boolean values are not accepted for Decimal fields")
+    if isinstance(value, float):
+        raise ValidationError("float values are not accepted; use Decimal or str")
+    return Decimal(str(value))
+
+
+def require_positive(value: Decimal, name: str) -> None:
+    if value <= ZERO:
+        raise ValidationError(f"{name} must be positive")
+
+
+def require_non_negative(value: Decimal, name: str) -> None:
+    if value < ZERO:
+        raise ValidationError(f"{name} cannot be negative")
+
+
+def max_decimal(left: Decimal, right: Decimal = ZERO) -> Decimal:
+    return left if left >= right else right

repaykit/policies/__init__.py

@@ -0,0 +1,14 @@
+"""Policy classes for rounding, late charges, settlement, and allocation."""
+
+from repaykit.policies.allocation import AllocationBreakdown, FifoAllocationPolicy
+from repaykit.policies.late_charge import LateChargePolicy
+from repaykit.policies.rounding import RoundingPolicy
+from repaykit.policies.settlement import SettlementPolicy
+
+__all__ = [
+    "AllocationBreakdown",
+    "FifoAllocationPolicy",
+    "LateChargePolicy",
+    "RoundingPolicy",
+    "SettlementPolicy",
+]

repaykit/policies/allocation.py

@@ -0,0 +1,21 @@
+"""Payment allocation policies for ledger processing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+
+
+@dataclass(frozen=True, slots=True)
+class AllocationBreakdown:
+    charges: Decimal
+    profit: Decimal
+    principal: Decimal
+    unapplied: Decimal
+
+
+@dataclass(frozen=True, slots=True)
+class FifoAllocationPolicy:
+    """Simple FIFO allocation marker used by LoanAccount statements."""
+
+    name: str = "fifo"

repaykit/policies/late_charge.py

@@ -0,0 +1,63 @@
+"""Pluggable late charge policy objects."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+
+from repaykit.exceptions import ValidationError
+from repaykit.money import ZERO, max_decimal
+from repaykit.money import decimal as to_decimal
+from repaykit.policies.rounding import RoundingPolicy
+
+
+@dataclass(frozen=True, slots=True)
+class LateChargePolicy:
+    rate: Decimal = ZERO
+    grace_days: int = 0
+    basis: str = "flat"
+    minimum_charge: Decimal = ZERO
+    maximum_charge: Decimal | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "rate", to_decimal(self.rate))
+        object.__setattr__(self, "minimum_charge", to_decimal(self.minimum_charge))
+        if self.maximum_charge is not None:
+            object.__setattr__(self, "maximum_charge", to_decimal(self.maximum_charge))
+        if self.rate < ZERO:
+            raise ValidationError("late charge rate cannot be negative")
+        if self.grace_days < 0:
+            raise ValidationError("grace_days cannot be negative")
+        if self.minimum_charge < ZERO:
+            raise ValidationError("minimum_charge cannot be negative")
+        if self.maximum_charge is not None and self.maximum_charge < ZERO:
+            raise ValidationError("maximum_charge cannot be negative")
+        if self.basis not in {"flat", "daily"}:
+            raise ValidationError("late charge basis must be 'flat' or 'daily'")
+
+    def calculate(
+        self,
+        *,
+        overdue_amount: Decimal,
+        due_date: date,
+        as_of: date,
+        rounding: RoundingPolicy,
+    ) -> Decimal:
+        overdue_amount = max_decimal(overdue_amount)
+        if overdue_amount == ZERO or self.rate == ZERO:
+            return ZERO
+
+        days_late = (as_of - due_date).days - self.grace_days
+        if days_late <= 0:
+            return ZERO
+
+        if self.basis == "daily":
+            charge = overdue_amount * self.rate * Decimal(days_late)
+        elif self.basis == "flat":
+            charge = overdue_amount * self.rate
+        if charge < self.minimum_charge:
+            charge = self.minimum_charge
+        if self.maximum_charge is not None and charge > self.maximum_charge:
+            charge = self.maximum_charge
+        return rounding.round_money(charge)

repaykit/policies/rounding.py

@@ -0,0 +1,36 @@
+"""Explicit rounding policies for financial results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import ROUND_HALF_UP, Decimal
+
+from repaykit.exceptions import ValidationError
+
+
+@dataclass(frozen=True, slots=True)
+class RoundingPolicy:
+    currency: str = "MYR"
+    decimal_places: int = 2
+    rounding_mode: str = ROUND_HALF_UP
+    rate_decimal_places: int = 12
+
+    def __post_init__(self) -> None:
+        if self.decimal_places < 0:
+            raise ValidationError("decimal_places cannot be negative")
+        if self.rate_decimal_places < 0:
+            raise ValidationError("rate_decimal_places cannot be negative")
+
+    @property
+    def money_quantum(self) -> Decimal:
+        return Decimal("1").scaleb(-self.decimal_places)
+
+    @property
+    def rate_quantum(self) -> Decimal:
+        return Decimal("1").scaleb(-self.rate_decimal_places)
+
+    def round_money(self, amount: Decimal) -> Decimal:
+        return amount.quantize(self.money_quantum, rounding=self.rounding_mode)
+
+    def round_rate(self, rate: Decimal) -> Decimal:
+        return rate.quantize(self.rate_quantum, rounding=self.rounding_mode)

repaykit/policies/settlement.py

@@ -0,0 +1,66 @@
+"""Settlement policy implementation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from repaykit.exceptions import SettlementError
+from repaykit.money import ZERO, decimal, max_decimal
+from repaykit.results import SettlementQuote
+
+if TYPE_CHECKING:
+    from repaykit.account import LoanAccount
+
+
+@dataclass(frozen=True, slots=True)
+class SettlementPolicy:
+    other_charges: Decimal = ZERO
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "other_charges", decimal(self.other_charges))
+        if self.other_charges < ZERO:
+            raise SettlementError("other_charges cannot be negative")
+
+    def quote(self, account: LoanAccount, as_of: date) -> SettlementQuote:
+        loan = account.loan
+        if as_of < loan.start_date:
+            raise SettlementError("settlement date cannot be before loan start date")
+
+        rows = loan.schedule()
+        paid = account.total_paid(as_of=as_of)
+        late_charges = account.late_charges(as_of=as_of)
+        due_rows = [row for row in rows if row.due_date <= as_of]
+        future_rows = [row for row in rows if row.due_date > as_of]
+
+        scheduled_principal_paid = sum((row.principal for row in due_rows), ZERO)
+        outstanding_principal = max_decimal(loan.principal - scheduled_principal_paid)
+        accrued_profit = sum((row.profit for row in due_rows), ZERO)
+        rebate = loan.repayment_method.unearned_profit_rebate(rows, as_of)
+        total_contract = sum((row.installment for row in rows), ZERO)
+        amount_payable = max_decimal(
+            total_contract - rebate + late_charges + self.other_charges - paid
+        )
+
+        return SettlementQuote(
+            as_of=as_of,
+            outstanding_principal=loan.rounding.round_money(outstanding_principal),
+            accrued_profit=loan.rounding.round_money(accrued_profit),
+            unearned_profit_rebate=loan.rounding.round_money(rebate),
+            late_charges=loan.rounding.round_money(late_charges),
+            other_charges=loan.rounding.round_money(self.other_charges),
+            amount_payable=loan.rounding.round_money(amount_payable),
+            explanation=(
+                "Amount payable = total contract installments - method-specific unearned "
+                "profit rebate + late charges + other charges - payments received."
+            ),
+            metadata={
+                "method": loan.repayment_method.name,
+                "periods_due": len(due_rows),
+                "periods_remaining": len(future_rows),
+                "total_paid": paid,
+                "total_contract": loan.rounding.round_money(total_contract),
+            },
+        )

repaykit/py.typed

@@ -0,0 +1 @@
+

repaykit/results.py

@@ -0,0 +1,58 @@
+"""Immutable calculation result objects."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from decimal import Decimal
+from typing import Any
+
+from repaykit._serialization import result_to_dict
+
+Metadata = dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ScheduleRow:
+    period: int
+    due_date: date
+    opening_balance: Decimal
+    principal: Decimal
+    profit: Decimal
+    installment: Decimal
+    closing_balance: Decimal
+    metadata: Metadata = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return result_to_dict(self)
+
+
+@dataclass(frozen=True, slots=True)
+class Statement:
+    as_of: date
+    total_due: Decimal
+    total_paid: Decimal
+    arrears: Decimal
+    late_charges: Decimal
+    outstanding_balance: Decimal
+    next_due_date: date | None
+    metadata: Metadata = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return result_to_dict(self)
+
+
+@dataclass(frozen=True, slots=True)
+class SettlementQuote:
+    as_of: date
+    outstanding_principal: Decimal
+    accrued_profit: Decimal
+    unearned_profit_rebate: Decimal
+    late_charges: Decimal
+    other_charges: Decimal
+    amount_payable: Decimal
+    explanation: str
+    metadata: Metadata = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return result_to_dict(self)

repaykit/schedules/__init__.py

@@ -0,0 +1,21 @@
+"""Payment schedule generators."""
+
+from repaykit.schedules.base import PaymentSchedule
+from repaykit.schedules.biweekly import BiWeeklySchedule
+from repaykit.schedules.custom import CustomSchedule
+from repaykit.schedules.daily import DailySchedule
+from repaykit.schedules.monthly import MonthlySchedule
+from repaykit.schedules.quarterly import QuarterlySchedule
+from repaykit.schedules.weekly import WeeklySchedule
+from repaykit.schedules.yearly import YearlySchedule
+
+__all__ = [
+    "BiWeeklySchedule",
+    "CustomSchedule",
+    "DailySchedule",
+    "MonthlySchedule",
+    "PaymentSchedule",
+    "QuarterlySchedule",
+    "WeeklySchedule",
+    "YearlySchedule",
+]