Metadata-Version: 2.4
Name: householdplan
Version: 0.1.0
Summary: Generate a written household financial plan: policies, action register, assumptions, and review scaffolding
Project-URL: Homepage, https://github.com/engineerinvestor/householdplan
Project-URL: Repository, https://github.com/engineerinvestor/householdplan
Project-URL: Issues, https://github.com/engineerinvestor/householdplan/issues
Author-email: Engineer Investor <egr.investor@gmail.com>
License: MIT
License-File: LICENSE
Keywords: document-generation,financial-planning,household,investment-policy-statement,personal-finance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# householdplan

[![ci](https://github.com/engineerinvestor/householdplan/actions/workflows/ci.yml/badge.svg)](https://github.com/engineerinvestor/householdplan/actions/workflows/ci.yml)
[![pypi](https://img.shields.io/pypi/v/householdplan)](https://pypi.org/project/householdplan/)
![python](https://img.shields.io/pypi/pyversions/householdplan)
[![license](https://img.shields.io/github/license/engineerinvestor/householdplan)](LICENSE)
[![checked with mypy](https://img.shields.io/badge/mypy-strict-2a6db2)](https://mypy-lang.org/)
[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

Generate a written household financial plan: policies by domain, an action register, an
assumptions table where every value carries a rationale and a revisit trigger, and the
scaffolding to keep the plan current after it is written.

A household plan records what you do when something happens, so the decision gets made once,
in advance, rather than under pressure. Most plans go stale because nothing forces the
assumptions to be revisited and nothing records why a number was chosen. This tool generates
both parts: the document, and the review structure around it.

Thirty policy rules across eleven domains, two dependencies, no language model, and no
network access. The same inputs always produce the same document, because policy text comes
from a YAML corpus rather than from generated prose.

Educational. Not legal, tax, or investment advice.

## Install

```bash
pip install householdplan
```

Python 3.11+. Two dependencies (`pydantic`, `pyyaml`). No network access, no telemetry, no
language model: policy text comes from a YAML corpus, so the same inputs always produce the
same document.

## Use

```bash
householdplan draft examples/couple.yaml -o plan.md   # the plan document
householdplan validate plan.md                        # structural checks
householdplan scaffold -o planrepo/                   # appendices + review template
householdplan export-rules -o rules.json              # the corpus, for other runtimes
```

## What it generates

`draft` emits a seven-section document:

1. Why we manage money this way
2. Goals, in priority order
3. Policies, grouped by domain
4. Action register
5. Assumptions
6. Review and change policy
7. Appendices to write next

`scaffold` emits the layer that keeps it alive: eleven numbered appendix skeletons (`00`
Summary through `10` References) with their table headers in place, a quarterly review
template whose sections map one-to-one onto those appendices, and a review log.

## Policy domains

Cash flow, liquidity, debt, investing, taxes, equity compensation, insurance, goals,
retirement, estate and handoff, governance.

Each rule declares which households it applies to, so a solo household without equity
compensation never sees rules written for a couple with vesting stock. A rule you switch off
is recorded as a deliberate omission rather than dropped silently, which keeps a later review
from relitigating a decision that was already made.

## Rules are data

The corpus lives in YAML, one file per domain:

```yaml
- id: reserve-floor
  domain: Liquidity
  label: Cash reserve floor and what happens if it breaks
  relevant: always
  default_on: true
  inputs:
    - {key: months, label: Reserve floor, kind: num, suffix: months of essential spending}
  assumption_keys: [months]
  variants:
    - when: always
      text: "{We} hold at least {n:months} months of essential spending in {t:accounts}.
             If reserves fall below that floor, optional taxable investing pauses until
             the floor is restored."
```

`relevant` and `when` are boolean expressions over six household flags (`couple`,
`dependents`, `both_retirement_plans`, `equity_comp`, `taxable`, `near_retirement`)
combined with `and`, `or`, `not`, and parentheses. A recursive-descent parser handles them,
so a corpus file cannot execute anything and an unknown flag name fails at load.

Because the corpus is data rather than code, `export-rules` emits it as JSON for other
runtimes to render, and a single edit to a policy sentence reaches every consumer.

## Validation

`validate` runs ten structural checks: every enabled rule's inputs are bound, every
assumption has a rationale and a revisit trigger, every action has an owner and a due date,
goals are uniquely ranked, the disclaimer is present, no individualized securities advice, no
overstated certainty, every number in the prose traces to a bound input, an effective date is
set, and switched-off domains are recorded rather than dropped.

## Scope

This generates a policy document from inputs you supply. It does not run projections, pick
investments, or give individualized advice. Numbers you put in come back out with their
rationale attached; it does no arithmetic of its own.

## Related

The plan document pairs with projection tools rather than replacing them. A projection tells
you whether the numbers work; this records what you will do when they stop working.
[`planner-lab`](https://pypi.org/project/planner-lab/) consumes this package as an optional
extra and can build a plan straight from a typed case file, so the policy figures and the
memo figures come from the same source.

## License

MIT

---

`#personal-finance` `#financial-planning` `#investment-policy-statement` `#household-budget`
`#retirement-planning` `#financial-independence` `#document-generation` `#markdown`
`#python` `#pydantic` `#deterministic` `#no-llm` `#open-source-finance` `#money-management`
`#financial-literacy`
