glidepath 0.2.0__py3-none-any.whl

glidepath/__init__.py

@@ -0,0 +1,3 @@
+"""glidepath: a desktop retirement and investment planner (UK-first)."""
+
+__version__ = "0.1.0"

glidepath/app/__init__.py

@@ -0,0 +1,364 @@
+"""UI-agnostic application layer (roadmap 8.1 to 8.3; planning §4.7).
+
+View models, user-facing copy (including the §1 disclaimer), display
+formatting, form parsing, session state, and first-run state for any
+UI shell. Everything here is plain typed Python over the scenario
+layer and engine — no Qt imports (guard test), no assumption of a
+desktop — so a future web shell can reuse it unchanged.
+"""
+
+from glidepath.app.backtest import (
+    BACKTEST_NO_PLAN_MESSAGE,
+    BACKTEST_RUNNING_MESSAGE,
+    BACKTEST_STALE_MESSAGE,
+    NO_BACKTEST_MESSAGE,
+    BacktestMetric,
+    BacktestPanelViewModel,
+    build_backtest_panel,
+    state_with_backtest,
+)
+from glidepath.app.charts import (
+    CHART_VIEW_LABEL,
+    DEFAULT_CHART_BASIS,
+    MONTE_CARLO_CHART_TITLE,
+    NO_PROJECTION_MESSAGE,
+    RUN_FAILED_PREFIX,
+    TABLE_VIEW_LABEL,
+    ChartBand,
+    ChartBasisOption,
+    ChartFill,
+    ChartSeries,
+    ChartSpec,
+    ChartsViewModel,
+    ChartTable,
+    bar_tooltip,
+    basis_from_key,
+    build_charts_view_model,
+    chart_table,
+    fill_tooltip,
+)
+from glidepath.app.copy import (
+    ABOUT_TITLE,
+    APP_NAME,
+    DATE_PICKER_TOOLTIP,
+    DISCLAIMER_ACCEPT_LABEL,
+    DISCLAIMER_BODY,
+    DISCLAIMER_DECLINE_LABEL,
+    DISCLAIMER_TITLE,
+    HELP_GUIDE_INTRO,
+    HELP_GUIDE_SECTIONS,
+    HELP_GUIDE_TITLE,
+    HELP_MENU_LABEL,
+)
+from glidepath.app.display import (
+    format_date,
+    format_money,
+    format_percent,
+    format_recorded,
+    format_value,
+)
+from glidepath.app.drawdown import (
+    DRAWDOWN_AGE_MESSAGE,
+    DRAWDOWN_NO_PLAN_MESSAGE,
+    DRAWDOWN_RUNNING_MESSAGE,
+    DRAWDOWN_STALE_MESSAGE,
+    DRAWDOWN_SUCCESS_MESSAGE,
+    NO_DRAWDOWN_MESSAGE,
+    DrawdownAnswer,
+    DrawdownPanelViewModel,
+    DrawdownRequest,
+    build_drawdown_panel,
+    state_with_drawdown,
+)
+from glidepath.app.example import example_facts_form_data
+from glidepath.app.exports import (
+    NOTHING_TO_EXPORT_MESSAGE,
+    REPORT_EXPORT_FAILED_PREFIX,
+    REPORT_NOT_WRITTEN_MESSAGE,
+    ExportOutcome,
+    PlanReport,
+    ReportRequest,
+    build_plan_report,
+    cash_flow_csv,
+    chart_resource_name,
+    export_cash_flow_csv,
+    plan_display_name,
+    report_exported_message,
+)
+from glidepath.app.files import (
+    NOTHING_TO_SAVE_MESSAGE,
+    UNSAVED_CHANGES_PROMPT,
+    UNSAVED_CHANGES_TITLE,
+    LoadOutcome,
+    SaveOutcome,
+    document_from_state,
+    has_unsaved_changes,
+    load_plan_state,
+    save_plan_state,
+)
+from glidepath.app.firstrun import (
+    FirstRunState,
+    default_state_path,
+    load_state,
+    record_disclaimer_acknowledged,
+    record_last_plan_path,
+)
+from glidepath.app.forms import (
+    ENTITY_ID_KEY,
+    ChoiceOption,
+    FactsFormData,
+    FactsFormResult,
+    FactsFormViewModel,
+    FieldKind,
+    FieldSpec,
+    FormError,
+    PlanEntityIds,
+    SectionSpec,
+    build_facts_form_view_model,
+    facts_form_data_from_household,
+    form_cannot_represent,
+    format_form_errors,
+    parse_facts_form,
+    plan_entity_ids,
+)
+from glidepath.app.inspector import (
+    AssumptionRow,
+    DecisionRow,
+    FactRow,
+    InspectorViewModel,
+    RollForwardRow,
+    StructureRow,
+    build_inspector_view_model,
+)
+from glidepath.app.montecarlo import (
+    DEFAULT_RUN_MODE,
+    MONTE_CARLO_NO_PLAN_MESSAGE,
+    MONTE_CARLO_PATHS_MESSAGE,
+    MONTE_CARLO_RUNNING_MESSAGE,
+    MONTE_CARLO_SEED_MESSAGE,
+    MONTE_CARLO_STALE_MESSAGE,
+    NO_MONTE_CARLO_MESSAGE,
+    MonteCarloMetric,
+    MonteCarloPanelViewModel,
+    RunModeOption,
+    monte_carlo_running_status,
+    path_pool,
+    run_mode_from_key,
+    run_mode_key,
+    state_with_monte_carlo,
+)
+from glidepath.app.plan import (
+    OVERRIDE_SOURCE,
+    OverrideOutcome,
+    PlanState,
+    facts_saved_message,
+    initial_plan_state,
+    state_marked_saved,
+    state_with_household,
+    state_with_override,
+    state_with_scenarios,
+)
+from glidepath.app.retirement import (
+    NO_RETIREMENT_MESSAGE,
+    RETIREMENT_NO_INCOME_MESSAGE,
+    RETIREMENT_NO_PLAN_MESSAGE,
+    RETIREMENT_RATE_MESSAGE,
+    RETIREMENT_RUNNING_MESSAGE,
+    RETIREMENT_STALE_MESSAGE,
+    RETIREMENT_SUCCESS_MESSAGE,
+    RetirementAnswer,
+    RetirementPanelViewModel,
+    RetirementRequest,
+    build_retirement_panel,
+    state_with_retirement,
+)
+from glidepath.app.scenarios import (
+    DEFAULT_COMPARISON_METRIC_KEY,
+    ComparisonMetricOption,
+    OverrideRow,
+    ScenarioItem,
+    ScenariosViewModel,
+    TargetOption,
+    build_scenarios_view_model,
+    metric_from_key,
+    scenario_target_options,
+    state_with_scenario_added,
+    state_with_scenario_override,
+    state_without_scenario,
+    state_without_scenario_override,
+)
+from glidepath.app.shell import (
+    AboutViewModel,
+    DisclaimerViewModel,
+    FileMenuViewModel,
+    HelpGuideViewModel,
+    HelpSectionViewModel,
+    ShellViewModel,
+    build_shell_view_model,
+    should_show_disclaimer,
+)
+from glidepath.core import ReportBasis
+
+__all__ = [
+    "ABOUT_TITLE",
+    "APP_NAME",
+    "BACKTEST_NO_PLAN_MESSAGE",
+    "BACKTEST_RUNNING_MESSAGE",
+    "BACKTEST_STALE_MESSAGE",
+    "CHART_VIEW_LABEL",
+    "DATE_PICKER_TOOLTIP",
+    "DEFAULT_CHART_BASIS",
+    "DEFAULT_COMPARISON_METRIC_KEY",
+    "DEFAULT_RUN_MODE",
+    "DISCLAIMER_ACCEPT_LABEL",
+    "DISCLAIMER_BODY",
+    "DISCLAIMER_DECLINE_LABEL",
+    "DISCLAIMER_TITLE",
+    "DRAWDOWN_AGE_MESSAGE",
+    "DRAWDOWN_NO_PLAN_MESSAGE",
+    "DRAWDOWN_RUNNING_MESSAGE",
+    "DRAWDOWN_STALE_MESSAGE",
+    "DRAWDOWN_SUCCESS_MESSAGE",
+    "ENTITY_ID_KEY",
+    "HELP_GUIDE_INTRO",
+    "HELP_GUIDE_SECTIONS",
+    "HELP_GUIDE_TITLE",
+    "HELP_MENU_LABEL",
+    "MONTE_CARLO_CHART_TITLE",
+    "MONTE_CARLO_NO_PLAN_MESSAGE",
+    "MONTE_CARLO_PATHS_MESSAGE",
+    "MONTE_CARLO_RUNNING_MESSAGE",
+    "MONTE_CARLO_SEED_MESSAGE",
+    "MONTE_CARLO_STALE_MESSAGE",
+    "NOTHING_TO_EXPORT_MESSAGE",
+    "NOTHING_TO_SAVE_MESSAGE",
+    "NO_BACKTEST_MESSAGE",
+    "NO_DRAWDOWN_MESSAGE",
+    "NO_MONTE_CARLO_MESSAGE",
+    "NO_PROJECTION_MESSAGE",
+    "NO_RETIREMENT_MESSAGE",
+    "OVERRIDE_SOURCE",
+    "REPORT_EXPORT_FAILED_PREFIX",
+    "REPORT_NOT_WRITTEN_MESSAGE",
+    "RETIREMENT_NO_INCOME_MESSAGE",
+    "RETIREMENT_NO_PLAN_MESSAGE",
+    "RETIREMENT_RATE_MESSAGE",
+    "RETIREMENT_RUNNING_MESSAGE",
+    "RETIREMENT_STALE_MESSAGE",
+    "RETIREMENT_SUCCESS_MESSAGE",
+    "RUN_FAILED_PREFIX",
+    "TABLE_VIEW_LABEL",
+    "UNSAVED_CHANGES_PROMPT",
+    "UNSAVED_CHANGES_TITLE",
+    "AboutViewModel",
+    "AssumptionRow",
+    "BacktestMetric",
+    "BacktestPanelViewModel",
+    "ChartBand",
+    "ChartBasisOption",
+    "ChartFill",
+    "ChartSeries",
+    "ChartSpec",
+    "ChartTable",
+    "ChartsViewModel",
+    "ChoiceOption",
+    "ComparisonMetricOption",
+    "DecisionRow",
+    "DisclaimerViewModel",
+    "DrawdownAnswer",
+    "DrawdownPanelViewModel",
+    "DrawdownRequest",
+    "ExportOutcome",
+    "FactRow",
+    "FactsFormData",
+    "FactsFormResult",
+    "FactsFormViewModel",
+    "FieldKind",
+    "FieldSpec",
+    "FileMenuViewModel",
+    "FirstRunState",
+    "FormError",
+    "HelpGuideViewModel",
+    "HelpSectionViewModel",
+    "InspectorViewModel",
+    "LoadOutcome",
+    "MonteCarloMetric",
+    "MonteCarloPanelViewModel",
+    "OverrideOutcome",
+    "OverrideRow",
+    "PlanEntityIds",
+    "PlanReport",
+    "PlanState",
+    "ReportBasis",
+    "ReportRequest",
+    "RetirementAnswer",
+    "RetirementPanelViewModel",
+    "RetirementRequest",
+    "RollForwardRow",
+    "RunModeOption",
+    "SaveOutcome",
+    "ScenarioItem",
+    "ScenariosViewModel",
+    "SectionSpec",
+    "ShellViewModel",
+    "StructureRow",
+    "TargetOption",
+    "bar_tooltip",
+    "basis_from_key",
+    "build_backtest_panel",
+    "build_charts_view_model",
+    "build_drawdown_panel",
+    "build_facts_form_view_model",
+    "build_inspector_view_model",
+    "build_plan_report",
+    "build_retirement_panel",
+    "build_scenarios_view_model",
+    "build_shell_view_model",
+    "cash_flow_csv",
+    "chart_resource_name",
+    "chart_table",
+    "default_state_path",
+    "document_from_state",
+    "example_facts_form_data",
+    "export_cash_flow_csv",
+    "facts_form_data_from_household",
+    "facts_saved_message",
+    "fill_tooltip",
+    "form_cannot_represent",
+    "format_date",
+    "format_form_errors",
+    "format_money",
+    "format_percent",
+    "format_recorded",
+    "format_value",
+    "has_unsaved_changes",
+    "initial_plan_state",
+    "load_plan_state",
+    "load_state",
+    "metric_from_key",
+    "monte_carlo_running_status",
+    "parse_facts_form",
+    "path_pool",
+    "plan_display_name",
+    "plan_entity_ids",
+    "record_disclaimer_acknowledged",
+    "record_last_plan_path",
+    "report_exported_message",
+    "run_mode_from_key",
+    "run_mode_key",
+    "save_plan_state",
+    "scenario_target_options",
+    "should_show_disclaimer",
+    "state_marked_saved",
+    "state_with_backtest",
+    "state_with_drawdown",
+    "state_with_household",
+    "state_with_monte_carlo",
+    "state_with_override",
+    "state_with_retirement",
+    "state_with_scenario_added",
+    "state_with_scenario_override",
+    "state_with_scenarios",
+    "state_without_scenario",
+    "state_without_scenario_override",
+]

glidepath/app/backtest.py

@@ -0,0 +1,281 @@
+"""Historical backtest in the shell: transition and panel (roadmap 9.18).
+
+The core window runner (:func:`~glidepath.core.run_windows`) surfaced
+per planning §4.7 as a charts-screen card next to the Monte Carlo
+panel: an explicit Run action replays the plan over every rolling
+window of the shipped historical return series
+(``returns_history.toml``, the §5.3 provenance pattern), and the
+readout mirrors the Monte Carlo metrics — success rate over windows,
+the worst starting year, ending-pot percentiles — so the two surfaces
+read side by side. Results are reproducible: no randomness is
+involved, and every plan-changing transition routes through
+:func:`~glidepath.app.plan.replanned_state`, which drops the held
+result, so a stale backtest can never be shown against a changed
+plan.
+"""
+
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING, Any, Final
+
+from glidepath.app.display import format_money, format_percent
+from glidepath.app.montecarlo import BAND_SPECS, SUCCESS_RATE_LABEL
+from glidepath.app.plan import PlanState, region_for, replanned_state
+from glidepath.core import Money, RunConfig, run_windows
+from glidepath.regions.uk import load_returns_history
+
+if TYPE_CHECKING:
+    from datetime import date
+    from decimal import Decimal
+
+    from glidepath.core import BacktestResult, WindowOutcome
+
+BACKTEST_HEADING: Final = "Historical backtest"
+
+RUN_BACKTEST_LABEL: Final = "Run backtest"
+
+NO_BACKTEST_MESSAGE: Final = (
+    "No backtest yet — press Run backtest to replay the plan over every"
+    " historical starting year."
+)
+
+BACKTEST_NO_PLAN_MESSAGE: Final = (
+    "Save facts on the Facts tab before running a backtest."
+)
+
+BACKTEST_FAILED_PREFIX: Final = "The backtest failed: "
+
+BACKTEST_RUNNING_MESSAGE: Final = "Running historical backtest…"
+
+BACKTEST_STALE_MESSAGE: Final = (
+    "Backtest result discarded — the plan changed while it ran."
+)
+
+WINDOWS_LABEL: Final = "Windows"
+
+WORST_WINDOW_LABEL: Final = "Worst starting year"
+
+BEST_WINDOW_LABEL: Final = "Best starting year"
+
+BACKTEST_YEAR_LABEL: Final = "Show starting year"
+
+BACKTEST_YEAR_TOOLTIP_NO_RUN: Final = (
+    "Run the backtest first, then enter a historical starting year to"
+    " draw its balance path on the balances chart."
+)
+
+
+@dataclass(frozen=True)
+class BacktestMetric:
+    """One backtest readout row: a label and its formatted value."""
+
+    label: str
+    value: str
+
+
+@dataclass(frozen=True)
+class BacktestPanelViewModel:
+    """The historical-backtest card on the charts screen (roadmap 9.18).
+
+    ``message`` carries the no-run or failure copy; it is blank
+    whenever ``metrics`` is populated. The card's one input is the
+    starting-year picker: ``year_value`` echoes the raw text the shell
+    captured (presentation state, not part of any run),
+    ``year_placeholder`` shows the valid span greyed inside the empty
+    box (what input is expected), ``year_tooltip`` explains what an
+    entry will draw (what the control is for), and ``year_message``
+    says why a non-blank entry drew no trajectory — it never displaces
+    the metrics.
+    """
+
+    heading: str
+    run_label: str
+    year_label: str
+    year_value: str
+    year_placeholder: str
+    year_tooltip: str
+    year_message: str
+    metrics: tuple[BacktestMetric, ...]
+    message: str
+
+
+def state_with_backtest(state: PlanState, *, today: date) -> PlanState:
+    """The state after replaying the plan over every historical window.
+
+    Anything unusable — no plan, a horizon the series cannot cover, an
+    engine rejection — folds into ``backtest_error`` on the returned
+    state, never raising at a shell (the :mod:`glidepath.app.plan`
+    rule). Before the windows run, the base projection (and the
+    scenario runs with it) is recomputed at the same ``today`` through
+    :func:`~glidepath.app.plan.replanned_state` — the 9.13 rule: the
+    backtest bands and the deterministic chart they overlay must share
+    one anchor date. The run is serial by design: a full backtest is
+    around a second of work (each window is one deterministic engine
+    pass), well under the process-pool threshold the Monte Carlo
+    transition uses.
+    """
+    if state.household is None:
+        return _with_backtest_error(state, BACKTEST_NO_PLAN_MESSAGE)
+    base = replanned_state(
+        state.assumptions,
+        state.household,
+        state.scenarios,
+        today=today,
+        modified=state.modified,
+    )
+    config = RunConfig(today=today)
+    try:
+        series = load_returns_history().series
+        result = run_windows(
+            state.household,
+            state.assumptions,
+            region_for(state.assumptions),
+            config,
+            series=series,
+        )
+    except Exception as exc:
+        # Broad by design, mirroring the Monte Carlo transition: an
+        # escape past the shell's worker thread would leave the
+        # in-flight guard held (buttons disabled, spinner running)
+        # forever, so every failure folds into the state (§4.7).
+        return _with_backtest_error(base, BACKTEST_FAILED_PREFIX + str(exc))
+    changes: dict[str, Any] = {"backtest": result, "backtest_error": None}
+    return replace(base, **changes) if changes else base
+
+
+def selected_window(
+    result: BacktestResult, year_text: str
+) -> tuple[WindowOutcome | None, str]:
+    """The window the raw starting-year text picks, or why none does.
+
+    A blank entry picks nothing silently; anything else must name one
+    of the result's starting years. The message names the valid span,
+    so a miss teaches the range.
+    """
+    text = year_text.strip()
+    if not text:
+        return None, ""
+    first = result.outcomes[0].start_year
+    last = result.outcomes[-1].start_year
+    miss = f"No window starts in {text} — starting years run {first} to {last}."
+    try:
+        year = int(text, 10)
+    except ValueError:
+        return None, miss
+    outcome = next(
+        (entry for entry in result.outcomes if entry.start_year == year), None
+    )
+    if outcome is None:
+        return None, miss
+    return outcome, ""
+
+
+def build_backtest_panel(
+    state: PlanState,
+    *,
+    ending_pot_deflator: Decimal | None,
+    basis_suffix: str,
+    year_text: str = "",
+) -> BacktestPanelViewModel:
+    """The historical-backtest card for the charts screen (9.18).
+
+    ``ending_pot_deflator`` is the final period's balance deflator in
+    the screen's basis (1 under nominal) — every window shares the
+    run's one assumed CPI path (planning §5.2), so the deterministic
+    report's deflator presents the window pots too; ``None`` (no
+    projection to read it from) leaves the metrics unbuilt.
+    ``basis_suffix`` names the basis on the money labels. ``year_text``
+    is the starting-year picker's raw text; with a held result it is
+    vetted through :func:`selected_window` so the card can say why a
+    miss drew nothing.
+    """
+    result = state.backtest
+    metrics: tuple[BacktestMetric, ...] = ()
+    message = ""
+    year_placeholder = ""
+    year_tooltip = BACKTEST_YEAR_TOOLTIP_NO_RUN
+    year_message = ""
+    if state.backtest_error is not None:
+        message = state.backtest_error
+    elif result is None or ending_pot_deflator is None:
+        message = NO_BACKTEST_MESSAGE
+    else:
+        metrics = _metrics(result, ending_pot_deflator, basis_suffix)
+        first = result.outcomes[0].start_year
+        last = result.outcomes[-1].start_year
+        year_placeholder = f"{first}-{last}"
+        year_tooltip = (
+            "Draw one historical starting year's balance path on the"
+            " balances chart, alongside the worst and best starting"
+            f" years. Enter a year from {first} to {last}."
+        )
+        _, year_message = selected_window(result, year_text)
+    return BacktestPanelViewModel(
+        heading=BACKTEST_HEADING,
+        run_label=RUN_BACKTEST_LABEL,
+        year_label=BACKTEST_YEAR_LABEL,
+        year_value=year_text,
+        year_placeholder=year_placeholder,
+        year_tooltip=year_tooltip,
+        year_message=year_message,
+        metrics=metrics,
+        message=message,
+    )
+
+
+def _window_value(
+    outcome: WindowOutcome, ending_pot_deflator: Decimal, basis_suffix: str
+) -> str:
+    """One starting year with how its window ended.
+
+    A ruined window names the plan-calendar year the money ran out —
+    the year the charts' x axis carries — and a surviving one its
+    ending pot, so the row reads against the chart either way.
+    """
+    shortfall = outcome.first_shortfall_period
+    if shortfall is not None:
+        return f"{outcome.start_year} — money ran out in {shortfall.start.year}"
+    presented = Money(outcome.ending_balance.amount / ending_pot_deflator).quantized()
+    return (
+        f"{outcome.start_year} — ending pot {format_money(presented)} ({basis_suffix})"
+    )
+
+
+def _metrics(
+    result: BacktestResult, ending_pot_deflator: Decimal, basis_suffix: str
+) -> tuple[BacktestMetric, ...]:
+    """The backtest readout rows, mirroring the Monte Carlo metrics."""
+    first = result.outcomes[0].start_year
+    last = result.outcomes[-1].start_year
+    rows = [
+        BacktestMetric(
+            label=SUCCESS_RATE_LABEL, value=format_percent(result.success_rate)
+        ),
+        BacktestMetric(
+            label=WINDOWS_LABEL,
+            value=f"{result.window_count} starting years ({first} to {last})",
+        ),
+        BacktestMetric(
+            label=WORST_WINDOW_LABEL,
+            value=_window_value(result.worst_window, ending_pot_deflator, basis_suffix),
+        ),
+        BacktestMetric(
+            label=BEST_WINDOW_LABEL,
+            value=_window_value(result.best_window, ending_pot_deflator, basis_suffix),
+        ),
+    ]
+    for spec in BAND_SPECS:
+        pot = result.ending_pot_percentile(spec.percentile)
+        presented = Money(pot.amount / ending_pot_deflator).quantized()
+        rows.append(
+            BacktestMetric(
+                label=f"{spec.ending_pot_label} ({basis_suffix})",
+                value=format_money(presented),
+            )
+        )
+    return tuple(rows)
+
+
+def _with_backtest_error(state: PlanState, message: str) -> PlanState:
+    """The state carrying a backtest failure, any held result dropped."""
+    changes: dict[str, Any] = {"backtest": None, "backtest_error": message}
+    return replace(state, **changes) if changes else state