Metadata-Version: 2.4
Name: refi-calculator
Version: 0.9.2
Summary: Refi Calculator Package.
License-Expression: Apache-2.0
License-File: LICENSE.txt
Keywords: Refi Calculator
Author: Jordan Pflum
Author-email: jordandpflum@gmail.com
Maintainer: Jordan Pflum
Maintainer-email: jordandpflum@gmail.com
Requires-Python: >=3.13, <3.14
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: Apache Software License
Provides-Extra: gui
Provides-Extra: web
Requires-Dist: plotly (>=5.18.0,<6.0.0) ; extra == "web"
Requires-Dist: streamlit (>=1.28.0,<2.0.0) ; extra == "web"
Project-URL: Homepage, https://github.com/jordandpflum/refi-calculator
Project-URL: Repository, https://github.com/jordandpflum/refi-calculator
Description-Content-Type: text/markdown

# Refi-Calculator

![CI](https://github.com/jordandpflum/refi-calculator/actions/workflows/ci.yml/badge.svg)
![PyPI](https://img.shields.io/pypi/v/refi-calculator)
![Python](https://img.shields.io/pypi/pyversions/refi-calculator)
![License](https://img.shields.io/pypi/l/refi-calculator)
![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)
![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)
[![Docs](https://img.shields.io/badge/docs-MkDocs-blue)](https://jordandpflum.github.io/refi-calculator/)
[![codecov](https://codecov.io/gh/jordandpflum/refi-calculator/branch/main/graph/badge.svg)](https://codecov.io/gh/jordandpflum/refi-calculator)

Refi-Calculator helps borrowers analyze whether refinancing makes sense by comparing current and
proposed loan terms through breakeven, NPV, amortization, and holding-period views inside a Tkinter
GUI.

## Features

- Side-by-side analysis of current vs. proposed mortgage payments (nominal and after-tax)
- Breakeven and holding-period tables with clear recommendations
- Accelerated payoff planning for maintaining current payment levels
- Loan Visualizations tab with the amortization comparison table (including cumulative interest Δ)
  plus the refreshed cumulative savings chart (ticks, zero-line label) and a new balance comparison
  chart for current vs. new loans
- Exportable CSV data for every tab
- Live market tab (when `FRED_API_KEY` is configured) surfaces historical 30-year fixed
  rates and pre-fills the refinance rate so you start with a realistic benchmark.
- Interactive history chart in the Market tab plus the value table below it with 30Y/15Y
  toggles for quick comparisons.

## Getting Started

### Requirements

- Python 3.13+
- Poetry for dependency management (the virtual environment lives in `.venv/`)

### Installation

```bash
poetry install
```

This command creates the virtual environment, installs dependencies, and prepares the hooks defined
in `.pre-commit-config.yaml`.

If you only need the GUI experience, install with `pip install .[gui]`; to enable the Streamlit
placeholder or eventual web UI, install `pip install .[web]`.

For a global CLI install, use `pipx` once the package is published, or run a local install with:

```bash
pipx install refi-calculator
# or (for development)
pip install -e .
```

### Running the GUI

```bash
poetry run refi-calculator
```

The `refi-calculator` console script now launches the Tkinter application exposed via
`refi_calculator.gui.app:main`, so you can start the GUI with `poetry run refi-calculator` or via
`pipx` once the package is installed globally.

### Running the Web placeholder

After installing the web optional dependencies (`pip install .[web]`), run `poetry run
refi-calculator-web` to launch the Streamlit placeholder. That console script now invokes the
Streamlit CLI (`streamlit run .../src/refi_calculator/web/app.py`) so you get the normal script
context and browser experience while the full Streamlit workflow is still under construction.

## Testing & Quality

- `poetry run pre-commit run --all-files` (runs formatting, linting, safety hooks, etc.)
- `poetry run pytest` (not yet populated, but ready for future tests)

### Market Data Tab

- Set the `FRED_API_KEY` environment variable to pull historical 30-year fixed-rate data when
  you launch the app. The Market tab will populate a refreshable table and update the default
  refinance rate using the latest observation. If the key is missing or the FRED request fails,
  the tab keeps working but reports the reason for the skip.
- Use the selectors inside the Market section to start with one year of history or extend the view
  to two years, five years, or all available data. The chart overlays both tenors with a legend,
  and the table below shows one column per tenor for the selected time window.

Add new tests under `tests/` following the `test_*.py` pattern whenever you enhance functionality.

## Hosted Streamlit Preview

- Visit
  [https://refi-calculator.streamlit.app/](https://refi-calculator.streamlit.app/)
  for a hosted version of the Streamlit placeholder
  so collaborators can explore the experience without installing dependencies locally.

## Documentation

- The MkDocs site at
  [https://jordandpflum.github.io/refi-calculator/](https://jordandpflum.github.io/refi-calculator/)
  serves the full guide, API reference, and autogenerated content for the project.

## Code Structure

- `src/refi_calculator/core/`: Shared calculations, models, and utility helpers used by every
  interface.
- `src/refi_calculator/gui/`: Tkinter GUI composed of:
    - `app.py`: The main application wiring.
    - `chart.py`: Custom savings chart canvas relying on shared helpers.
    - `builders/`: Tab-specific builders and UI helpers.
- `src/refi_calculator/web/`: Streamlit placeholder (future web UI) exposing `main()`.
- `src/refi_calculator/cli.py`: CLI launcher exposed via the `refi-calculator` console script.
- `bin/refi-calculator.py`: Entry point that runs the GUI.

## Contributing

- Keep imports grouped by functionality (allow isort to do the heavy lifting through pre-commit).
- Update or add tests in `tests/` before opening a pull request.
- Run `poetry run pre-commit run --all-files` to catch formatting/lint issues early.

## License

See [LICENSE.txt](LICENSE.txt) for licensing details.

