refi-calculator 0.8.0

Refi Calculator Package.

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

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:

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

Running the GUI

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/ 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/ 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 for licensing details.