manyfutures 0.1.0__tar.gz

manyfutures-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Environments and tool caches
+.venv/
+.pytest_cache/
+.ruff_cache/
+
+# Editors and systems
+.DS_Store
+.idea/
+.vscode/

manyfutures-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+What each release changed, and whether it moved the headline, the chance of running short.
+
+## 0.1.0 (2026-10-26)
+
+The first release: the engine, moved here from the private dashboard it was built for, with the projected life
+table of Statistics Netherlands (CBS).
+
+### The engine, moved
+
+- **The Scenario seam** at the package's top level: `run`, `return_band`, `compare` and `inputs_that_matter` run a
+  `Scenario`, the household's decisions, from a `Start`, its money and debts on a date and the market's past
+  returns, on `Assumptions`, its facts and the model's constants, and give an `Outcome` or a `ReturnBand`.
+- **The rest under the module names it had in the dashboard**: `models`, `constants`, `data`, `places` (nine places
+  in six countries, each tax regime with its source and date), `tax`, `mortgage`, `paths`, `simulation`,
+  `analytics` and `readouts`.
+- **The household's facts have no default** (decision 9): a run is always told whose life it runs on. The model's
+  constants keep their defaults, and the Scenario's defaults are a made-up example household's choices.
+- **It reaches out to nothing**: it depends on numpy and pydantic alone, fetches nothing (the caller hands it the
+  return history), and its measures give plain records rather than tables.
+- **US inflation** bundled as `us_cpi.csv`: the CPI-U each December, FRED series CPIAUCNS (public domain), each
+  year's own taken off its return (decision 2).
+- **Its words and reasons**: the glossary (`GLOSSARY.md`), modelling decisions 1 to 35 (`docs/decisions.md`) and
+  ADR 0001, the End Age (`docs/adr/`). The README runs the example household's plan in under twenty lines.
+
+### The CBS life table
+
+- CBS's projected life table, StatLine 86246NED (the Kernprognose 2025-2070, published 16 December 2025, CC BY 4.0),
+  bundled as `life_table.csv` with its source, date, licence and reduction in its header: the chance of dying
+  before the next birthday for men and for women, at ages 0 to 99 or older, in each year from 2025 to 2070.
+- Each adult's chances are read along their own birth year at run time, so the End Age is drawn for any two birth
+  years the table covers (decision 26).
+- It replaces the actuaries' table AG2026, which is all rights reserved: AG2026 never entered this repository, and
+  a check in CI keeps it out.
+
+### The headline
+
+- The move changed no number: before its tests moved to the example household, the moved engine passed the
+  dashboard's own engine tests on the dashboard's household, 324 of 324. The CBS table, which the dashboard took up
+  just before the move, moved the End Ages a little and the headline with them.
+- The tests here are pinned on the example household and the CBS table. Its default plan runs short in about one
+  future in five: 21.7% ± 0.6 at the default 5,000 futures.

manyfutures-0.1.0/GLOSSARY.md

@@ -0,0 +1,64 @@
+# manyfutures
+
+The engine's words: what a plan, its futures and its measures are called here, in the code, the docstrings, the
+tests and the docs. Each is defined once. The modelling decisions in [docs/decisions.md](docs/decisions.md) and the
+ADRs in [docs/adr/](docs/adr/) use them. The words came with the engine from the dashboard it was built for.
+
+## Language
+
+**Scenario**:
+The household's decisions for one plan: when to retire, what to spend in retirement and how much of its spending
+it must be able to pay (Must-have Spending), the Bridge Income and until when, whether, when and where to
+downsize, and whether to sell the home as a last resort (the Last-resort Sale).
+_Avoid_: config, inputs
+
+**Retirement**:
+Leaving full-time work, at the Scenario's retirement age. From then the household's salaries fall to its Bridge
+Income and its spending becomes the Scenario's annual spending.
+_Avoid_: stopping work (the household keeps earning Bridge Income)
+
+**Bridge Income**:
+The household's gross earnings after Retirement, from consulting, contract work or a partner's job, in today's
+euros, until an age the Scenario sets.
+_Avoid_: post-retirement salary, pt salary, part-time salary
+
+**End Age**:
+The age, in whole years, at which the later of the two deaths falls on one simulated path, drawn at random for that
+path from CBS's projected life table: the plan has to last to the end of the year it falls in. The one way a death
+enters the model: nothing else in the plan changes with it.
+_Avoid_: life expectancy, horizon, death age, survivor
+
+**Must-have Spending**:
+The part of the household's baseline spending it must fund every year, in today's euros. Housing, children, the
+student loan and taxes are always paid and sit outside it.
+_Avoid_: floor, essential spending
+
+**Nice-to-have Spending**:
+Baseline spending above Must-have Spending.
+_Avoid_: discretionary spending
+
+**Money Left at the End**:
+What a simulated future leaves at the end of the year its End Age falls in, in today's euros: its liquid money (the
+portfolio and the cash reserve) plus its home's value less what is still owed on it.
+_Avoid_: terminal wealth, bequest, estate, final liquid (that is the portfolio alone)
+
+**Running Short**:
+A year in which more than a tenth of Must-have Spending goes unfunded.
+_Avoid_: shortfall, failure, depletion
+
+**Spending Rule**:
+How the household's spending is set each year from Retirement: Fixed (the chosen amount every year) or Sustainable
+(recomputed each year from what the money can carry).
+_Avoid_: amortisation, guardrail, withdrawal policy
+
+**Return Band**:
+The same run at the assumed average return and at one point lower and one point higher.
+_Avoid_: parameter band, prior, sensitivity
+
+**Last-resort Sale**:
+Selling the home when liquid money cannot cover next year's need, and renting from then on.
+_Avoid_: equity release, forced sale
+
+**Assumptions**:
+The household facts and model constants a run reads, as distinct from the Scenario's decisions.
+_Avoid_: parameters, config

manyfutures-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Pinder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

manyfutures-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: manyfutures
+Version: 0.1.0
+Summary: A household's retirement plan run over many simulated futures: the chance it runs short, and what moves it.
+Project-URL: Repository, https://github.com/thomaspinder/manyfutures
+Project-URL: Issues, https://github.com/thomaspinder/manyfutures/issues
+Author: Thomas Pinder
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2.4.4
+Requires-Dist: pydantic>=2.12.5
+Description-Content-Type: text/markdown
+
+# manyfutures
+
+Runs a household's retirement plan over many simulated futures: how often the plan runs short, the money left at
+the end, and which of its inputs matter most.
+
+The engine was built for a private dashboard and moved here in 0.1.0: the plan and its assumptions, the simulated
+futures and the measures over them, with the projected life table of Statistics Netherlands (CBS) for how long each
+future lasts. Every amount is in today's euros. The household lives in Amsterdam, under Dutch tax, unless its plan
+moves it to one of the other places the engine knows.
+
+## Install
+
+```bash
+pip install manyfutures
+```
+
+or `uv add manyfutures`. Python 3.11 or later; the only dependencies are numpy and pydantic.
+
+## An example
+
+A made-up household: two adults born in 1990 and 1992, earning 180,000 a year between them and spending 40,000, with
+one child, a home bought in 2024 with a 350,000 mortgage, and a student loan of £20,000. Its plan is the `Scenario`'s
+defaults: retiring at 58 on 40,000 a year, 30,000 of it Must-have Spending, with 40,000 a year of Bridge Income until
+the pension at 67 and a downsize to a 350,000 home.
+
+```python
+from datetime import date
+
+import numpy as np
+from manyfutures import Assumptions, Scenario, Start, readouts, run
+from manyfutures.models import Adult, MortgageTerms, Position, StudentLoanTerms
+
+household = Assumptions(  # its facts; every other Assumption is one of the engine's own model constants
+    first_adult=Adult(born=date(1990, 1, 1), life_series="men"), partner=Adult(born=1992, life_series="women"),
+    gross_income=180_000, working_years_spending=40_000, pension=20_000, child_birth_ages=(33,),
+    daycare_days_per_week=2, daycare_monthly_per_day=500, childcare_reimbursement_rate=0.33, after_school_monthly=300,
+    mortgage=MortgageTerms(rate=0.035, term=30, start=date(2024, 1, 1)),
+    student_loan=StudentLoanTerms(rate=0.03, repayment=500, repayment_day=1),
+)
+position = Position(portfolio=350_000, crypto=0, cash_buffer=30_000, home_value=520_000, mortgage_balance=340_000,
+                    student_loan=20_000)
+returns = np.random.default_rng(1).normal(0.07, 0.17, 120)  # made up: one a year, 1906 to 2025
+start = Start(today=date(2026, 6, 1), position=position, returns=returns, return_years=np.arange(1906, 2026))
+metrics = run(Scenario(), start, assumptions=household).metrics
+print("Chance of running short:", readouts.chance(metrics.chance_of_running_short, metrics.chance_of_running_short_se))
+```
+
+It prints:
+
+```text
+Chance of running short: 21.7% ± 0.6
+```
+
+About one future in five runs short: in at least one of its years more than a tenth of the Must-have Spending goes
+unfunded. The ± is one standard error of the simulation, in points, over the 5,000 futures a `Scenario` runs by
+default.
+
+The three inputs:
+
+- **`Assumptions`**: the household's facts, which have no default, and the model's constants, which do (inflation,
+  investment costs, the life table, the Running Short threshold and the rest).
+- **`Start`**: where the plan begins, the household's money and debts on a date (a `Position`) and the market's past
+  returns, each with its calendar year. Here the returns are made up; a real run is handed a history such as the
+  S&P 500's. The engine fetches nothing.
+- **`Scenario`**: the household's decisions, each with a default, so a Scenario names only those that differ.
+
+`run` gives an `Outcome`: its `metrics` (the chance of running short, how deep and for how long, the money left at
+the end, the same readouts over the futures that last to 95), the End Ages and the portfolio at each age.
+`return_band` runs the same plan with every year's return a point lower and a point higher, `compare` runs it in every
+place, and `inputs_that_matter` moves one hand-set input at a time.
+
+## The engine's words and decisions
+
+- [GLOSSARY.md](GLOSSARY.md): the words, each defined once.
+- [docs/decisions.md](docs/decisions.md): the modelling decisions, numbered as they were made, each with its rule,
+  its reason and the code and tests that hold it.
+- [docs/adr/](docs/adr/): the decisions that are not to be reopened, the End Age's among them.
+- [CHANGELOG.md](CHANGELOG.md): what each release changed, and whether it moved the headline.
+
+## Licence
+
+MIT: see [LICENSE](LICENSE). The bundled life table is CBS's (CC BY 4.0) and the US inflation the BLS's, through FRED
+(public domain); each file's header says where it comes from.

manyfutures-0.1.0/README.md

@@ -0,0 +1,83 @@
+# manyfutures
+
+Runs a household's retirement plan over many simulated futures: how often the plan runs short, the money left at
+the end, and which of its inputs matter most.
+
+The engine was built for a private dashboard and moved here in 0.1.0: the plan and its assumptions, the simulated
+futures and the measures over them, with the projected life table of Statistics Netherlands (CBS) for how long each
+future lasts. Every amount is in today's euros. The household lives in Amsterdam, under Dutch tax, unless its plan
+moves it to one of the other places the engine knows.
+
+## Install
+
+```bash
+pip install manyfutures
+```
+
+or `uv add manyfutures`. Python 3.11 or later; the only dependencies are numpy and pydantic.
+
+## An example
+
+A made-up household: two adults born in 1990 and 1992, earning 180,000 a year between them and spending 40,000, with
+one child, a home bought in 2024 with a 350,000 mortgage, and a student loan of £20,000. Its plan is the `Scenario`'s
+defaults: retiring at 58 on 40,000 a year, 30,000 of it Must-have Spending, with 40,000 a year of Bridge Income until
+the pension at 67 and a downsize to a 350,000 home.
+
+```python
+from datetime import date
+
+import numpy as np
+from manyfutures import Assumptions, Scenario, Start, readouts, run
+from manyfutures.models import Adult, MortgageTerms, Position, StudentLoanTerms
+
+household = Assumptions(  # its facts; every other Assumption is one of the engine's own model constants
+    first_adult=Adult(born=date(1990, 1, 1), life_series="men"), partner=Adult(born=1992, life_series="women"),
+    gross_income=180_000, working_years_spending=40_000, pension=20_000, child_birth_ages=(33,),
+    daycare_days_per_week=2, daycare_monthly_per_day=500, childcare_reimbursement_rate=0.33, after_school_monthly=300,
+    mortgage=MortgageTerms(rate=0.035, term=30, start=date(2024, 1, 1)),
+    student_loan=StudentLoanTerms(rate=0.03, repayment=500, repayment_day=1),
+)
+position = Position(portfolio=350_000, crypto=0, cash_buffer=30_000, home_value=520_000, mortgage_balance=340_000,
+                    student_loan=20_000)
+returns = np.random.default_rng(1).normal(0.07, 0.17, 120)  # made up: one a year, 1906 to 2025
+start = Start(today=date(2026, 6, 1), position=position, returns=returns, return_years=np.arange(1906, 2026))
+metrics = run(Scenario(), start, assumptions=household).metrics
+print("Chance of running short:", readouts.chance(metrics.chance_of_running_short, metrics.chance_of_running_short_se))
+```
+
+It prints:
+
+```text
+Chance of running short: 21.7% ± 0.6
+```
+
+About one future in five runs short: in at least one of its years more than a tenth of the Must-have Spending goes
+unfunded. The ± is one standard error of the simulation, in points, over the 5,000 futures a `Scenario` runs by
+default.
+
+The three inputs:
+
+- **`Assumptions`**: the household's facts, which have no default, and the model's constants, which do (inflation,
+  investment costs, the life table, the Running Short threshold and the rest).
+- **`Start`**: where the plan begins, the household's money and debts on a date (a `Position`) and the market's past
+  returns, each with its calendar year. Here the returns are made up; a real run is handed a history such as the
+  S&P 500's. The engine fetches nothing.
+- **`Scenario`**: the household's decisions, each with a default, so a Scenario names only those that differ.
+
+`run` gives an `Outcome`: its `metrics` (the chance of running short, how deep and for how long, the money left at
+the end, the same readouts over the futures that last to 95), the End Ages and the portfolio at each age.
+`return_band` runs the same plan with every year's return a point lower and a point higher, `compare` runs it in every
+place, and `inputs_that_matter` moves one hand-set input at a time.
+
+## The engine's words and decisions
+
+- [GLOSSARY.md](GLOSSARY.md): the words, each defined once.
+- [docs/decisions.md](docs/decisions.md): the modelling decisions, numbered as they were made, each with its rule,
+  its reason and the code and tests that hold it.
+- [docs/adr/](docs/adr/): the decisions that are not to be reopened, the End Age's among them.
+- [CHANGELOG.md](CHANGELOG.md): what each release changed, and whether it moved the headline.
+
+## Licence
+
+MIT: see [LICENSE](LICENSE). The bundled life table is CBS's (CC BY 4.0) and the US inflation the BLS's, through FRED
+(public domain); each file's header says where it comes from.

manyfutures-0.1.0/docs/adr/0001-end-age-is-the-only-way-a-death-enters-the-model.md

@@ -0,0 +1,42 @@
+---
+status: accepted
+date: 2026-10-25
+---
+
+# The End Age is the only way a death enters the model
+
+A review of the household-finance literature, made for the dashboard the engine was first built in, argued, with
+every strand and both of its critics behind it, that a household plan should carry two lives: a survivor phase with
+its own income fall, lower needs, a sale of the home at the first death, and life cover sized to the survivor's
+living standard. We decided against all of it. Each simulated path draws one **End Age** from a life table (the later
+of two draws, one per adult, from CBS's projected life table, StatLine 86246NED) and the plan has to last to it;
+nothing else in the plan changes when a death occurs, and the model never asks who died. The household the engine
+was first built for judged the survivor case not a money problem for planning, and held that if one of them died
+there would be more important things to worry about as a household than the plan. The random End Age is kept
+because the horizon still has to be random: stopping every path at a fixed age moved the headline a long way and
+hid the long-lived futures in which running short happens.
+
+The decision was made while the engine was part of that dashboard, and it travelled with the engine to this
+package in 0.1.0. Decision 26 in [the decisions](../decisions.md) holds how the End Age is drawn and what it does.
+
+## Considered options
+
+- Two lives with a survivor phase (the review's recommendation): rejected as above; also the survivor-income
+  figures the review found are American and would have been hand-set.
+- A fixed horizon at a life-expectancy age (the engine's prior behaviour): rejected because the horizon is the
+  single largest driver of the headline and the long-lived tail is where the risk sits.
+- The End Age from the current-year CBS period table: rejected because it ignores future gains in longevity and
+  cuts about five years off the life of an adult in their thirties. CBS's projected table allows for them, and is
+  what the End Age is drawn from.
+- The actuaries' projection table AG2026, which the End Age was first drawn from: rejected and replaced on
+  2026-10-25 by CBS's projected table, because AG2026 is all rights reserved and the engine is published, and CBS's
+  table is open (CC BY 4.0). The End Ages moved little. AG2026 never entered this repository, and a check in CI
+  keeps it out (`scripts/ag2026_guard.py`).
+
+## Consequences
+
+This is not to be reopened: the household the engine was first built for asked that it not be, and that holds here
+too. No survivor rules, no first-death sale, no life-cover lever, however strongly a source argues for them. The End
+Age is capped at the model's last age, 100 (`MAX_MODEL_AGE`), which truncates about one future in five of the
+example household's (`test_three_in_five_futures_last_to_95_and_six_in_seven_to_90`); lifting the cap is a
+one-constant change if wanted.

manyfutures-0.1.0/docs/adr/README.md

@@ -0,0 +1,8 @@
+# Architecture decision records
+
+A decision recorded here is settled: it says what was decided, what else was considered, and why it is not to be
+reopened. The modelling decisions, each a rule with its reason and the code that holds it, are in
+[the decisions](../decisions.md).
+
+- [0001 The End Age is the only way a death enters the model](0001-end-age-is-the-only-way-a-death-enters-the-model.md)
+  (accepted, 2026-10-25)