Metadata-Version: 2.4
Name: mortgage-utils
Version: 1.0.0
Summary: Lightweight Python utility library for mortgage calculations — DTI, amortization, affordability, LTV.
Author-email: Sanjeev Kumar <contact@ournethelps.com>
License: MIT
Project-URL: Homepage, https://ournethelps.com
Project-URL: Repository, https://github.com/sanjeevkumardev/mortgage-utils-py
Project-URL: Bug Tracker, https://github.com/sanjeevkumardev/mortgage-utils-py/issues
Keywords: mortgage,calculator,dti,debt-to-income,amortization,affordability,ltv,fintech,real-estate,home-loan,mortgage-broker
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# mortgage-utils

> Lightweight Python utility library for mortgage calculations - DTI, amortization, affordability, and LTV.

Built by **[OurNetHelps](https://ournethelps.com)** - mortgage tools for US mortgage brokers.

---

## Installation

```bash
pip install mortgage-utils
```

---

## Features

- DTI Calculator - front-end and back-end debt-to-income ratio
- Amortization - monthly payment and full amortization schedule
- Affordability - maximum loan amount based on income and debts
- LTV - loan-to-value ratio with PMI threshold detection
- Zero dependencies
- Python 3.8 and above

---

## Usage

### DTI (Debt-to-Income)

```python
from mortgage_utils import front_end_dti, back_end_dti, dti_report

# Front-End DTI
front = front_end_dti(monthly_housing_cost=1800, gross_monthly_income=7000)
print(front)
# {'ratio': 0.2571, 'percentage': 25.71, 'status': 'good', ...}

# Back-End DTI
back = back_end_dti(
    monthly_housing_cost=1800,
    monthly_debts=500,
    gross_monthly_income=7000
)
print(back)
# {'ratio': 0.3286, 'percentage': 32.86, 'status': 'good', ...}

# Full DTI Report
report = dti_report(
    monthly_housing_cost=1800,
    monthly_debts=500,
    gross_monthly_income=7000
)
print(report['qualified'])  # True
print(report['summary'])    # "Front-End: 25.71% | Back-End: 32.86%"
```

### Amortization

```python
from mortgage_utils import monthly_payment, amortization_schedule

# Monthly Payment
result = monthly_payment(
    loan_amount=300000,
    annual_interest_rate=6.5,
    loan_term_years=30
)
print(result['monthly_payment'])  # 1896.20
print(result['total_interest'])   # 382632.0

# Full Amortization Schedule
schedule = amortization_schedule(300000, 6.5, 30)
print(schedule[0])
# {'month': 1, 'payment': 1896.20, 'principal': 271.2, 'interest': 1625.0, 'balance': 299728.8}
```

### Affordability

```python
from mortgage_utils import max_affordable_loan, loan_to_value

# Max Affordable Loan
result = max_affordable_loan(
    gross_monthly_income=8000,
    monthly_debts=500,
    annual_interest_rate=6.5,
    loan_term_years=30
)
print(result['estimated_loan_amount'])  # max loan amount
print(result['max_monthly_payment'])    # max monthly payment

# LTV Ratio
ltv = loan_to_value(loan_amount=320000, property_value=400000)
print(ltv['percentage'])   # 80.0
print(ltv['requires_pmi']) # False
```

---

## API Reference

### `front_end_dti(monthly_housing_cost, gross_monthly_income)`
Returns front-end DTI with status (good / caution / high).

### `back_end_dti(monthly_housing_cost, monthly_debts, gross_monthly_income)`
Returns back-end DTI including all monthly debts.

### `dti_report(monthly_housing_cost, monthly_debts, gross_monthly_income)`
Returns full DTI report with qualified boolean and summary.

### `monthly_payment(loan_amount, annual_interest_rate, loan_term_years)`
Returns monthly P&I payment, total payment, and total interest.

### `amortization_schedule(loan_amount, annual_interest_rate, loan_term_years)`
Returns list of monthly payment breakdowns.

### `max_affordable_loan(gross_monthly_income, monthly_debts, annual_interest_rate, loan_term_years, max_dti=43.0)`
Returns max affordable loan amount based on income and DTI threshold.

### `loan_to_value(loan_amount, property_value)`
Returns LTV ratio, percentage, down payment, and PMI requirement flag.

---

## DTI Status Thresholds

| Status | Front-End DTI | Back-End DTI |
|--------|--------------|--------------|
| good | 28% or less | 36% or less |
| caution | 29% to 36% | 37% to 43% |
| high | Above 36% | Above 43% |

---

## Related

- [OurNetHelps](https://ournethelps.com) - mortgage tools for US mortgage brokers
- [mortgage-utils on NPM](https://www.npmjs.com/package/mortgage-utils) - JavaScript version
- [Live Mortgage Calculator](https://huggingface.co/spaces/sanjeevkumardev/mortgage-suite)

---

## License

MIT © [Sanjeev Kumar](https://ournethelps.com)
