planner-lab 0.1.0__tar.gz

planner_lab-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v8.3.2
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --all-extras
+      - run: uv run pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v8.3.2
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - run: uv sync --all-extras
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy

planner_lab-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v8.3.2
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

planner_lab-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Private working notes — never commit
+*.local.md
+CLAUDE.local.md
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+
+# Slop-lint venv (auto-created by scripts/slopcheck.sh)
+scripts/.slopvenv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Environment / secrets
+.env
+.env.*
+
+# Real financial data must never land in the repo
+data/private/
+*.ofx
+*.qfx
+
+# OS
+.DS_Store

planner_lab-0.1.0/CITATION.cff

@@ -0,0 +1,16 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "agentic-financial-planner-lab: an auditable financial planning agent framework"
+authors:
+  - family-names: Hodge
+    given-names: John
+url: "https://github.com/jman4162/agentic-financial-planner-lab"
+license: MIT
+version: 0.1.0
+date-released: 2026-07-10
+keywords:
+  - financial-planning
+  - retirement
+  - monte-carlo
+  - llm-agents
+  - model-context-protocol

planner_lab-0.1.0/CLAUDE.md

@@ -0,0 +1,90 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+uv sync --extra agent --extra planning --extra dev    # full install
+uv run pytest                          # run tests (offline; live tests are opt-in marks)
+uv run pytest tests/test_x.py::test_y  # run a single test
+uv run pytest -m ollama                # live tests against local Ollama (excluded by default)
+uv run ruff check . && uv run ruff format --check .   # lint/format
+uv run mypy                            # type check (strict)
+uv run planner-lab validate examples/cases/sample_household.yaml
+uv run planner-lab memo examples/cases/sample_household.yaml -o memo.md --yes  # needs Ollama
+uv run planner-lab analyze examples/cases/sample_household.yaml --simulate --health --allocation --yes
+uv run planner-lab import-cashflow examples/data/sample_transactions_monarch.csv --format monarch
+bash scripts/slopcheck.sh              # AI-slop lint on public prose (see Writing style)
+```
+
+The package lives in `src/planner_lab/` (src layout, hatchling). Dependencies are grouped as optional extras in `pyproject.toml` (`agent`, `planning`, `portfolio`, `mcp`, `dev`); the core must install, import, and pass its tests with no extras (pipeline/hook tests need `agent`; `test_adapter_*` files skip when their package is absent). `--research` needs the `PLANNER_LAB_RESEARCH_MCP_URL` env var; that URL lives only in the environment, never in code or docs.
+
+Known environment quirk: this repo lives under `~/Documents`, and macOS file syncing sometimes marks new `.venv` files with the BSD `hidden` flag, which makes Python skip the editable-install `.pth` file (`ModuleNotFoundError: planner_lab`). Fix: `chflags -R nohidden .venv` and delete any `*.pth` duplicates with ` 2`/` 3` suffixes in `site-packages`.
+
+## Project status
+
+Phases 1-6 built: schemas, calculators, traceability ledger, deterministic critic (nine checks), memo renderer, CLI (`validate`/`calc`/`analyze`/`memo`/`intake`/`import-cashflow`), agent pipeline with exactly two LLM call sites (memo writer, LLM critic), compliance hooks, Monte Carlo simulation adapter, generic MCP research adapter with citation enforcement, CEFR health metric, lifecycle allocation diagnostics (framed as comparisons, never instructions — `check_diagnostic_framing` guards this), and a stdlib CSV cash-flow importer with presets for common budgeting-app exports.
+
+## What this project is
+
+An experimental, provider-neutral Python framework for auditable personal-finance planning agents: it turns a user's question into a structured household case file, runs deterministic calculators and simulations against it, passes results through a critic/verifier, and emits a planning memo with explicit assumptions, citations, and an educational disclaimer.
+
+It is not a financial advisor. It does not execute trades, give individualized securities advice ("buy/sell X"), or pick stocks.
+
+## Core design rules
+
+These are architectural invariants, not suggestions:
+
+1. **The LLM never does math.** LLMs handle orchestration, question-asking, tool selection, and explanation. All arithmetic (simulations, tax math, withdrawal rates, funded ratios, portfolio metrics) comes from deterministic, seeded, testable functions the agent calls as tools.
+2. **Everything flows through a typed case file.** Household facts, goals, balance sheet, cash flow, portfolio, assumptions, and constraints live in a Pydantic model, not loose chat history. Every number in an output memo must be traceable to a case-file input or a calculator result.
+3. **Assumptions are explicit.** The assumption builder produces labeled base / conservative / optimistic sets and surfaces them before simulations run. Never silently pick optimistic assumptions.
+4. **A critic/verifier stage is mandatory** before any memo is emitted: numbers traceable, citations present, no individualized securities advice, no nominal/real confusion, certainty not overstated, missing material inputs flagged.
+5. **Integrations are optional adapters behind generic Protocol interfaces** (`ScenarioSimulator`, `ResearchSource`, `FinancialHealthMetric`, `CashflowImporter`, `PortfolioAnalyticsEngine`). Core workflow must run with no adapter installed; no specific commercial product or third-party account is ever required, and no adapter's name leaks into core classes, schemas, prompts, or diagrams.
+6. **Examples and docs use synthetic households only.** Never commit real financial data.
+
+## Intended architecture
+
+```
+User question
+  → Intake (classify task, ask high-value missing-field questions)
+  → Case file builder (typed Pydantic model)
+  → Optional data importers (generic CSV first; budgeting exports, ledgers as adapters)
+  → Assumption builder (base / conservative / optimistic)
+  → Deterministic engines (Monte Carlo simulation, tax models, portfolio diagnostics)
+  → Optional research/citation sources (MCP-based, read-only)
+  → Critic / verifier
+  → Cited planning memo (exec summary, inputs, missing data, base + stress results,
+    risks, trade-offs, next questions, methodology, disclaimer)
+```
+
+Agent topology: single orchestrator with specialist sub-agents (intake, ingestion, assumptions, simulation, research, tax/account location, portfolio risk, critic, report writer), not a decentralized swarm.
+
+Planned stack: Strands Agents SDK for the agent layer (swap-friendly interface in case LangGraph is needed later for durable/resumable state), OpenTelemetry for tracing, Typer/Rich for CLI, optional local-first LLM via Ollama. Dependencies are grouped as optional extras in `pyproject.toml` (e.g. `agent`, `mcp`, `planning`, `imports`, `market-data`, `portfolio`, `dev`) so the core installs lean.
+
+Planned dev tooling: pytest + hypothesis for tests, ruff for lint/format, mypy for types. Simulation code must be deterministic under a fixed seed so results are regression-testable.
+
+## Scope guardrails
+
+- Portfolio analysis addresses structure (allocation mix, concentration, fees, factor tilts, sequence risk). It never covers security selection or trade timing.
+- Optimization libraries (mean-variance etc.) are diagnostics and educational examples, not recommendation engines.
+- Market-data integrations fetch neutral series (asset-class returns, yields, inflation), never stock screens.
+- Prefer user-controlled file imports (CSV, plain-text ledgers) over live account aggregation.
+
+## Writing style for public-facing prose
+
+Applies to README, docs, docstrings, example output, commit messages, and PR text.
+
+- **Required pre-publish slop check.** Before committing new or substantially rewritten public prose, run `bash scripts/slopcheck.sh` (or pass explicit files). It runs two local, no-network linters: `slopscore-lint` (0-100 SlopScore with evidence spans) and `slopless` (rule findings). Both flag patterns, not authorship. Review findings by hand; do not auto-apply. Fix true positives, ignore deliberate house style. Advisory by default; `--strict` exits non-zero on high-severity findings for CI. The script auto-creates a venv at `scripts/.slopvenv` (gitignored) and never scans `*.local.md`.
+- **No em dashes** in public prose. Use commas, periods, or semicolons.
+- **No corrective-contrast framing.** Avoid "X is not Y, it is Z" / "It's not just X, it's Y" couplets and "X, not Y" section headings. State the strong version directly; the strawman rarely adds value.
+- **No puffery or significance narration.** State results; do not narrate their importance ("this is powerful because...", "crucially...").
+- **No formulaic-preamble emphasizers.** No "Importantly:", "Notably:", "At its core...", "Ultimately..." as sentence openers.
+- **No meta-narration.** No "This guide covers..." / "We'll explore..."; readers can see the headings.
+- **No hyperbolic insight-claiming.** No "Here's the thing..." / "What most people miss..." setups.
+- **Avoid reflexive AI vocabulary:** delve, crucial, pivotal, robust, seamless, leverage, showcase, underscore, tapestry, vibrant. Prefer specific, concrete, falsifiable wording.
+- Reference: [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing).
+
+## Local files
+
+Files matching `*.local.md` are private working notes and are gitignored. Never commit them or copy their contents into committed files. Read `background-info.local.md` for the full design discussion behind this document.

planner_lab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Hodge
+
+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.

planner_lab-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: planner-lab
+Version: 0.1.0
+Summary: Experimental, provider-neutral framework for auditable personal-finance planning agents
+Author: John Hodge
+License: MIT
+License-File: LICENSE
+Keywords: financial-planning,fire,llm-agents,mcp,monte-carlo,personal-finance,retirement
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: agent
+Requires-Dist: strands-agents-tools>=0.2; extra == 'agent'
+Requires-Dist: strands-agents[ollama,otel]<2,>=1.46; extra == 'agent'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0; 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'
+Provides-Extra: mcp
+Requires-Dist: httpx>=0.27; extra == 'mcp'
+Requires-Dist: mcp>=1.28; extra == 'mcp'
+Provides-Extra: planning
+Requires-Dist: fundedness>=0.2.4; extra == 'planning'
+Requires-Dist: monteplan>=0.6; extra == 'planning'
+Provides-Extra: portfolio
+Requires-Dist: lifecycle-allocation>=0.2; extra == 'portfolio'
+Description-Content-Type: text/markdown
+
+# agentic-financial-planner-lab
+
+[![ci](https://github.com/jman4162/agentic-financial-planner-lab/actions/workflows/ci.yml/badge.svg)](https://github.com/jman4162/agentic-financial-planner-lab/actions/workflows/ci.yml)
+[![license](https://img.shields.io/github/license/jman4162/agentic-financial-planner-lab)](LICENSE)
+
+An experimental, provider-neutral framework for building auditable personal-finance planning agents: a typed case file, deterministic calculators, a Monte Carlo simulation adapter, cited research through the Model Context Protocol, and a critic gate that blocks any memo whose numbers cannot be traced to a recorded computation.
+
+**The LLM never does the math.** Every dollar figure in an output memo resolves to a recorded calculator run or a case-file field, and a critic rejects the memo otherwise. This is a research and education project: not a financial advisor, no trade execution, no stock picking, no required account anywhere. Examples use synthetic households only (see the [disclaimer](#license)).
+
+![Demo of validate, calc, and import-cashflow commands](docs/assets/demo.gif)
+
+**Keywords:** financial planning, retirement readiness, Monte Carlo simulation, LLM agents, Model Context Protocol (MCP), funded ratio, safe withdrawal rate, personal finance, FIRE.
+
+## Architecture
+
+The LLM appears at exactly two points (memo drafting and a tone review); everything else is deterministic, seeded, and testable.
+
+```mermaid
+flowchart TD
+    A[Case file: typed household facts] --> B[Assumptions gate:<br/>base / conservative / optimistic,<br/>confirmed by the user]
+    B --> C[Deterministic engines]
+    C --> C1[Calculators:<br/>funded ratio, FI timeline]
+    C --> C2[Monte Carlo simulation]
+    C --> C3[CEFR health metric]
+    C --> C4[Allocation diagnostics]
+    C1 --> D[(Computation ledger:<br/>every result gets a citable id)]
+    C2 --> D
+    C3 --> D
+    C4 --> D
+    E[MCP research source:<br/>search + fetch, recorded] --> D
+    D --> F[Memo writer LLM:<br/>drafts prose, cites only<br/>ids from the ledger menu]
+    F --> G{Critic gate:<br/>9 deterministic checks<br/>+ LLM tone review}
+    G -- approved --> H[Planning memo<br/>+ audit sidecar]
+    G -- rejected twice --> I[Hard failure:<br/>no memo emitted]
+```
+
+## How it compares
+
+| | Spreadsheet / DIY | Web retirement simulators | Generic LLM chat | This project |
+|---|---|---|---|---|
+| Deterministic, seeded math | yes | yes | no | yes |
+| Explains trade-offs in prose | no | limited | yes | yes |
+| Every number traceable to a computation | manual | no | no | enforced by a critic |
+| Cited methodology sources | manual | some | fabrication risk | fetched and verified |
+| Runs fully local | yes | no | rarely | yes (Ollama) |
+| Refuses unverifiable output | n/a | n/a | no | yes |
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+uv sync --extra agent --extra dev
+```
+
+Or with pip:
+
+```bash
+pip install -e ".[agent,dev]"
+```
+
+Extras are optional by design. The core installs without any agent framework; `agent` adds the Strands SDK (with Ollama and OpenTelemetry support), `mcp` adds Model Context Protocol clients for research sources.
+
+## Try it
+
+The core works offline with no LLM:
+
+```bash
+uv run planner-lab validate examples/cases/sample_household.yaml
+uv run planner-lab calc funded-ratio --portfolio 900000 --spending 50000
+uv run planner-lab calc fi-timeline --portfolio 250000 --savings 50000 --spending 60000
+```
+
+With a local [Ollama](https://ollama.com/) server running and a tool-calling-capable model pulled (default `qwen3`; override with `OLLAMA_MODEL`):
+
+```bash
+# Full pipeline: assumptions -> calculators -> memo draft -> critic gate -> memo
+uv run planner-lab memo examples/cases/sample_household.yaml -o memo.md --yes
+
+# Add Monte Carlo simulation, the fundedness metric, and allocation diagnostics
+uv sync --all-extras
+uv run planner-lab analyze examples/cases/sample_household.yaml --simulate --health --allocation --yes
+
+# Ground the memo's methodology in cited guides from an MCP research server
+PLANNER_LAB_RESEARCH_MCP_URL=https://example.com/mcp \
+  uv run planner-lab memo examples/cases/sample_household.yaml -o memo.md --yes --research
+
+# Derive annual cash flow from a budgeting-app CSV export (no LLM involved)
+uv run planner-lab import-cashflow examples/data/sample_transactions_monarch.csv \
+  --format monarch --case my_case.yaml --write
+
+# Interactive intake chat that builds a case file
+uv run planner-lab intake -o my_case.yaml
+
+# Minimal agent-plus-tool example
+uv run python examples/hello_agent.py
+```
+
+The memo command writes the markdown memo plus a `.audit.json` sidecar holding the full computation ledger and critic report, so every number can be checked by hand. If the critic rejects the draft twice, no memo is written and the failing checks are printed.
+
+## Case studies
+
+Full walkthroughs with real generated memos, checked in verbatim:
+
+- [An on-track couple, full analysis](docs/case-studies/on-track-couple.md): simulation percentiles, the CEFR health metric, allocation diagnostics, and cited research in one run.
+- [Data gaps and CSV import](docs/case-studies/data-gaps-and-csv-import.md): missing data is disclosed, then partially filled from a transactions export with no LLM involved.
+- [A rejected memo](docs/case-studies/rejected-memo.md): what the critic gate catches, and why the worst case is no memo rather than a wrong one.
+
+## How a run works
+
+1. The case file is loaded and validated; material gaps are recorded.
+2. Base, conservative, and optimistic assumption sets are shown for confirmation (`--yes` accepts them non-interactively). Rates are real, after inflation.
+3. Deterministic calculators run per assumption set: funded ratio, years to financial independence, sustainable spending. Each result lands in the computation ledger with an id.
+4. Optionally, a Monte Carlo engine simulates each set (plus crash and sequence-risk stress runs) behind a generic `ScenarioSimulator` interface.
+5. The LLM drafts the memo, citing numbers only from the ledger menu it is given.
+6. The critic runs eight deterministic checks (traceability, no securities advice, disclaimer, assumption disclosure, missing-data disclosure, citation consistency, real/nominal labeling, certainty language) plus an LLM tone review. One revision is attempted; then the run fails.
+
+## Configuration
+
+Everything is configured through environment variables; nothing is hardcoded.
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `PLANNER_LAB_MODEL_PROVIDER` | `ollama` or `bedrock` | `ollama` |
+| `OLLAMA_HOST` / `OLLAMA_MODEL` | Local model server and model id | `http://localhost:11434` / `qwen3` |
+| `PLANNER_LAB_BEDROCK_MODEL` | Bedrock model id (provider `bedrock`) | provider default |
+| `PLANNER_LAB_RESEARCH_MCP_URL` | Streamable-HTTP MCP server exposing `search` and `fetch` tools; enables `--research` | unset |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS` | OTLP tracing target for `setup_telemetry("otlp")`; `--trace` prints spans to stdout | unset |
+
+Small local models occasionally mis-copy a number or skip a citation; the critic then rejects the memo after one revision attempt rather than emitting it. A larger model (for example `OLLAMA_MODEL=gpt-oss:20b`) makes full runs with simulation, diagnostics, and research more reliable.
+
+Optional extras: `agent` (LLM pipeline, Strands SDK), `planning` (Monte Carlo simulation, fundedness metric), `portfolio` (lifecycle allocation diagnostics), `mcp` (research sources), `dev` (tests, lint, types). The core installs with none of them.
+
+## Status
+
+Working retirement-readiness pipeline: case-file schemas, deterministic calculators, critic gate, memo renderer, interactive intake, Monte Carlo simulation, certainty-equivalent funded ratio (CEFR) metric, lifecycle allocation diagnostics, MCP research citations, and CSV cash-flow import. See `CLAUDE.md` for architecture rules.
+
+## Citation
+
+```bibtex
+@software{hodge_agentic_financial_planner_lab,
+  author  = {Hodge, John},
+  title   = {agentic-financial-planner-lab: an auditable financial planning agent framework},
+  year    = {2026},
+  url     = {https://github.com/jman4162/agentic-financial-planner-lab},
+  version = {0.1.0},
+  license = {MIT}
+}
+```
+
+## License
+
+MIT. Educational use; nothing here is financial advice.

planner_lab-0.1.0/README.md

@@ -0,0 +1,153 @@
+# agentic-financial-planner-lab
+
+[![ci](https://github.com/jman4162/agentic-financial-planner-lab/actions/workflows/ci.yml/badge.svg)](https://github.com/jman4162/agentic-financial-planner-lab/actions/workflows/ci.yml)
+[![license](https://img.shields.io/github/license/jman4162/agentic-financial-planner-lab)](LICENSE)
+
+An experimental, provider-neutral framework for building auditable personal-finance planning agents: a typed case file, deterministic calculators, a Monte Carlo simulation adapter, cited research through the Model Context Protocol, and a critic gate that blocks any memo whose numbers cannot be traced to a recorded computation.
+
+**The LLM never does the math.** Every dollar figure in an output memo resolves to a recorded calculator run or a case-file field, and a critic rejects the memo otherwise. This is a research and education project: not a financial advisor, no trade execution, no stock picking, no required account anywhere. Examples use synthetic households only (see the [disclaimer](#license)).
+
+![Demo of validate, calc, and import-cashflow commands](docs/assets/demo.gif)
+
+**Keywords:** financial planning, retirement readiness, Monte Carlo simulation, LLM agents, Model Context Protocol (MCP), funded ratio, safe withdrawal rate, personal finance, FIRE.
+
+## Architecture
+
+The LLM appears at exactly two points (memo drafting and a tone review); everything else is deterministic, seeded, and testable.
+
+```mermaid
+flowchart TD
+    A[Case file: typed household facts] --> B[Assumptions gate:<br/>base / conservative / optimistic,<br/>confirmed by the user]
+    B --> C[Deterministic engines]
+    C --> C1[Calculators:<br/>funded ratio, FI timeline]
+    C --> C2[Monte Carlo simulation]
+    C --> C3[CEFR health metric]
+    C --> C4[Allocation diagnostics]
+    C1 --> D[(Computation ledger:<br/>every result gets a citable id)]
+    C2 --> D
+    C3 --> D
+    C4 --> D
+    E[MCP research source:<br/>search + fetch, recorded] --> D
+    D --> F[Memo writer LLM:<br/>drafts prose, cites only<br/>ids from the ledger menu]
+    F --> G{Critic gate:<br/>9 deterministic checks<br/>+ LLM tone review}
+    G -- approved --> H[Planning memo<br/>+ audit sidecar]
+    G -- rejected twice --> I[Hard failure:<br/>no memo emitted]
+```
+
+## How it compares
+
+| | Spreadsheet / DIY | Web retirement simulators | Generic LLM chat | This project |
+|---|---|---|---|---|
+| Deterministic, seeded math | yes | yes | no | yes |
+| Explains trade-offs in prose | no | limited | yes | yes |
+| Every number traceable to a computation | manual | no | no | enforced by a critic |
+| Cited methodology sources | manual | some | fabrication risk | fetched and verified |
+| Runs fully local | yes | no | rarely | yes (Ollama) |
+| Refuses unverifiable output | n/a | n/a | no | yes |
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+uv sync --extra agent --extra dev
+```
+
+Or with pip:
+
+```bash
+pip install -e ".[agent,dev]"
+```
+
+Extras are optional by design. The core installs without any agent framework; `agent` adds the Strands SDK (with Ollama and OpenTelemetry support), `mcp` adds Model Context Protocol clients for research sources.
+
+## Try it
+
+The core works offline with no LLM:
+
+```bash
+uv run planner-lab validate examples/cases/sample_household.yaml
+uv run planner-lab calc funded-ratio --portfolio 900000 --spending 50000
+uv run planner-lab calc fi-timeline --portfolio 250000 --savings 50000 --spending 60000
+```
+
+With a local [Ollama](https://ollama.com/) server running and a tool-calling-capable model pulled (default `qwen3`; override with `OLLAMA_MODEL`):
+
+```bash
+# Full pipeline: assumptions -> calculators -> memo draft -> critic gate -> memo
+uv run planner-lab memo examples/cases/sample_household.yaml -o memo.md --yes
+
+# Add Monte Carlo simulation, the fundedness metric, and allocation diagnostics
+uv sync --all-extras
+uv run planner-lab analyze examples/cases/sample_household.yaml --simulate --health --allocation --yes
+
+# Ground the memo's methodology in cited guides from an MCP research server
+PLANNER_LAB_RESEARCH_MCP_URL=https://example.com/mcp \
+  uv run planner-lab memo examples/cases/sample_household.yaml -o memo.md --yes --research
+
+# Derive annual cash flow from a budgeting-app CSV export (no LLM involved)
+uv run planner-lab import-cashflow examples/data/sample_transactions_monarch.csv \
+  --format monarch --case my_case.yaml --write
+
+# Interactive intake chat that builds a case file
+uv run planner-lab intake -o my_case.yaml
+
+# Minimal agent-plus-tool example
+uv run python examples/hello_agent.py
+```
+
+The memo command writes the markdown memo plus a `.audit.json` sidecar holding the full computation ledger and critic report, so every number can be checked by hand. If the critic rejects the draft twice, no memo is written and the failing checks are printed.
+
+## Case studies
+
+Full walkthroughs with real generated memos, checked in verbatim:
+
+- [An on-track couple, full analysis](docs/case-studies/on-track-couple.md): simulation percentiles, the CEFR health metric, allocation diagnostics, and cited research in one run.
+- [Data gaps and CSV import](docs/case-studies/data-gaps-and-csv-import.md): missing data is disclosed, then partially filled from a transactions export with no LLM involved.
+- [A rejected memo](docs/case-studies/rejected-memo.md): what the critic gate catches, and why the worst case is no memo rather than a wrong one.
+
+## How a run works
+
+1. The case file is loaded and validated; material gaps are recorded.
+2. Base, conservative, and optimistic assumption sets are shown for confirmation (`--yes` accepts them non-interactively). Rates are real, after inflation.
+3. Deterministic calculators run per assumption set: funded ratio, years to financial independence, sustainable spending. Each result lands in the computation ledger with an id.
+4. Optionally, a Monte Carlo engine simulates each set (plus crash and sequence-risk stress runs) behind a generic `ScenarioSimulator` interface.
+5. The LLM drafts the memo, citing numbers only from the ledger menu it is given.
+6. The critic runs eight deterministic checks (traceability, no securities advice, disclaimer, assumption disclosure, missing-data disclosure, citation consistency, real/nominal labeling, certainty language) plus an LLM tone review. One revision is attempted; then the run fails.
+
+## Configuration
+
+Everything is configured through environment variables; nothing is hardcoded.
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `PLANNER_LAB_MODEL_PROVIDER` | `ollama` or `bedrock` | `ollama` |
+| `OLLAMA_HOST` / `OLLAMA_MODEL` | Local model server and model id | `http://localhost:11434` / `qwen3` |
+| `PLANNER_LAB_BEDROCK_MODEL` | Bedrock model id (provider `bedrock`) | provider default |
+| `PLANNER_LAB_RESEARCH_MCP_URL` | Streamable-HTTP MCP server exposing `search` and `fetch` tools; enables `--research` | unset |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS` | OTLP tracing target for `setup_telemetry("otlp")`; `--trace` prints spans to stdout | unset |
+
+Small local models occasionally mis-copy a number or skip a citation; the critic then rejects the memo after one revision attempt rather than emitting it. A larger model (for example `OLLAMA_MODEL=gpt-oss:20b`) makes full runs with simulation, diagnostics, and research more reliable.
+
+Optional extras: `agent` (LLM pipeline, Strands SDK), `planning` (Monte Carlo simulation, fundedness metric), `portfolio` (lifecycle allocation diagnostics), `mcp` (research sources), `dev` (tests, lint, types). The core installs with none of them.
+
+## Status
+
+Working retirement-readiness pipeline: case-file schemas, deterministic calculators, critic gate, memo renderer, interactive intake, Monte Carlo simulation, certainty-equivalent funded ratio (CEFR) metric, lifecycle allocation diagnostics, MCP research citations, and CSV cash-flow import. See `CLAUDE.md` for architecture rules.
+
+## Citation
+
+```bibtex
+@software{hodge_agentic_financial_planner_lab,
+  author  = {Hodge, John},
+  title   = {agentic-financial-planner-lab: an auditable financial planning agent framework},
+  year    = {2026},
+  url     = {https://github.com/jman4162/agentic-financial-planner-lab},
+  version = {0.1.0},
+  license = {MIT}
+}
+```
+
+## License
+
+MIT. Educational use; nothing here is financial advice.

planner_lab-0.1.0/docs/README.md

@@ -0,0 +1,8 @@
+# Documentation
+
+- [Case studies](case-studies/): full walkthroughs with real generated memos
+  - [An on-track couple, full analysis](case-studies/on-track-couple.md): simulation, health metric, allocation diagnostics, and cited research in one run
+  - [Data gaps and CSV import](case-studies/data-gaps-and-csv-import.md): how missing data is disclosed and filled from a transactions export
+  - [A rejected memo](case-studies/rejected-memo.md): what the critic gate catches and why failing loudly is the point
+
+For architecture rules and development commands, see [CLAUDE.md](../CLAUDE.md) and the main [README](../README.md).

planner_lab-0.1.0/docs/case-studies/data-gaps-and-csv-import.md

@@ -0,0 +1,60 @@
+# Case study: data gaps and CSV import
+
+A synthetic 38-year-old asks *"Am I on track for retirement?"* with a thin case file, [`examples/cases/incomplete_household.yaml`](../../examples/cases/incomplete_household.yaml): one pre-tax account, a gross income, and nothing else. This walkthrough shows how the system refuses to paper over what it does not know, and how a transactions CSV fills part of the gap without an LLM anywhere in the loop.
+
+## Step 1: validation names the gaps
+
+```text
+$ planner-lab validate riley_case.yaml
+Valid case file: incomplete-household
+Question: Am I on track for retirement?
+Net worth: $95,000
+Investable assets: $95,000
+Missing material fields:
+  - cash_flow.annual_expenses
+  - cash_flow.annual_savings
+  - goals.retirement.annual_amount_today
+  - portfolio
+```
+
+These dotted paths follow the case everywhere. The critic gate later requires every one of them to appear in the memo's "Important missing data" section.
+
+## Step 2: derive cash flow from a transactions export
+
+```text
+$ planner-lab import-cashflow examples/data/sample_transactions_monarch.csv \
+    --format monarch --case riley_case.yaml --write
+
+   Cash flow derived from sample_transactions_monarch.csv
+┌────────────────────┬──────────────────────────────────────┐
+│ Window             │ 2025-02-01 to 2026-02-01 (exclusive) │
+│ Complete months    │ 12                                   │
+│ Income (take-home) │ $96,000/yr                           │
+│ Expenses           │ $44,949/yr                           │
+│ Savings            │ $51,051/yr                           │
+│ Excluded transfers │ $48,000/yr                           │
+└────────────────────┴──────────────────────────────────────┘
+
+Case file cash flow (current -> imported):
+  annual_take_home: unset -> $96,000
+  annual_expenses: unset -> $44,949
+  annual_savings: unset -> $51,051
+Case file updated: riley_case.yaml
+```
+
+The importer is stdlib code with a column-mapping preset per export format. Note the excluded-transfers line: $48,000 of credit-card payments and brokerage transfers were kept out of income and expenses, because counting them would double-count spending that was already recorded at the merchant level. The window is the last 12 complete calendar months; shorter exports are annualized with an explicit warning.
+
+## Step 3: the remaining gaps stay visible
+
+```text
+$ planner-lab validate riley_case.yaml
+Missing material fields:
+  - goals.retirement.annual_amount_today
+  - portfolio
+```
+
+The cash-flow gaps cleared because the data now exists; the portfolio and the retirement spending target still need the human. Running the memo pipeline now produces [`data-gaps-memo.md`](data-gaps-memo.md), whose "Important missing data" section carries both remaining paths (the critic blocks the memo if it does not) and whose analysis leans on the expense figure as the spending proxy, labeled as such.
+
+## Why this matters
+
+A planning answer computed from unstated guesses is worse than no answer. The pipeline's rule is that gaps are data: they are recorded in the case file, disclosed in the memo, and enforced by a deterministic check rather than by hoping the model mentions them.