sherpa-amortization

README

# Sherpa Amortization v0.1

A Streamlit application for reconstructing fixed-rate mortgage loans from Form 1098 tax data.

## Features

- Reconstructs mortgage details from minimal 1098 data
- Supports multiple loan term scenarios (15-year, 30-year, custom)
- Uses bisection search to find optimal interest rate
- Generates complete amortization schedules
- Exports schedules to CSV

## Installation

```bash
pip install -r requirements.txt
```

## Usage

Run the Streamlit app:

```bash
streamlit run app.py
```

The app will open in your browser at `http://localhost:8501`.

## Input Parameters

- **Origination Date**: When the loan was originated
- **Tax Year**: The tax year from your Form 1098
- **Beginning Principal**: Balance on January 1 of the tax year
- **Total Interest Paid**: Interest paid during the tax year
- **Candidate Terms**: Loan terms to test (15-year, 30-year, or custom)

## How It Works

The solver uses:
1. The origination date to calculate payment timing
2. The beginning balance to constrain the original principal
3. The interest paid to find the optimal rate via bisection search
4. Standard amortization formulas to generate the payment schedule

## Example

For a sanity check, try these values:
- Origination Date: 2018-06-01
- Tax Year: 2023
- Beginning Balance: 274,472.55
- Interest Paid: 10,863.81
- Term: 30-year only

Expected results:
- Rate: ~4.00%
- Original Principal: ~$300,000
- Monthly Payment: ~$1,432.25

## Project Structure

- `app.py` - Streamlit UI
- `amort_engine.py` - Core amortization math functions
- `mortgage_1098_solver.py` - Solver logic for reconstructing loans
- `requirements.txt` - Python dependencies

## Future Enhancements (v0.2+)

- Commercial loan support
- AI-assisted mode for irregular payments
- Multiple tax year analysis
- Refinance detection

STATUS

No STATUS.

DECISIONS

No DECISIONS.

MEMORY

No MEMORY.

CLAUDE.md

No CLAUDE.md.

Diary mentions

No recent diary mentions for this app.