refi-calculator 0.7.0__py3-none-any.whl

refi_calculator/web/formatting.py

@@ -0,0 +1,90 @@
+"""Helpers for formatting values displayed in the Streamlit interface."""
+
+from __future__ import annotations
+
+from logging import getLogger
+
+logger = getLogger(__name__)
+
+
+def format_currency(value: float) -> str:
+    """Format a numeric value as whole-dollar currency.
+
+    Args:
+        value: Numeric value to format.
+
+    Returns:
+        Dollar-formatted string without decimal cents.
+    """
+    return f"${value:,.0f}"
+
+
+def format_optional_currency(value: float | None) -> str:
+    """Format an optional numeric value as currency, falling back to N/A.
+
+    Args:
+        value: Optional numeric value.
+
+    Returns:
+        Formatted currency or "N/A" when no value is present.
+    """
+    if value is None:
+        return "N/A"
+    return format_currency(value)
+
+
+def format_months(value: float | int | None) -> str:
+    """Describe a month count alongside its equivalent in years.
+
+    Args:
+        value: Number of months to convert.
+
+    Returns:
+        Human-friendly string or "N/A" when value is missing.
+    """
+    if value is None:
+        return "N/A"
+    months = int(value)
+    years = value / 12
+    return f"{months} mo ({years:.1f} yr)"
+
+
+def format_signed_currency(value: float) -> str:
+    """Format a signed value with explicit plus/minus.
+
+    Args:
+        value: Value to format with sign.
+
+    Returns:
+        Signed currency string to highlight deltas.
+    """
+    prefix = "+" if value >= 0 else "-"
+    return f"{prefix}{format_currency(abs(value))}"
+
+
+def format_savings_delta(value: float) -> str:
+    """Invert savings sign to match user-facing storytelling.
+
+    Args:
+        value: Value representing savings.
+
+    Returns:
+        Signed string reflecting the UX messaging used in the GUI.
+    """
+    prefix = "-" if value >= 0 else "+"
+    return f"{prefix}{format_currency(abs(value))}"
+
+
+logger.debug("Formatting helpers module initialized.")
+
+__all__ = [
+    "format_currency",
+    "format_optional_currency",
+    "format_months",
+    "format_signed_currency",
+    "format_savings_delta",
+]
+
+__description__ = """
+Formatting utilities for the Streamlit refinance calculator widgets.
+"""

refi_calculator/web/info.py

@@ -0,0 +1,226 @@
+"""Background and help content shared on the informational tab."""
+
+from __future__ import annotations
+
+from logging import getLogger
+
+import streamlit as st
+
+logger = getLogger(__name__)
+
+BACKGROUND_SECTIONS = [
+    (
+        "What is Refinancing?",
+        (
+            "Refinancing replaces your existing mortgage with a new loan, typically to secure a "
+            "lower interest rate, change the loan term, or access home equity (cash-out refinance). "
+            "The new loan pays off your old mortgage, and you begin making payments on the new terms.\n\n"
+            "Common reasons to refinance:\n"
+            "• Lower your interest rate and monthly payment\n"
+            "• Shorten your loan term to pay off faster\n"
+            "• Switch from adjustable-rate to fixed-rate (or vice versa)\n"
+            "• Access equity for major expenses (cash-out refi)\n"
+            "• Remove private mortgage insurance (PMI)"
+        ),
+    ),
+    (
+        "Key Costs to Consider",
+        (
+            "Refinancing isn't free. Typical closing costs run 2-5% of the loan amount and may include:\n\n"
+            "• Origination fees (lender charges)\n"
+            "• Appraisal fee ($300-$700)\n"
+            "• Title search and insurance\n"
+            "• Recording fees\n"
+            "• Credit report fee\n"
+            "• Prepaid interest, taxes, and insurance\n\n"
+            "These costs can be paid upfront, rolled into the loan balance, or covered by accepting a "
+            'slightly higher rate ("no-cost" refi). Rolling costs into the loan means you\'ll pay interest '
+            "on them over time."
+        ),
+    ),
+    (
+        "The Breakeven Concept",
+        (
+            "The fundamental question: How long until your monthly savings recoup the closing costs?\n\n"
+            "Simple Breakeven = Closing Costs ÷ Monthly Savings\n\n"
+            "Example: $6,000 in costs with $200/month savings = 30 months to breakeven.\n\n"
+            "If you plan to stay in the home longer than the breakeven period, refinancing likely makes sense. "
+            "If you might move or refinance again before breakeven, you'll lose money on the transaction.\n\n"
+            "Important caveat: Simple breakeven ignores the time value of money. A dollar saved three years "
+            "from now is worth less than a dollar today."
+        ),
+    ),
+    (
+        "Net Present Value (NPV)",
+        (
+            "NPV provides a more sophisticated analysis by discounting future savings to today's dollars. "
+            'It accounts for the "opportunity cost" of your closing costs — what you could have earned by investing '
+            "that money instead.\n\n"
+            "NPV = -Closing Costs + Σ (Monthly Savings / (1 + r)^n)\n\n"
+            "Where r is the monthly discount rate and n is the month number.\n\n"
+            "A positive NPV means refinancing creates value even after accounting for opportunity cost. "
+            "The higher the NPV, the more clearly beneficial the refinance."
+        ),
+    ),
+    (
+        "The Term Reset Problem",
+        (
+            "A critical nuance many borrowers miss: refinancing often resets your amortization clock.\n\n"
+            "Example: You're 5 years into a 30-year mortgage (25 years remaining). If you refinance into a new "
+            "30-year loan, you've added 5 years to your payoff timeline — even if your rate dropped.\n\n"
+            "This can dramatically increase total interest paid over the life of the loan, even with a lower rate. "
+            "Solutions:\n"
+            "• Refinance into a shorter term (e.g., 20 or 15 years)\n"
+            "• Make extra principal payments to maintain your original payoff date\n"
+            "• Compare total interest paid, not just monthly payment"
+        ),
+    ),
+    (
+        "Tax Implications",
+        (
+            "Mortgage interest is tax-deductible if you itemize deductions. This effectively reduces your true "
+            "interest rate:\n\n"
+            "After-Tax Rate = Nominal Rate × (1 - Marginal Tax Rate)\n\n"
+            "Example: 6% rate with 24% marginal bracket = 4.56% effective rate\n\n"
+            "Note: The 2017 tax law changes increased the standard deduction significantly, meaning fewer homeowners "
+            "now itemize. If you take the standard deduction, there's no mortgage interest tax benefit."
+        ),
+    ),
+    (
+        "Cash-Out Refinancing",
+        (
+            "A cash-out refi lets you borrow against your home equity, receiving the difference as cash. Your new "
+            "loan balance equals your old balance plus the cash withdrawn plus closing costs.\n\n"
+            "Considerations:\n"
+            "• You're converting home equity into debt\n"
+            "• Monthly payment will likely increase even with a lower rate\n"
+            "• Interest on cash-out amounts above original loan may not be tax-deductible\n"
+            "• Good for consolidating high-interest debt or funding investments\n"
+            "• Risky if used for consumption or if home values decline"
+        ),
+    ),
+    (
+        "When NOT to Refinance",
+        (
+            "Refinancing isn't always beneficial:\n\n"
+            "• Short holding period: If you'll move before breakeven\n"
+            "• Small rate reduction: Less than 0.5-0.75% often doesn't justify costs\n"
+            "• Extended payoff: If resetting to 30 years significantly increases total interest\n"
+            "• High closing costs: Some lenders charge excessive fees\n"
+            "• Credit issues: Poor credit may mean higher rates or denial\n"
+            "• Equity constraints: Most lenders require 20%+ equity for best rates\n\n"
+            "Rule of thumb: A 1% rate reduction with typical costs usually breaks even in 2-3 years."
+        ),
+    ),
+]
+
+HELP_SECTIONS = [
+    (
+        "Overview",
+        (
+            "This calculator helps you analyze whether refinancing your mortgage makes financial sense. "
+            "It goes beyond simple breakeven calculations to provide NPV analysis, tax-adjusted figures, "
+            "sensitivity tables, and visualizations.\n\n"
+            "All calculations update automatically when you change inputs or press Enter."
+        ),
+    ),
+    (
+        "Calculator Tab",
+        (
+            "The main analysis screen with inputs and results.\n\n"
+            "INPUTS - Current Loan:\n"
+            "• Balance ($): Your remaining mortgage principal\n"
+            "• Rate (%): Current annual interest rate\n"
+            "• Years Remaining: Time left on your current loan\n\n"
+            "INPUTS - New Loan:\n"
+            "• Rate (%): Proposed new interest rate\n"
+            "• Term (years): Length of new loan (typically 15, 20, or 30)\n"
+            "• Closing Costs ($): Total refinance fees\n"
+            "• Cash Out ($): Additional amount to borrow (0 for rate-only refi)\n"
+            "• Opportunity Rate (%): Expected return on alternative investments\n"
+            "• Marginal Tax Rate (%): Your tax bracket (0 if you don't itemize)"
+        ),
+    ),
+    (
+        "Rate Sensitivity Tab",
+        (
+            "Shows how breakeven and NPV change at different new interest rates.\n\n"
+            "The table displays scenarios from your current rate down to the maximum reduction specified in Options (default: 2% "
+            "in 0.25% steps).\n\n"
+            "Use this to answer questions like:\n"
+            '• "Should I wait for rates to drop further?"\n'
+            '• "How much does each 0.25% reduction improve my outcome?"'
+        ),
+    ),
+    (
+        "Holding Period Tab",
+        (
+            "Shows NPV at various holding periods (1-20 years).\n\n"
+            "This helps when you're uncertain how long you'll stay in the home. The recommendation column provides guidance:\n"
+            "• Strong Yes (green): NPV > $5,000\n"
+            "• Yes (dark green): NPV > $0\n"
+            "• Marginal (orange): NPV between -$2,000 and $0\n"
+            "• No (red): NPV < -$2,000"
+        ),
+    ),
+    (
+        "Loan Visualizations Tab",
+        (
+            "The Loan Visualizations tab contains the annual amortization comparison table, which now includes a cumulative interest Δ "
+            "column alongside colored savings/cost indicators so you can track how the refinance affects total interest year over year."
+        ),
+    ),
+    (
+        "Charts within Loan Visualizations",
+        (
+            "Two charts live on the Loan Visualizations tab:\n\n"
+            "1. Cumulative Savings Chart — shows nominal (blue) and NPV-adjusted (green) savings with monthly ticks, a labeled zero line, "
+            "and a dashed vertical line marking the NPV breakeven point.\n"
+            "2. Loan Balance Comparison Chart — plots the remaining balances for the current (red) and new (blue) loans so you can see how "
+            "the term reset or accelerated payoff affects your timeline."
+        ),
+    ),
+    (
+        "Options Tab",
+        (
+            "Customize calculation parameters:\n\n"
+            "• NPV Window (years): Time horizon for NPV calculation displayed on main tab\n"
+            "• Chart Horizon (years): How many years shown on the chart\n"
+            "• Max Rate Reduction (%): How far below current rate to show in sensitivity table\n"
+            "• Rate Step (%): Increment between rows in sensitivity table"
+        ),
+    ),
+    (
+        "Exporting Data",
+        (
+            "Export buttons are available on Calculator, Rate Sensitivity, Holding Period, and Amortization tabs. "
+            "Files are saved with timestamps to avoid overwriting."
+        ),
+    ),
+]
+
+
+def render_info_tab() -> None:
+    """Render background and help guidance content."""
+    background_tab, help_tab = st.tabs(["Background", "Help"])
+
+    with background_tab:
+        for title, text in BACKGROUND_SECTIONS:
+            st.markdown(f"**{title}**")
+            st.markdown(text)
+            st.divider()
+
+    with help_tab:
+        for title, text in HELP_SECTIONS:
+            st.markdown(f"**{title}**")
+            st.markdown(text)
+            st.divider()
+
+
+logger.debug("Info tab helpers initialized.")
+
+__all__ = ["render_info_tab"]
+
+__description__ = """
+Background and help guidance for the refinance calculator experience.
+"""

refi_calculator/web/market.py

@@ -0,0 +1,270 @@
+"""Market data helpers for the refinance calculator interface."""
+
+from __future__ import annotations
+
+from logging import getLogger
+from typing import cast
+
+import pandas as pd
+import plotly.graph_objects as go
+import streamlit as st
+
+from refi_calculator.core.market.fred import fetch_fred_series
+from refi_calculator.gui.market_constants import MARKET_PERIOD_OPTIONS, MARKET_SERIES
+
+logger = getLogger(__name__)
+
+MARKET_CACHE_TTL_SECONDS = 15 * 60
+MARKET_AXIS_YEAR_THRESHOLD_MONTHS = 24
+
+
+def get_api_key() -> str | None:
+    """Retrieve the FRED API key stored in Streamlit secrets."""
+    return st.secrets.get("FRED_API_KEY")
+
+
+@st.cache_data(ttl=MARKET_CACHE_TTL_SECONDS)
+def _fetch_series(series_id: str, api_key: str) -> list[tuple[str, float]]:
+    """Fetch a single series from FRED with caching.
+
+    Args:
+        series_id: FRED series identifier.
+        api_key: API key to authenticate with FRED.
+
+    Returns:
+        List of (date, value) observations.
+    """
+    return fetch_fred_series(series_id, api_key)
+
+
+def fetch_all_series(api_key: str) -> tuple[dict[str, list[tuple[str, float]]], list[str]]:
+    """Retrieve all configured market series from FRED.
+
+    Args:
+        api_key: API key to authenticate with FRED.
+
+    Returns:
+        Tuple of raw series data and collection of error messages.
+    """
+    raw_series: dict[str, list[tuple[str, float]]] = {}
+    errors: list[str] = []
+    for label, series_id in MARKET_SERIES:
+        try:
+            observations = _fetch_series(series_id, api_key)
+        except RuntimeError as exc:
+            logger.exception("Failed to fetch %s series", label)
+            errors.append(f"{label}: {exc}")
+            observations = []
+        raw_series[label] = observations
+    return raw_series, errors
+
+
+def _build_market_dataframe(
+    raw_series: dict[str, list[tuple[str, float]]],
+) -> pd.DataFrame:
+    """Combine multiple FRED series into a Date-indexed DataFrame.
+
+    Args:
+        raw_series: Mapping of series labels to raw (date, value) observations.
+
+    Returns:
+        Combined DataFrame with Date index and one column per series.
+    """
+    frames: list[pd.DataFrame] = []
+    for label, observations in raw_series.items():
+        if not observations:
+            continue
+        df = pd.DataFrame(observations, columns=pd.Index(["Date", label]))
+        df["Date"] = pd.to_datetime(df["Date"])
+        df.set_index("Date", inplace=True)
+        frames.append(df)
+
+    if not frames:
+        return pd.DataFrame()
+
+    return pd.concat(frames, axis=1).sort_index()
+
+
+def _filter_market_dataframe(
+    data: pd.DataFrame,
+    months: int | None,
+) -> pd.DataFrame:
+    """Restrict the provided series to the most recent `months`.
+
+    Args:
+        data: Date-indexed DataFrame with market series.
+        months: Number of trailing months to keep or None for full history.
+
+    Returns:
+        Filtered DataFrame.
+    """
+    if months is None or data.empty:
+        return data
+
+    last_date_raw = data.index.max()
+    if last_date_raw is pd.NaT:
+        return data
+    last_date = cast(pd.Timestamp, last_date_raw)
+    cutoff = last_date - pd.DateOffset(months=months)
+    return data.loc[data.index >= cutoff]
+
+
+def _segment_months(value: str) -> int | None:
+    """Convert the UI option value into a number of months.
+
+    Args:
+        value: Selected option value.
+
+    Returns:
+        Number of months or None for full history.
+    """
+    if value == "0":
+        return None
+    return int(value)
+
+
+def _render_market_chart(data: pd.DataFrame) -> None:
+    """Render the market series chart with optimized axes.
+
+    Args:
+        data: Date-indexed DataFrame with market series.
+    """
+    if data.empty:
+        return
+
+    melted = data.reset_index().melt("Date", var_name="Series", value_name="Rate")
+    min_rate = melted["Rate"].min()
+    max_rate = melted["Rate"].max()
+    span = max_rate - min_rate
+    padding = max(span * 0.05, 0.1)
+    lower = max(min_rate - padding, 0)
+    upper = max_rate + padding
+
+    first_date_raw = data.index.min()
+    last_date_raw = data.index.max()
+    if first_date_raw is pd.NaT or last_date_raw is pd.NaT:
+        return
+    first_date = cast(pd.Timestamp, first_date_raw)
+    last_date = cast(pd.Timestamp, last_date_raw)
+    date_span = cast(pd.Timedelta, last_date - first_date)
+    months = date_span.days / 30
+    use_year_only = months >= MARKET_AXIS_YEAR_THRESHOLD_MONTHS
+    date_format = "%Y" if use_year_only else "%b %Y"
+
+    fig = go.Figure()
+    for label, group in melted.groupby("Series"):
+        fig.add_trace(
+            go.Scatter(
+                x=group["Date"],
+                y=group["Rate"],
+                mode="lines",
+                name=label,
+                hovertemplate="Date=%{x|%b %Y}<br>Series=%{text}<br>Rate=%{y:.2f}%<extra></extra>",
+                text=[label] * len(group),
+            ),
+        )
+
+    xaxis_kwargs: dict[str, object] = {
+        "title": "Date",
+        "tickformat": date_format,
+        "tickangle": 0 if use_year_only else -45,
+    }
+    if use_year_only:
+        start_year = int(first_date.year)
+        end_year = int(last_date.year)
+        xaxis_kwargs.update(
+            {
+                "tickmode": "array",
+                "tickvals": [
+                    pd.Timestamp(year=y, month=1, day=1) for y in range(start_year, end_year + 1)
+                ],
+            },
+        )
+    else:
+        xaxis_kwargs["tickmode"] = "auto"
+
+    fig.update_layout(
+        xaxis=xaxis_kwargs,
+        yaxis=dict(
+            title="Rate (%)",
+            range=[lower, upper],
+        ),
+        legend=dict(title="Series"),
+        margin=dict(t=5, b=30, l=50, r=10),
+        hovermode="x",
+    )
+
+    st.plotly_chart(fig, use_container_width=True)
+
+
+def render_market_tab() -> None:
+    """Render the market data tab with metrics, range selector, chart, and table."""
+    st.subheader("Market Data")
+
+    api_key = get_api_key()
+    if not api_key:
+        st.warning(
+            "Add your FRED API key to `st.secrets['FRED_API_KEY']` to view mortgage rate history.",
+        )
+        return
+
+    raw_series, errors = fetch_all_series(api_key)
+    for err in errors:
+        st.error(err)
+
+    market_df_all = _build_market_dataframe(raw_series)
+    if market_df_all.empty:
+        st.info("Market data is not available for the selected range.")
+        return
+
+    latest_valid = market_df_all.dropna(how="all")
+    if latest_valid.empty:
+        st.info("Market data lacks recent observations.")
+        return
+
+    latest = latest_valid.iloc[-1].dropna()
+    latest_timestamp_raw = latest_valid.index.max()
+    if latest_timestamp_raw is pd.NaT:
+        st.info("Market data lacks recent observations.")
+        return
+    latest_date = cast(pd.Timestamp, latest_timestamp_raw).date()
+    st.markdown(
+        f"**Current rates (latest available as of {latest_date:%Y-%m-%d})**",
+    )
+    if not latest.empty:
+        metric_cols = st.columns(len(latest))
+        for col, (label, value) in zip(metric_cols, latest.items()):
+            col.metric(label, f"{value:.2f}%")
+
+    options = [label for label, _ in MARKET_PERIOD_OPTIONS]
+    option_mapping = {label: value for label, value in MARKET_PERIOD_OPTIONS}
+    period_label = st.radio(
+        "Range",
+        options,
+        horizontal=True,
+        key="market_period",
+    )
+    period_months = _segment_months(option_mapping[period_label])
+
+    market_df = _filter_market_dataframe(market_df_all, period_months)
+    if market_df.empty:
+        st.info("Filtered market data is not available for the selected range.")
+        return
+
+    _render_market_chart(market_df)
+
+    table = market_df.sort_index(ascending=False).head(12).reset_index()
+    table["Date"] = table["Date"].dt.date
+    st.dataframe(table, width="stretch")
+
+
+logger.debug("Market helpers module initialized.")
+
+__all__ = [
+    "render_market_tab",
+    "get_api_key",
+]
+
+__description__ = """
+Helpers for fetching FRED data, rendering the market chart, and displaying latest rates.
+"""