glidepath 0.2.0__py3-none-any.whl

glidepath/app/shell.py

@@ -0,0 +1,185 @@
+"""Shell view models: everything a UI shell renders, as plain data (§4.7).
+
+Shells (PySide6 today, possibly web later) bind these to widgets and
+forward user actions back; they add no copy or formatting of their own.
+"""
+
+from dataclasses import dataclass
+from importlib import metadata
+from typing import TYPE_CHECKING
+
+from glidepath.app.copy import (
+    ABOUT_TITLE,
+    APP_NAME,
+    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.exports import (
+    CASH_FLOW_FILE_FILTER,
+    CASH_FLOW_FILE_SUFFIX,
+    EXPORT_CASH_FLOW_DIALOG_TITLE,
+    EXPORT_CASH_FLOW_LABEL,
+    EXPORT_REPORT_DIALOG_TITLE,
+    EXPORT_REPORT_LABEL,
+    REPORT_FILE_FILTER,
+    REPORT_FILE_SUFFIX,
+)
+from glidepath.app.files import (
+    FILE_MENU_LABEL,
+    OPEN_DIALOG_TITLE,
+    OPEN_PLAN_LABEL,
+    PLAN_FILE_FILTER,
+    PLAN_FILE_SUFFIX,
+    QUIT_LABEL,
+    SAVE_DIALOG_TITLE,
+    SAVE_PLAN_AS_LABEL,
+    SAVE_PLAN_LABEL,
+)
+from glidepath.app.forms import FactsFormViewModel, build_facts_form_view_model
+
+if TYPE_CHECKING:
+    from glidepath.app.firstrun import FirstRunState
+
+
+@dataclass(frozen=True)
+class FileMenuViewModel:
+    """The File menu: open, save, and export the plan (§4.5, 9.19)."""
+
+    menu_label: str
+    open_label: str
+    save_label: str
+    save_as_label: str
+    open_dialog_title: str
+    save_dialog_title: str
+    file_filter: str
+    file_suffix: str
+    export_cash_flow_label: str
+    export_cash_flow_dialog_title: str
+    export_cash_flow_filter: str
+    export_cash_flow_suffix: str
+    export_report_label: str
+    export_report_dialog_title: str
+    export_report_filter: str
+    export_report_suffix: str
+    quit_label: str
+
+
+@dataclass(frozen=True)
+class DisclaimerViewModel:
+    """The first-run disclaimer screen (§1 product requirement)."""
+
+    title: str
+    body: str
+    accept_label: str
+    decline_label: str
+
+
+@dataclass(frozen=True)
+class AboutViewModel:
+    """The About screen; repeats the disclaimer (§1 product requirement)."""
+
+    title: str
+    body: str
+
+
+@dataclass(frozen=True)
+class HelpSectionViewModel:
+    """One titled passage of the how-to-use guide."""
+
+    heading: str
+    body: str
+
+
+@dataclass(frozen=True)
+class HelpGuideViewModel:
+    """The how-to-use guide: what each part of the shell is for."""
+
+    title: str
+    intro: str
+    sections: tuple[HelpSectionViewModel, ...]
+
+
+@dataclass(frozen=True)
+class ShellViewModel:
+    """Top-level application shell."""
+
+    window_title: str
+    file_menu: FileMenuViewModel
+    help_menu_label: str
+    facts_tab_label: str
+    charts_tab_label: str
+    scenarios_tab_label: str
+    inspector_tab_label: str
+    disclaimer: DisclaimerViewModel
+    about: AboutViewModel
+    help_guide: HelpGuideViewModel
+    facts_form: FactsFormViewModel
+
+
+def _installed_version() -> str:
+    """The installed distribution version, or a placeholder outside an install."""
+    try:
+        return metadata.version(APP_NAME)
+    except metadata.PackageNotFoundError:
+        return "unknown"
+
+
+def build_shell_view_model() -> ShellViewModel:
+    """Assemble the shell view model from canonical copy and metadata."""
+    return ShellViewModel(
+        window_title=APP_NAME,
+        file_menu=FileMenuViewModel(
+            menu_label=FILE_MENU_LABEL,
+            open_label=OPEN_PLAN_LABEL,
+            save_label=SAVE_PLAN_LABEL,
+            save_as_label=SAVE_PLAN_AS_LABEL,
+            open_dialog_title=OPEN_DIALOG_TITLE,
+            save_dialog_title=SAVE_DIALOG_TITLE,
+            file_filter=PLAN_FILE_FILTER,
+            file_suffix=PLAN_FILE_SUFFIX,
+            export_cash_flow_label=EXPORT_CASH_FLOW_LABEL,
+            export_cash_flow_dialog_title=EXPORT_CASH_FLOW_DIALOG_TITLE,
+            export_cash_flow_filter=CASH_FLOW_FILE_FILTER,
+            export_cash_flow_suffix=CASH_FLOW_FILE_SUFFIX,
+            export_report_label=EXPORT_REPORT_LABEL,
+            export_report_dialog_title=EXPORT_REPORT_DIALOG_TITLE,
+            export_report_filter=REPORT_FILE_FILTER,
+            export_report_suffix=REPORT_FILE_SUFFIX,
+            quit_label=QUIT_LABEL,
+        ),
+        help_menu_label=HELP_MENU_LABEL,
+        facts_tab_label="Facts",
+        charts_tab_label="Charts",
+        scenarios_tab_label="Scenarios",
+        inspector_tab_label="Stated vs assumed",
+        disclaimer=DisclaimerViewModel(
+            title=DISCLAIMER_TITLE,
+            body=DISCLAIMER_BODY,
+            accept_label=DISCLAIMER_ACCEPT_LABEL,
+            decline_label=DISCLAIMER_DECLINE_LABEL,
+        ),
+        about=AboutViewModel(
+            title=ABOUT_TITLE,
+            body=f"{APP_NAME} {_installed_version()}\n\n{DISCLAIMER_BODY}",
+        ),
+        help_guide=HelpGuideViewModel(
+            title=HELP_GUIDE_TITLE,
+            intro=HELP_GUIDE_INTRO,
+            sections=tuple(
+                HelpSectionViewModel(heading=heading, body=body)
+                for heading, body in HELP_GUIDE_SECTIONS
+            ),
+        ),
+        facts_form=build_facts_form_view_model(),
+    )
+
+
+def should_show_disclaimer(state: FirstRunState) -> bool:
+    """The disclaimer shows on every run until an acknowledgement is recorded."""
+    return state.disclaimer_acknowledged_on is None

glidepath/app/tables.py

@@ -0,0 +1,138 @@
+"""Text form for table-valued assumption overrides (planning §1, issue #70/#71).
+
+Structured defaults are edited as plain text — one ``key = value``
+line per figure, dotted keys for nested tables — so every shipped
+default is overridable in place without a bespoke editor per table
+shape. Serialising and parsing are exact inverses over the value
+shapes the catalogue holds (planning §7): ``Decimal`` and ``int``
+figures, string tags, and nested tables. Content validation is not
+this module's job — the per-key policy parsers vet a parsed table
+before it can reach the assumption set (:mod:`glidepath.app.plan`).
+"""
+
+import re
+from collections.abc import Mapping
+from decimal import Decimal, InvalidOperation
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from glidepath.regions.uk import AssumptionValue
+
+_INT_PATTERN = re.compile(r"[+-]?\d+")
+
+
+def table_edit_text(value: Mapping[str, object]) -> str:
+    """The table as editable text: one ``key = value`` line per figure.
+
+    Nested tables flatten to dotted keys, so the text round-trips
+    through :func:`parse_table_text` for every shipped table shape.
+    """
+    lines: list[str] = []
+    _serialise(lines, value, prefix="")
+    return "\n".join(lines)
+
+
+def _serialise(lines: list[str], table: Mapping[str, object], prefix: str) -> None:
+    """Append one dotted-key line per leaf of ``table`` to ``lines``."""
+    for key, entry in table.items():
+        path = f"{prefix}{key}"
+        if isinstance(entry, Mapping):
+            _serialise(lines, entry, f"{path}.")
+        else:
+            lines.append(f"{path} = {_leaf_text(entry)}")
+
+
+def _leaf_text(entry: object) -> str:
+    """One leaf value as text that re-parses to an equal figure.
+
+    An integral ``Decimal`` (e.g. a hand-edited plan's ``1``) would
+    otherwise serialise to bare-integer text and re-parse as ``int``,
+    which the policy parsers reject — so it gains a fractional digit,
+    keeping numeric equality.
+    """
+    text = str(entry)
+    if isinstance(entry, Decimal) and _INT_PATTERN.fullmatch(text):
+        return f"{text}.0"
+    return text
+
+
+def parse_table_text(text: str) -> dict[str, AssumptionValue]:
+    """Parse ``key = value`` lines back into a nested table.
+
+    Whole numbers parse as ``int``, other numerics as ``Decimal``, and
+    anything else as a string tag — the same convention the catalogue's
+    TOML loader applies, so a serialised default parses back exactly.
+    Blank lines are ignored.
+
+    Raises:
+        ValueError: On a line without ``=``, a missing value, an empty
+            key segment, or a duplicate/conflicting key path.
+    """
+    table: dict[str, AssumptionValue] = {}
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        key_text, separator, value_text = stripped.partition("=")
+        if not separator:
+            msg = f"line {stripped!r}: expected 'key = value'"
+            raise ValueError(msg)
+        raw_value = value_text.strip()
+        if not raw_value:
+            msg = f"line {stripped!r}: missing value"
+            raise ValueError(msg)
+        path = [segment.strip() for segment in key_text.strip().split(".")]
+        if not all(path):
+            msg = f"line {stripped!r}: empty key"
+            raise ValueError(msg)
+        _assign(table, path, _parsed_scalar(raw_value))
+    return table
+
+
+def _assign(
+    table: dict[str, AssumptionValue], path: list[str], value: AssumptionValue
+) -> None:
+    """Set ``value`` at the dotted ``path`` in ``table``, refusing conflicts.
+
+    Raises:
+        ValueError: If the path duplicates an earlier line or mixes a
+            figure with a nested table at the same key.
+    """
+    node = table
+    for depth, segment in enumerate(path[:-1], start=1):
+        child = node.setdefault(segment, {})
+        if not isinstance(child, dict):
+            # A user-text conflict, not a Python typing error, so the
+            # message must travel the ValueError rejection channel.
+            msg = f"key {'.'.join(path[:depth])!r} holds both a value and a table"
+            raise ValueError(msg)  # noqa: TRY004
+        node = child
+    leaf = path[-1]
+    if leaf in node:
+        msg = f"duplicate key {'.'.join(path)!r}"
+        raise ValueError(msg)
+    node[leaf] = value
+
+
+def _parsed_scalar(raw: str) -> AssumptionValue:
+    """The typed value one line's text denotes.
+
+    Non-finite numerics (``Infinity``, ``NaN``) fall through as string
+    tags — the policy parsers reject them by type, so they can never
+    enter a table as figures.
+    """
+    if _INT_PATTERN.fullmatch(raw):
+        return int(raw)
+    try:
+        value = Decimal(raw)
+    except InvalidOperation:
+        return raw
+    if not value.is_finite():
+        return raw
+    return value
+
+
+__all__ = [
+    "parse_table_text",
+    "table_edit_text",
+]

glidepath/core/__init__.py

@@ -0,0 +1,390 @@
+"""Region-agnostic core primitives (roadmap Phase 1).
+
+The core defines value types, calendars, provenance kinds and entities.
+It never imports region code (planning §4.2) — enforced by a guard test —
+and never contains policy figures, which live in region data files.
+"""
+
+from glidepath.core.annuities import (
+    AnnuityBasis,
+    AnnuityPurchase,
+    AnnuityRateTable,
+    AnnuityType,
+    annuity_base_rate_key,
+    annuity_start_date,
+)
+from glidepath.core.backtest import (
+    BacktestResult,
+    HistoricalSeries,
+    HistoricalWindowModel,
+    HistoricalYear,
+    WindowOutcome,
+    historical_window_factory,
+    run_windows,
+)
+from glidepath.core.comparison import (
+    BASE_RUN_NAME,
+    ComparisonRow,
+    PeriodMetrics,
+    ScenarioComparison,
+    ScenarioPeriodEntry,
+    compare_scenario_results,
+    run_scenarios,
+)
+from glidepath.core.config import EngineError, RunConfig, RunMode
+from glidepath.core.contributions import (
+    AnnualAllowanceFunding,
+    AnnualAllowanceMeasurement,
+    AnnualAllowanceOutcome,
+    ContributionRuleset,
+    ContributionSchedule,
+    DbArrangementInput,
+    MemberContributionOutcome,
+    MemberContributionRequest,
+    SchemeInput,
+    SchemePayment,
+)
+from glidepath.core.engine import run
+from glidepath.core.entities import (
+    EntityId,
+    Household,
+    Person,
+    PlannedOutflow,
+    Sex,
+    SpendingPlan,
+    TaxResidencyId,
+    new_entity_id,
+    validate_household_v1,
+)
+from glidepath.core.glide import (
+    GlidePathConfig,
+    GlidePathPoint,
+    LifeStage,
+    glide_path_from_shape,
+    years_to_target_retirement,
+)
+from glidepath.core.investments import (
+    AssetAllocation,
+    AssetReturns,
+    FeesAndGrowthOutcome,
+    FeeSchedule,
+    apply_fees_and_growth,
+    period_fee,
+)
+from glidepath.core.money import Money, Rate
+from glidepath.core.montecarlo import (
+    MonteCarloResult,
+    PathOutcome,
+    PathParallelism,
+    SustainableIncomeSearch,
+    run_paths,
+    sustainable_income,
+)
+from glidepath.core.pensions import (
+    DBActiveMembership,
+    DBPension,
+    FactorTable,
+    RevaluationBasis,
+    RevaluationReference,
+    db_early_late_factor,
+    db_service_end_date,
+    db_start_date,
+    db_taken_age,
+    revaluation_factor_for_months,
+)
+from glidepath.core.periods import (
+    AgeRules,
+    AnnualCalendar,
+    FiscalCalendar,
+    Period,
+    add_months,
+    age_on,
+    birthday_in_year,
+    date_age_attained,
+    entitlement_active_fraction,
+    is_age_attained_by_period_start,
+    period_active_fraction,
+    prorata_fraction,
+    service_active_fraction,
+    whole_months_between,
+)
+from glidepath.core.provenance import (
+    Assumption,
+    AssumptionKey,
+    AssumptionReadRecorder,
+    AssumptionSet,
+    Decision,
+    Fact,
+    Provenance,
+    TrackedAssumptions,
+    decimal_assumption_value,
+    int_assumption_value,
+    mapping_assumption_value,
+)
+from glidepath.core.randomness import (
+    RandomSource,
+    SeededRandomSource,
+    derive_seed,
+)
+from glidepath.core.region import Region
+from glidepath.core.reporting import (
+    PeriodReportRow,
+    ProjectionReport,
+    ReportBasis,
+    WrapperReportBalance,
+    build_report,
+)
+from glidepath.core.results import (
+    BalanceRollForward,
+    LabelledDecision,
+    LabelledFact,
+    PeriodSnapshot,
+    PersonPeriodResult,
+    ProjectionResult,
+    RunProvenance,
+    WrapperPeriodResult,
+    collect_plan_decisions,
+    collect_plan_facts,
+)
+from glidepath.core.retirement import (
+    RetirementAgeSearch,
+    earliest_retirement_age,
+    sustainable_income_at_age,
+)
+from glidepath.core.returns import (
+    DeterministicReturnModel,
+    PeriodReturns,
+    ReturnModel,
+    ReturnModelFactory,
+    StochasticReturnModel,
+    cholesky_lower,
+    nominal_rate,
+)
+from glidepath.core.scenarios import (
+    AppliedOverride,
+    AssumptionTarget,
+    DecisionTarget,
+    DecisionTargetInfo,
+    Override,
+    OverrideTarget,
+    Scenario,
+    ScenarioError,
+    ScenarioResolution,
+    decision_target_catalogue,
+    is_scenario_valid,
+    resolve_scenario,
+    scenario_orphans,
+)
+from glidepath.core.state_pension import (
+    StatePensionEntitlement,
+    StatePensionRecord,
+    StatePensionScheme,
+    StatePensionUprating,
+    UpratingRule,
+    deferral_months,
+)
+from glidepath.core.tax import TaxInput, TaxLine, TaxResult, TaxSystem
+from glidepath.core.withdrawals import (
+    FixedPercentWithdrawalStrategy,
+    FixedRealWithdrawalStrategy,
+    GrossDraw,
+    GrossWithdrawalPlan,
+    GuardrailsWithdrawalStrategy,
+    NaturalYieldWithdrawalStrategy,
+    NetWithdrawalPlan,
+    TaxFreeCashStrategy,
+    WithdrawalPlan,
+    WithdrawalSource,
+    WithdrawalSourceId,
+    WithdrawalState,
+    WithdrawalStrategy,
+    tax_aware_order,
+)
+from glidepath.core.wrappers import (
+    ContributionCap,
+    ContributionTaxTreatment,
+    ContributionTerms,
+    GrowthTaxTreatment,
+    ReliefMechanic,
+    WithdrawalTaxTreatment,
+    Wrapper,
+    WrapperKindId,
+    WrapperRuleset,
+    WrapperTaxTreatment,
+)
+
+__all__ = [
+    "BASE_RUN_NAME",
+    "AgeRules",
+    "AnnualAllowanceFunding",
+    "AnnualAllowanceMeasurement",
+    "AnnualAllowanceOutcome",
+    "AnnualCalendar",
+    "AnnuityBasis",
+    "AnnuityPurchase",
+    "AnnuityRateTable",
+    "AnnuityType",
+    "AppliedOverride",
+    "AssetAllocation",
+    "AssetReturns",
+    "Assumption",
+    "AssumptionKey",
+    "AssumptionReadRecorder",
+    "AssumptionSet",
+    "AssumptionTarget",
+    "BacktestResult",
+    "BalanceRollForward",
+    "ComparisonRow",
+    "ContributionCap",
+    "ContributionRuleset",
+    "ContributionSchedule",
+    "ContributionTaxTreatment",
+    "ContributionTerms",
+    "DBActiveMembership",
+    "DBPension",
+    "DbArrangementInput",
+    "Decision",
+    "DecisionTarget",
+    "DecisionTargetInfo",
+    "DeterministicReturnModel",
+    "EngineError",
+    "EntityId",
+    "Fact",
+    "FactorTable",
+    "FeeSchedule",
+    "FeesAndGrowthOutcome",
+    "FiscalCalendar",
+    "FixedPercentWithdrawalStrategy",
+    "FixedRealWithdrawalStrategy",
+    "GlidePathConfig",
+    "GlidePathPoint",
+    "GrossDraw",
+    "GrossWithdrawalPlan",
+    "GrowthTaxTreatment",
+    "GuardrailsWithdrawalStrategy",
+    "HistoricalSeries",
+    "HistoricalWindowModel",
+    "HistoricalYear",
+    "Household",
+    "LabelledDecision",
+    "LabelledFact",
+    "LifeStage",
+    "MemberContributionOutcome",
+    "MemberContributionRequest",
+    "Money",
+    "MonteCarloResult",
+    "NaturalYieldWithdrawalStrategy",
+    "NetWithdrawalPlan",
+    "Override",
+    "OverrideTarget",
+    "PathOutcome",
+    "PathParallelism",
+    "Period",
+    "PeriodMetrics",
+    "PeriodReportRow",
+    "PeriodReturns",
+    "PeriodSnapshot",
+    "Person",
+    "PersonPeriodResult",
+    "PlannedOutflow",
+    "ProjectionReport",
+    "ProjectionResult",
+    "Provenance",
+    "RandomSource",
+    "Rate",
+    "Region",
+    "ReliefMechanic",
+    "ReportBasis",
+    "RetirementAgeSearch",
+    "ReturnModel",
+    "ReturnModelFactory",
+    "RevaluationBasis",
+    "RevaluationReference",
+    "RunConfig",
+    "RunMode",
+    "RunProvenance",
+    "Scenario",
+    "ScenarioComparison",
+    "ScenarioError",
+    "ScenarioPeriodEntry",
+    "ScenarioResolution",
+    "SchemeInput",
+    "SchemePayment",
+    "SeededRandomSource",
+    "Sex",
+    "SpendingPlan",
+    "StatePensionEntitlement",
+    "StatePensionRecord",
+    "StatePensionScheme",
+    "StatePensionUprating",
+    "StochasticReturnModel",
+    "SustainableIncomeSearch",
+    "TaxFreeCashStrategy",
+    "TaxInput",
+    "TaxLine",
+    "TaxResidencyId",
+    "TaxResult",
+    "TaxSystem",
+    "TrackedAssumptions",
+    "UpratingRule",
+    "WindowOutcome",
+    "WithdrawalPlan",
+    "WithdrawalSource",
+    "WithdrawalSourceId",
+    "WithdrawalState",
+    "WithdrawalStrategy",
+    "WithdrawalTaxTreatment",
+    "Wrapper",
+    "WrapperKindId",
+    "WrapperPeriodResult",
+    "WrapperReportBalance",
+    "WrapperRuleset",
+    "WrapperTaxTreatment",
+    "add_months",
+    "age_on",
+    "annuity_base_rate_key",
+    "annuity_start_date",
+    "apply_fees_and_growth",
+    "birthday_in_year",
+    "build_report",
+    "cholesky_lower",
+    "collect_plan_decisions",
+    "collect_plan_facts",
+    "compare_scenario_results",
+    "date_age_attained",
+    "db_early_late_factor",
+    "db_service_end_date",
+    "db_start_date",
+    "db_taken_age",
+    "decimal_assumption_value",
+    "decision_target_catalogue",
+    "deferral_months",
+    "derive_seed",
+    "earliest_retirement_age",
+    "entitlement_active_fraction",
+    "glide_path_from_shape",
+    "historical_window_factory",
+    "int_assumption_value",
+    "is_age_attained_by_period_start",
+    "is_scenario_valid",
+    "mapping_assumption_value",
+    "new_entity_id",
+    "nominal_rate",
+    "period_active_fraction",
+    "period_fee",
+    "prorata_fraction",
+    "resolve_scenario",
+    "revaluation_factor_for_months",
+    "run",
+    "run_paths",
+    "run_scenarios",
+    "run_windows",
+    "scenario_orphans",
+    "service_active_fraction",
+    "sustainable_income",
+    "sustainable_income_at_age",
+    "tax_aware_order",
+    "validate_household_v1",
+    "whole_months_between",
+    "years_to_target_retirement",
+]