repaykit 1.0.0__py3-none-any.whl

repaykit/__init__.py

@@ -0,0 +1,18 @@
+"""Pure Python repayment schedule, ledger, and settlement toolkit."""
+
+from repaykit.account import LoanAccount
+from repaykit.loan import Loan
+from repaykit.results import ScheduleRow, SettlementQuote, Statement
+
+__version__ = "1.0.0"
+version = __version__
+
+__all__ = [
+    "Loan",
+    "LoanAccount",
+    "ScheduleRow",
+    "SettlementQuote",
+    "Statement",
+    "__version__",
+    "version",
+]

repaykit/_serialization.py

@@ -0,0 +1,28 @@
+"""Serialization helpers that avoid lossy float conversion."""
+
+from __future__ import annotations
+
+from dataclasses import fields, is_dataclass
+from datetime import date
+from decimal import Decimal
+from typing import Any
+
+
+def serialize_value(value: Any) -> Any:
+    if isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, dict):
+        return {key: serialize_value(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [serialize_value(item) for item in value]
+    if isinstance(value, tuple):
+        return tuple(serialize_value(item) for item in value)
+    return value
+
+
+def result_to_dict(result: Any) -> dict[str, Any]:
+    if not is_dataclass(result) or isinstance(result, type):
+        raise TypeError("result_to_dict expects a dataclass result object")
+    return {field.name: serialize_value(getattr(result, field.name)) for field in fields(result)}

repaykit/account.py

@@ -0,0 +1,98 @@
+"""Loan account ledger and statements."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+
+from repaykit.exceptions import ValidationError
+from repaykit.ledger import Payment
+from repaykit.money import ZERO, max_decimal
+from repaykit.results import SettlementQuote, Statement
+
+if TYPE_CHECKING:
+    from repaykit.loan import Loan
+
+
+@dataclass(slots=True)
+class LoanAccount:
+    loan: Loan
+    payments: list[Payment] = field(default_factory=list)
+
+    def add_payment(
+        self,
+        *,
+        amount: Decimal,
+        paid_at: date,
+        reference: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Payment:
+        if paid_at < self.loan.start_date:
+            raise ValidationError("payment date cannot be before loan start_date")
+        payment = Payment(
+            amount=amount,
+            paid_at=paid_at,
+            reference=reference,
+            metadata=metadata or {},
+        )
+        self.payments.append(payment)
+        self.payments.sort(key=lambda item: (item.paid_at, item.reference or ""))
+        return payment
+
+    def total_paid(self, *, as_of: date) -> Decimal:
+        return self.loan.rounding.round_money(
+            sum((payment.amount for payment in self.payments if payment.paid_at <= as_of), ZERO)
+        )
+
+    def late_charges(self, *, as_of: date) -> Decimal:
+        remaining_paid = self.total_paid(as_of=as_of)
+        charges = ZERO
+        for row in self.loan.iter_schedule():
+            if row.due_date > as_of:
+                break
+            applied = min(remaining_paid, row.installment)
+            remaining_paid -= applied
+            overdue = max_decimal(row.installment - applied)
+            charges += self.loan.late_charge_policy.calculate(
+                overdue_amount=overdue,
+                due_date=row.due_date,
+                as_of=as_of,
+                rounding=self.loan.rounding,
+            )
+        return self.loan.rounding.round_money(charges)
+
+    def statement(self, *, as_of: date) -> Statement:
+        rows = self.loan.schedule()
+        due_rows = [row for row in rows if row.due_date <= as_of]
+        next_row = next((row for row in rows if row.due_date > as_of), None)
+        total_due = self.loan.rounding.round_money(sum((row.installment for row in due_rows), ZERO))
+        total_paid = self.total_paid(as_of=as_of)
+        late_charges = self.late_charges(as_of=as_of)
+        arrears = self.loan.rounding.round_money(max_decimal(total_due + late_charges - total_paid))
+        contract_total = self.loan.rounding.round_money(
+            sum((row.installment for row in rows), ZERO)
+        )
+        outstanding = self.loan.rounding.round_money(
+            max_decimal(contract_total + late_charges - total_paid)
+        )
+        return Statement(
+            as_of=as_of,
+            total_due=total_due,
+            total_paid=total_paid,
+            arrears=arrears,
+            late_charges=late_charges,
+            outstanding_balance=outstanding,
+            next_due_date=None if next_row is None else next_row.due_date,
+            metadata={
+                "payments_count": len(
+                    [payment for payment in self.payments if payment.paid_at <= as_of]
+                ),
+                "periods_due": len(due_rows),
+                "contract_total": contract_total,
+            },
+        )
+
+    def full_settlement(self, *, as_of: date) -> SettlementQuote:
+        return self.loan.settlement_policy.quote(self, as_of)

repaykit/accruals/__init__.py

@@ -0,0 +1,8 @@
+"""Accrual policies."""
+
+from repaykit.accruals.base import AccrualPolicy
+from repaykit.accruals.daily import DailyAccrual
+from repaykit.accruals.flat import FlatAccrual
+from repaykit.accruals.periodic import PeriodicAccrual
+
+__all__ = ["AccrualPolicy", "DailyAccrual", "FlatAccrual", "PeriodicAccrual"]

repaykit/accruals/base.py

@@ -0,0 +1,25 @@
+"""Accrual policy interfaces."""
+
+from __future__ import annotations
+
+from abc import ABC
+from dataclasses import dataclass
+from decimal import Decimal
+
+from repaykit.exceptions import ValidationError
+from repaykit.money import decimal, require_non_negative
+
+
+@dataclass(frozen=True, slots=True)
+class AccrualPolicy(ABC):
+    annual_rate: Decimal
+    allow_negative_rate: bool = False
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "annual_rate", decimal(self.annual_rate))
+        if self.annual_rate < Decimal("0") and not self.allow_negative_rate:
+            raise ValidationError("annual_rate cannot be negative")
+
+    def periodic_rate(self, periods_per_year: Decimal) -> Decimal:
+        require_non_negative(periods_per_year, "periods_per_year")
+        return self.annual_rate / periods_per_year

repaykit/accruals/daily.py

@@ -0,0 +1,18 @@
+"""Daily accrual policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+
+from repaykit.accruals.base import AccrualPolicy
+
+
+@dataclass(frozen=True, slots=True)
+class DailyAccrual(AccrualPolicy):
+    day_count_basis: Decimal = Decimal("365")
+
+    def accrue(self, principal: Decimal, start: date, end: date) -> Decimal:
+        days = Decimal((end - start).days)
+        return principal * self.annual_rate * days / self.day_count_basis

repaykit/accruals/flat.py

@@ -0,0 +1,14 @@
+"""Flat accrual policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+
+from repaykit.accruals.base import AccrualPolicy
+
+
+@dataclass(frozen=True, slots=True)
+class FlatAccrual(AccrualPolicy):
+    def total_profit(self, principal: Decimal, term_years: Decimal) -> Decimal:
+        return principal * self.annual_rate * term_years

repaykit/accruals/periodic.py

@@ -0,0 +1,12 @@
+"""Periodic simple-rate accrual policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from repaykit.accruals.base import AccrualPolicy
+
+
+@dataclass(frozen=True, slots=True)
+class PeriodicAccrual(AccrualPolicy):
+    pass

repaykit/backends/README.md

@@ -0,0 +1,12 @@
+# Backend Design Note
+
+The public API is intentionally pure Python and policy-oriented. A future optional Rust/PyO3
+backend can accelerate bulk schedule generation by implementing the same repayment method
+interfaces behind a feature flag or backend registry.
+
+Compatibility rules for a compiled backend:
+
+- Accept and return `Decimal`-compatible values at the Python boundary.
+- Preserve `ScheduleRow`, `Statement`, and `SettlementQuote` public shapes.
+- Preserve rounding policy behavior exactly.
+- Keep the pure Python backend as the reference implementation and fallback.

repaykit/enums.py

@@ -0,0 +1,21 @@
+"""Small enum types used by repaykit."""
+
+from enum import StrEnum
+
+
+class PaymentFrequency(StrEnum):
+    DAILY = "daily"
+    WEEKLY = "weekly"
+    BIWEEKLY = "biweekly"
+    MONTHLY = "monthly"
+    QUARTERLY = "quarterly"
+    YEARLY = "yearly"
+    CUSTOM = "custom"
+
+
+class RepaymentMethodName(StrEnum):
+    FLAT_RATE = "flat_rate"
+    SUM_OF_DIGITS = "sum_of_digits"
+    RULE_OF_78 = "rule_of_78"
+    REDUCING_BALANCE = "reducing_balance"
+    CONSTANT_PRINCIPAL = "constant_principal"

repaykit/exceptions.py

@@ -0,0 +1,21 @@
+"""Custom exceptions raised by repaykit."""
+
+
+class RepayKitError(Exception):
+    """Base exception for repaykit."""
+
+
+class ValidationError(RepayKitError, ValueError):
+    """Raised when user input fails validation."""
+
+
+class UnsupportedMethodError(RepayKitError):
+    """Raised when a requested repayment method is not supported."""
+
+
+class ScheduleGenerationError(RepayKitError):
+    """Raised when a schedule cannot be generated safely."""
+
+
+class SettlementError(RepayKitError):
+    """Raised when a settlement quote cannot be produced."""

repaykit/exporters/__init__.py

@@ -0,0 +1,12 @@
+"""Export helpers."""
+
+from repaykit.exporters.csv import schedule_to_csv, write_schedule_csv
+from repaykit.exporters.dicts import rows_to_dicts, schedule_to_dicts, to_dict
+
+__all__ = [
+    "rows_to_dicts",
+    "schedule_to_csv",
+    "schedule_to_dicts",
+    "to_dict",
+    "write_schedule_csv",
+]

repaykit/exporters/csv.py

@@ -0,0 +1,35 @@
+"""CSV exporters for schedules."""
+
+from __future__ import annotations
+
+import csv
+from collections.abc import Iterable
+from pathlib import Path
+
+from repaykit.exporters.dicts import rows_to_dicts
+from repaykit.results import ScheduleRow
+
+CSV_HEADERS = [
+    "period",
+    "due_date",
+    "opening_balance",
+    "principal",
+    "profit",
+    "installment",
+    "closing_balance",
+    "metadata",
+]
+
+
+def write_schedule_csv(rows: Iterable[ScheduleRow], path: str | Path) -> None:
+    data = rows_to_dicts(rows)
+    if not data:
+        Path(path).write_text("", encoding="utf-8")
+        return
+    with Path(path).open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.DictWriter(handle, fieldnames=CSV_HEADERS)
+        writer.writeheader()
+        writer.writerows(data)
+
+
+schedule_to_csv = write_schedule_csv

repaykit/exporters/dicts.py

@@ -0,0 +1,19 @@
+"""Dictionary exporters for result objects."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from repaykit._serialization import result_to_dict
+
+
+def to_dict(row: Any) -> dict[str, Any]:
+    return result_to_dict(row)
+
+
+def rows_to_dicts(rows: Iterable[Any]) -> list[dict[str, Any]]:
+    return [to_dict(row) for row in rows]
+
+
+schedule_to_dicts = rows_to_dicts

repaykit/ledger/__init__.py

@@ -0,0 +1,7 @@
+"""Payment ledger objects."""
+
+from repaykit.ledger.account_statement import Statement
+from repaykit.ledger.payment import Payment
+from repaykit.ledger.transaction import Transaction
+
+__all__ = ["Payment", "Statement", "Transaction"]

repaykit/ledger/account_statement.py

@@ -0,0 +1,5 @@
+"""Statement exports."""
+
+from repaykit.results import Statement
+
+__all__ = ["Statement"]

repaykit/ledger/payment.py

@@ -0,0 +1,25 @@
+"""Payment records."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from decimal import Decimal
+from typing import Any
+
+from repaykit.exceptions import ValidationError
+from repaykit.money import decimal, require_positive
+
+
+@dataclass(frozen=True, slots=True)
+class Payment:
+    amount: Decimal
+    paid_at: date
+    reference: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "amount", decimal(self.amount))
+        require_positive(self.amount, "payment amount")
+        if self.reference is not None and not self.reference.strip():
+            raise ValidationError("payment reference cannot be blank")

repaykit/ledger/transaction.py

@@ -0,0 +1,17 @@
+"""Ledger transaction primitives."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from decimal import Decimal
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Transaction:
+    amount: Decimal
+    posted_at: date
+    kind: str
+    reference: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)

repaykit/loan.py

@@ -0,0 +1,157 @@
+"""Public loan contract model."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from datetime import date
+from decimal import Decimal
+from typing import Any
+
+from repaykit.accruals import AccrualPolicy, DailyAccrual, FlatAccrual, PeriodicAccrual
+from repaykit.enums import RepaymentMethodName
+from repaykit.exceptions import UnsupportedMethodError, ValidationError
+from repaykit.methods import (
+    ConstantPrincipalAllocation,
+    FlatRateAllocation,
+    ReducingBalanceAllocation,
+    RepaymentMethod,
+    SumOfDigitsAllocation,
+)
+from repaykit.money import decimal, require_positive
+from repaykit.policies import LateChargePolicy, RoundingPolicy, SettlementPolicy
+from repaykit.results import ScheduleRow
+from repaykit.schedules import (
+    BiWeeklySchedule,
+    DailySchedule,
+    MonthlySchedule,
+    PaymentSchedule,
+    QuarterlySchedule,
+    WeeklySchedule,
+    YearlySchedule,
+)
+from repaykit.terms import Term
+
+
+@dataclass(slots=True)
+class Loan:
+    principal: Decimal
+    term: Term
+    payment_schedule: PaymentSchedule
+    accrual_policy: AccrualPolicy
+    repayment_method: RepaymentMethod
+    rounding: RoundingPolicy = field(default_factory=RoundingPolicy)
+    start_date: date = field(default_factory=date.today)
+    late_charge_policy: LateChargePolicy = field(default_factory=LateChargePolicy)
+    settlement_policy: SettlementPolicy = field(default_factory=SettlementPolicy)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.principal = decimal(self.principal)
+        require_positive(self.principal, "principal")
+        if self.period_count() <= 0:
+            raise ValidationError("term must produce at least one period")
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        amount: Decimal,
+        annual_rate: Decimal,
+        term: str | Term,
+        payment_frequency: str,
+        method: str,
+        start_date: date,
+        currency: str = "MYR",
+        **metadata: Any,
+    ) -> Loan:
+        term_obj = Term.parse(term)
+        schedule = _schedule_from_frequency(payment_frequency)
+        method_obj = _method_from_name(method)
+        accrual: AccrualPolicy
+        if isinstance(method_obj, FlatRateAllocation | SumOfDigitsAllocation):
+            accrual = FlatAccrual(annual_rate=decimal(annual_rate))
+        elif payment_frequency == "daily":
+            accrual = DailyAccrual(annual_rate=decimal(annual_rate))
+        else:
+            accrual = PeriodicAccrual(annual_rate=decimal(annual_rate))
+        return cls(
+            principal=decimal(amount),
+            term=term_obj,
+            payment_schedule=schedule,
+            accrual_policy=accrual,
+            repayment_method=method_obj,
+            rounding=RoundingPolicy(currency=currency),
+            start_date=start_date,
+            metadata=metadata,
+        )
+
+    @property
+    def annual_rate(self) -> Decimal:
+        return self.accrual_policy.annual_rate
+
+    @property
+    def periods_per_year(self) -> Decimal:
+        return self.payment_schedule.periods_per_year
+
+    def period_count(self) -> int:
+        return self.payment_schedule.period_count(self.start_date, self.term)
+
+    def term_years(self) -> Decimal:
+        return self.payment_schedule.term_years(self.start_date, self.term)
+
+    def payment_amount(self) -> Decimal:
+        return self.repayment_method.payment_amount(
+            principal=self.principal,
+            annual_rate=self.annual_rate,
+            term_years=self.term_years(),
+            periods=self.period_count(),
+            periods_per_year=self.periods_per_year,
+            rounding=self.rounding,
+        )
+
+    def iter_schedule(self) -> Iterator[ScheduleRow]:
+        return self.repayment_method.iter_schedule(
+            principal=self.principal,
+            annual_rate=self.annual_rate,
+            term_years=self.term_years(),
+            periods=self.period_count(),
+            periods_per_year=self.periods_per_year,
+            start_date=self.start_date,
+            due_dates=self.payment_schedule.iter_due_dates(self.start_date, self.term),
+            rounding=self.rounding,
+        )
+
+    def schedule(self) -> list[ScheduleRow]:
+        return list(self.iter_schedule())
+
+
+def _schedule_from_frequency(value: str) -> PaymentSchedule:
+    normalized = value.lower().replace("-", "_")
+    schedules: dict[str, PaymentSchedule] = {
+        "daily": DailySchedule(),
+        "weekly": WeeklySchedule(),
+        "biweekly": BiWeeklySchedule(),
+        "bi_weekly": BiWeeklySchedule(),
+        "monthly": MonthlySchedule(),
+        "quarterly": QuarterlySchedule(),
+        "yearly": YearlySchedule(),
+        "annual": YearlySchedule(),
+    }
+    try:
+        return schedules[normalized]
+    except KeyError as exc:
+        raise ValidationError(f"unsupported payment frequency: {value}") from exc
+
+
+def _method_from_name(value: str) -> RepaymentMethod:
+    normalized = value.lower().replace("-", "_")
+    if normalized == RepaymentMethodName.FLAT_RATE:
+        return FlatRateAllocation()
+    if normalized in {RepaymentMethodName.SUM_OF_DIGITS, RepaymentMethodName.RULE_OF_78}:
+        return SumOfDigitsAllocation()
+    if normalized == RepaymentMethodName.REDUCING_BALANCE:
+        return ReducingBalanceAllocation()
+    if normalized == RepaymentMethodName.CONSTANT_PRINCIPAL:
+        return ConstantPrincipalAllocation()
+    raise UnsupportedMethodError(f"unsupported repayment method: {value}")

repaykit/methods/__init__.py

@@ -0,0 +1,15 @@
+"""Repayment allocation methods."""
+
+from repaykit.methods.base import RepaymentMethod
+from repaykit.methods.constant_principal import ConstantPrincipalAllocation
+from repaykit.methods.flat_rate import FlatRateAllocation
+from repaykit.methods.reducing_balance import ReducingBalanceAllocation
+from repaykit.methods.sum_of_digits import SumOfDigitsAllocation
+
+__all__ = [
+    "ConstantPrincipalAllocation",
+    "FlatRateAllocation",
+    "ReducingBalanceAllocation",
+    "RepaymentMethod",
+    "SumOfDigitsAllocation",
+]

repaykit/methods/base.py

@@ -0,0 +1,46 @@
+"""Repayment method interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable, Iterator
+from datetime import date
+from decimal import Decimal
+
+from repaykit.policies.rounding import RoundingPolicy
+from repaykit.results import ScheduleRow
+
+
+class RepaymentMethod(ABC):
+    name: str
+
+    @abstractmethod
+    def payment_amount(
+        self,
+        *,
+        principal: Decimal,
+        annual_rate: Decimal,
+        term_years: Decimal,
+        periods: int,
+        periods_per_year: Decimal,
+        rounding: RoundingPolicy,
+    ) -> Decimal:
+        """Return a representative installment amount."""
+
+    @abstractmethod
+    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]:
+        """Yield immutable schedule rows."""
+
+    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"))