planner-lab 0.1.0__py3-none-any.whl

planner_lab/__init__.py

@@ -0,0 +1,9 @@
+"""planner-lab: provider-neutral framework for auditable financial planning agents."""
+
+from planner_lab.schemas.case_file import CaseFile
+from planner_lab.schemas.critic import CriticReport
+from planner_lab.schemas.memo import PlanningMemo
+
+__version__ = "0.1.0"
+
+__all__ = ["CaseFile", "CriticReport", "PlanningMemo", "__version__"]

planner_lab/adapters/__init__.py

@@ -0,0 +1,74 @@
+"""Lazy loaders for optional integrations.
+
+Each loader imports its adapter only on request and raises AdapterUnavailableError
+with the exact extra to install when the dependency is missing. Core code calls
+these loaders; it never imports adapter modules directly.
+"""
+
+from planner_lab.protocols import (
+    CashflowImporter,
+    FinancialHealthMetric,
+    PortfolioAnalyticsEngine,
+    ResearchSource,
+    ScenarioSimulator,
+)
+
+
+class AdapterUnavailableError(RuntimeError):
+    pass
+
+
+def get_cashflow_importer(fmt: str = "generic") -> CashflowImporter:
+    from planner_lab.adapters.csv_import.importer import CsvCashflowImporter
+    from planner_lab.adapters.csv_import.mapping import PRESETS
+
+    if fmt not in PRESETS:
+        raise AdapterUnavailableError(f"unknown CSV format {fmt!r}; choose from {sorted(PRESETS)}")
+    return CsvCashflowImporter(PRESETS[fmt])
+
+
+def get_simulator(name: str = "montecarlo") -> ScenarioSimulator:
+    if name == "montecarlo":
+        try:
+            from planner_lab.adapters.monteplan.simulator import MontePlanSimulator
+        except ImportError as e:
+            raise AdapterUnavailableError(
+                "Monte Carlo simulation requires the 'planning' extra: "
+                "uv sync --extra planning (needs Python >= 3.11)"
+            ) from e
+        return MontePlanSimulator()
+    raise AdapterUnavailableError(f"unknown simulator {name!r}")
+
+
+def get_research_source(url: str) -> ResearchSource:
+    try:
+        from planner_lab.adapters.mcp_research.source import MCPResearchSource
+    except ImportError as e:
+        raise AdapterUnavailableError(
+            "Research sources require the 'mcp' extra: uv sync --extra mcp"
+        ) from e
+    return MCPResearchSource(url)
+
+
+def get_health_metric(name: str = "funded") -> FinancialHealthMetric:
+    if name == "funded":
+        try:
+            from planner_lab.adapters.fundedness_metric.metric import FundednessMetric
+        except ImportError as e:
+            raise AdapterUnavailableError(
+                "Financial-health metrics require the 'planning' extra: uv sync --extra planning"
+            ) from e
+        return FundednessMetric()
+    raise AdapterUnavailableError(f"unknown health metric {name!r}")
+
+
+def get_portfolio_engine(name: str = "lifecycle") -> PortfolioAnalyticsEngine:
+    if name == "lifecycle":
+        try:
+            from planner_lab.adapters.lifecycle.allocation import LifecycleAllocationEngine
+        except ImportError as e:
+            raise AdapterUnavailableError(
+                "Portfolio analytics require the 'portfolio' extra: uv sync --extra portfolio"
+            ) from e
+        return LifecycleAllocationEngine()
+    raise AdapterUnavailableError(f"unknown portfolio engine {name!r}")

planner_lab/adapters/csv_import/__init__.py

@@ -0,0 +1,4 @@
+from planner_lab.adapters.csv_import.importer import CsvCashflowImporter
+from planner_lab.adapters.csv_import.mapping import PRESETS, ColumnMapping
+
+__all__ = ["ColumnMapping", "CsvCashflowImporter", "PRESETS"]

planner_lab/adapters/csv_import/importer.py

@@ -0,0 +1,183 @@
+"""Derive annual cash flow from a transactions CSV. Stdlib only.
+
+Positive amounts are money in, negative are money out. Transfers between the
+user's own accounts (category set or payee prefix, per mapping) are excluded
+from income and expenses: credit-card payments and brokerage buys are not
+spending; spending was already counted at the card/merchant transaction level.
+
+The window is the last 12 complete calendar months ending at the month of the
+latest transaction. Fewer complete months are annualized by scaling, with a
+warning. Transaction income is post-tax, so it maps to annual_take_home;
+annual_gross_income is left unset.
+
+Known limitation: some apps' query-style exports include both split parents
+and split children; exact-duplicate rows trigger a warning, but prefer
+per-account register exports.
+"""
+
+import csv
+import datetime
+from pathlib import Path
+
+from planner_lab.adapters.csv_import.mapping import ColumnMapping
+from planner_lab.schemas.case_file import CashFlow
+from planner_lab.schemas.results import CashflowImportResult
+
+_DATE_FORMATS = ("%m/%d/%Y", "%m/%d/%y")
+_CURRENCY_CHARS = "$€£"
+
+
+def _parse_amount(raw: str) -> float:
+    """Normalize amount strings: currency symbols, thousands separators,
+    parentheses negatives, leading formula-guard apostrophes, empty cells."""
+    text = raw.strip().strip('"').lstrip("'").strip()
+    if not text:
+        return 0.0
+    negative = text.startswith("(") and text.endswith(")")
+    if negative:
+        text = text[1:-1]
+    for char in _CURRENCY_CHARS:
+        text = text.replace(char, "")
+    text = text.replace(",", "").strip()
+    if not text:
+        return 0.0
+    value = float(text)
+    return -abs(value) if negative else value
+
+
+def _parse_date(raw: str) -> datetime.date:
+    text = raw.strip().strip('"').lstrip("'")
+    try:
+        return datetime.date.fromisoformat(text)
+    except ValueError:
+        pass
+    for fmt in _DATE_FORMATS:
+        try:
+            return datetime.datetime.strptime(text, fmt).date()
+        except ValueError:
+            continue
+    raise ValueError(f"unparseable date {raw!r}; expected ISO or US month/day/year")
+
+
+def _month_start(day: datetime.date) -> datetime.date:
+    return day.replace(day=1)
+
+
+def _shift_months(day: datetime.date, months: int) -> datetime.date:
+    total = day.year * 12 + (day.month - 1) + months
+    return datetime.date(total // 12, total % 12 + 1, 1)
+
+
+class CsvCashflowImporter:
+    name = "csv"
+
+    def __init__(self, mapping: ColumnMapping):
+        self._mapping = mapping
+
+    def _row_amount(self, row: dict[str, str]) -> float:
+        m = self._mapping
+        if m.amount is not None:
+            return _parse_amount(row[m.amount])
+        assert m.inflow is not None and m.outflow is not None
+        return _parse_amount(row[m.inflow]) - abs(_parse_amount(row[m.outflow]))
+
+    def _is_transfer(self, row: dict[str, str]) -> bool:
+        m = self._mapping
+        if m.category is not None:
+            category = (row.get(m.category) or "").strip()
+            if category in m.transfer_categories:
+                return True
+        if m.payee is not None and m.transfer_payee_prefixes:
+            payee = (row.get(m.payee) or "").strip()
+            if payee.startswith(m.transfer_payee_prefixes):
+                return True
+        return False
+
+    def import_cashflow(self, path: Path) -> CashflowImportResult:
+        m = self._mapping
+        warnings: list[str] = []
+        rows: list[tuple[datetime.date, float, bool, tuple[str, ...]]] = []
+        with open(path, encoding="utf-8-sig", newline="") as f:
+            reader = csv.DictReader(f)
+            headers = reader.fieldnames or []
+            missing = [h for h in m.required_headers() if h not in headers]
+            if missing:
+                raise ValueError(f"CSV is missing expected column(s) {missing}; found {headers}")
+            for row in reader:
+                raw_date = (row.get(m.date) or "").strip()
+                if not raw_date:
+                    continue
+                day = _parse_date(raw_date)
+                amount = self._row_amount(row)
+                dedupe_key = tuple(str(row.get(col) or "") for col in headers)
+                rows.append((day, amount, self._is_transfer(row), dedupe_key))
+        if not rows:
+            raise ValueError(f"{path} contains no transactions")
+
+        seen: set[tuple[str, ...]] = set()
+        duplicates = 0
+        for _, _, _, key in rows:
+            if key in seen:
+                duplicates += 1
+            seen.add(key)
+        if duplicates:
+            warnings.append(
+                f"{duplicates} exact-duplicate row(s) found; split-transaction exports "
+                "can double-count. Totals include them; verify the export format."
+            )
+
+        latest = max(day for day, _, _, _ in rows)
+        window_end = _month_start(latest)  # exclusive: complete months only
+        window_start = _shift_months(window_end, -12)
+        in_window = [r for r in rows if window_start <= r[0] < window_end]
+        if not in_window:
+            raise ValueError(
+                "no transactions fall inside a complete calendar month; "
+                "the export is too short to derive annual cash flow"
+            )
+
+        earliest = min(day for day, _, _, _ in in_window)
+        months_covered = min(
+            (window_end.year * 12 + window_end.month) - (earliest.year * 12 + earliest.month),
+            12,
+        )
+
+        income = expenses = transfers = 0.0
+        for _, amount, is_transfer, _ in in_window:
+            if is_transfer:
+                transfers += abs(amount)
+            elif amount >= 0:
+                income += amount
+            else:
+                expenses += -amount
+        if months_covered < 12:
+            scale = 12 / months_covered
+            income *= scale
+            expenses *= scale
+            transfers *= scale
+            warnings.append(
+                f"only {months_covered} complete month(s) of data; totals were "
+                f"annualized by scaling with 12/{months_covered}"
+            )
+
+        savings = income - expenses
+        if savings < 0:
+            warnings.append(
+                f"expenses exceed income by ${-savings:,.0f}/year; annual_savings recorded as 0"
+            )
+            savings = 0.0
+
+        return CashflowImportResult(
+            cash_flow=CashFlow(
+                annual_take_home=round(income, 2),
+                annual_expenses=round(expenses, 2),
+                annual_savings=round(savings, 2),
+            ),
+            window_start=window_start,
+            window_end=window_end,
+            months_covered=months_covered,
+            total_inflow=round(income, 2),
+            total_outflow=round(expenses, 2),
+            excluded_transfer_amount=round(transfers, 2),
+            warnings=warnings,
+        )

planner_lab/adapters/csv_import/mapping.py

@@ -0,0 +1,66 @@
+"""Column mappings for transaction-CSV exports from common budgeting apps.
+
+Header names are community-documented conventions; the importer matches by
+header name, never by position. Transfers between the user's own accounts are
+excluded from income/expense totals via category names or payee prefixes,
+following each app's own cash-flow convention.
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class ColumnMapping:
+    date: str
+    amount: str | None = None  # single signed column, XOR the inflow/outflow pair
+    inflow: str | None = None
+    outflow: str | None = None
+    category: str | None = None
+    account: str | None = None
+    payee: str | None = None
+    transfer_categories: frozenset[str] = field(default_factory=frozenset)
+    transfer_payee_prefixes: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        has_amount = self.amount is not None
+        has_pair = self.inflow is not None and self.outflow is not None
+        if has_amount == has_pair:
+            raise ValueError(
+                "mapping needs either a signed 'amount' column or an "
+                "inflow/outflow pair, not both or neither"
+            )
+
+    def required_headers(self) -> list[str]:
+        headers = [self.date]
+        headers += [c for c in (self.amount, self.inflow, self.outflow) if c is not None]
+        return headers
+
+
+PRESETS: dict[str, ColumnMapping] = {
+    "generic": ColumnMapping(date="Date", amount="Amount", category="Category", payee="Payee"),
+    "monarch": ColumnMapping(
+        date="Date",
+        amount="Amount",
+        category="Category",
+        account="Account",
+        payee="Merchant",
+        transfer_categories=frozenset({"Transfer", "Credit Card Payment", "Buy", "Sell"}),
+    ),
+    "actual": ColumnMapping(
+        date="Date",
+        amount="Amount",
+        category="Category",
+        account="Account",
+        payee="Payee",
+        transfer_payee_prefixes=("Transfer",),
+    ),
+    "ynab": ColumnMapping(
+        date="Date",
+        inflow="Inflow",
+        outflow="Outflow",
+        category="Category",
+        account="Account",
+        payee="Payee",
+        transfer_payee_prefixes=("Transfer : ",),
+    ),
+}

planner_lab/adapters/fundedness_metric/__init__.py

@@ -0,0 +1,3 @@
+from planner_lab.adapters.fundedness_metric.metric import FundednessMetric
+
+__all__ = ["FundednessMetric"]

planner_lab/adapters/fundedness_metric/metric.py

@@ -0,0 +1,175 @@
+"""FinancialHealthMetric adapter for the fundedness package (CEFR).
+
+CEFR = certainty-equivalent funded ratio: assets after tax, liquidity, and
+reliability haircuts divided by the present value of future spending streams.
+
+Mapping notes (verified against fundedness 0.2.4 source):
+- Asset values are passed GROSS; the engine applies tax haircuts internally,
+  so pre-netting traditional balances would double-tax them.
+- fundedness Liability objects are spending streams, not debt balances. The
+  retirement spending target becomes a CPI-linked essential-spending stream;
+  case debts with a minimum payment become fixed streams until paid; debts
+  without a payment become a one-year lump so they are never silently ignored.
+- Liabilities are discounted at a fixed 2% real rate (the package default,
+  a liability-matching convention). Discounting at the portfolio's expected
+  return would flatter optimistic scenarios on both sides of the ratio.
+- concentration_level is always DIVERSIFIED: the case file carries only a
+  free-text concentration note, so single-stock risk is not modeled here.
+"""
+
+import math
+
+from fundedness import Asset, BalanceSheet, Household, Liability, Person, compute_cefr
+from fundedness.models.assets import AccountType, AssetClass, LiquidityClass
+from fundedness.models.liabilities import InflationLinkage, LiabilityType
+
+from planner_lab.schemas.assumptions import AssumptionSet
+from planner_lab.schemas.case_file import CaseFile
+from planner_lab.schemas.results import MetricResult
+
+_REAL_DISCOUNT_RATE = 0.02
+
+# our account_type -> (fundedness AccountType, LiquidityClass, default AssetClass)
+_ACCOUNT_MAP: dict[str, tuple[AccountType, LiquidityClass, AssetClass]] = {
+    "taxable": (AccountType.TAXABLE, LiquidityClass.TAXABLE_INDEX, AssetClass.STOCKS),
+    "traditional": (AccountType.TAX_DEFERRED, LiquidityClass.RETIREMENT, AssetClass.STOCKS),
+    "roth": (AccountType.TAX_EXEMPT, LiquidityClass.RETIREMENT, AssetClass.STOCKS),
+    "hsa": (AccountType.HSA, LiquidityClass.RETIREMENT, AssetClass.STOCKS),
+    "cash": (AccountType.TAXABLE, LiquidityClass.CASH, AssetClass.CASH),
+    "education": (AccountType.TAX_EXEMPT, LiquidityClass.RETIREMENT, AssetClass.STOCKS),
+    "other": (AccountType.TAXABLE, LiquidityClass.TAXABLE_INDEX, AssetClass.STOCKS),
+}
+
+
+def _build_assets(case: CaseFile) -> list[Asset]:
+    """One Asset per account, or up to three per non-cash account split by the
+    portfolio's stock/bond/cash weights when a portfolio is present (fundedness
+    haircuts differ by asset class; all-stocks would overstate the haircut)."""
+    assets: list[Asset] = []
+    portfolio = case.portfolio
+    for account in case.balance_sheet.accounts:
+        account_type, liquidity, default_class = _ACCOUNT_MAP[account.account_type]
+        if portfolio is None or default_class is AssetClass.CASH:
+            assets.append(
+                Asset(
+                    name=account.name,
+                    value=account.balance,
+                    account_type=account_type,
+                    asset_class=default_class,
+                    liquidity_class=liquidity,
+                )
+            )
+            continue
+        slices = (
+            (AssetClass.STOCKS, portfolio.stock_pct, "stocks"),
+            (AssetClass.BONDS, portfolio.bond_pct, "bonds"),
+            (AssetClass.CASH, portfolio.cash_pct, "cash"),
+        )
+        for asset_class, weight, label in slices:
+            if weight <= 0:
+                continue
+            assets.append(
+                Asset(
+                    name=f"{account.name} ({label})",
+                    value=account.balance * weight,
+                    account_type=account_type,
+                    asset_class=asset_class,
+                    liquidity_class=liquidity,
+                )
+            )
+    return assets
+
+
+def _build_liabilities(case: CaseFile, current_age: int, retirement_age: int) -> list[Liability]:
+    target = case.retirement_spending_target()
+    if target is None:
+        raise ValueError(
+            "case file has no retirement spending target: set "
+            "goals[kind=retirement].annual_amount_today or cash_flow.annual_expenses"
+        )
+    liabilities = [
+        Liability(
+            name="retirement_spending",
+            liability_type=LiabilityType.ESSENTIAL_SPENDING,
+            annual_amount=target,
+            start_year=max(retirement_age - current_age, 0),
+            end_year=None,
+            inflation_linkage=InflationLinkage.CPI,
+        )
+    ]
+    for debt in case.balance_sheet.liabilities:
+        if debt.balance <= 0:
+            continue
+        if debt.minimum_annual_payment:
+            liabilities.append(
+                Liability(
+                    name=debt.name,
+                    liability_type=LiabilityType.DEBT,
+                    annual_amount=debt.minimum_annual_payment,
+                    start_year=0,
+                    end_year=math.ceil(debt.balance / debt.minimum_annual_payment),
+                    inflation_linkage=InflationLinkage.NONE,
+                )
+            )
+        else:
+            liabilities.append(
+                Liability(
+                    name=debt.name,
+                    liability_type=LiabilityType.DEBT,
+                    annual_amount=debt.balance,
+                    start_year=0,
+                    end_year=1,
+                    inflation_linkage=InflationLinkage.NONE,
+                )
+            )
+    return liabilities
+
+
+def _build_household(case: CaseFile, assumptions: AssumptionSet) -> Household:
+    current_year = case.created.year
+    members = []
+    for person in case.household.persons:
+        age = person.age_in(current_year)
+        members.append(
+            Person(
+                name=person.name,
+                age=age,
+                retirement_age=person.planned_retirement_age or 65,
+                life_expectancy=max(assumptions.plan_end_age, age + 1),
+            )
+        )
+    first = case.household.persons[0]
+    current_age = first.age_in(current_year)
+    retirement_age = first.planned_retirement_age or 65
+    return Household(
+        members=members,
+        balance_sheet=BalanceSheet(assets=_build_assets(case)),
+        liabilities=_build_liabilities(case, current_age, retirement_age),
+    )
+
+
+class FundednessMetric:
+    name = "funded"
+
+    def compute(self, case: CaseFile, assumptions: AssumptionSet) -> MetricResult:
+        household = _build_household(case, assumptions)
+        current_age = case.household.persons[0].age_in(case.created.year)
+        result = compute_cefr(
+            household=household,
+            planning_horizon=max(assumptions.plan_end_age - current_age, 1),
+            real_discount_rate=_REAL_DISCOUNT_RATE,
+            base_inflation=assumptions.inflation,
+        )
+        return MetricResult(
+            metric_name="cefr",
+            value=result.cefr,
+            components={
+                "gross_assets": result.gross_assets,
+                "total_tax_haircut": result.total_tax_haircut,
+                "total_liquidity_haircut": result.total_liquidity_haircut,
+                "total_reliability_haircut": result.total_reliability_haircut,
+                "net_assets": result.net_assets,
+                "liability_pv": result.liability_pv,
+            },
+            interpretation=result.get_interpretation(),
+        )

planner_lab/adapters/lifecycle/__init__.py

@@ -0,0 +1,3 @@
+from planner_lab.adapters.lifecycle.allocation import LifecycleAllocationEngine
+
+__all__ = ["LifecycleAllocationEngine"]

planner_lab/adapters/lifecycle/allocation.py

@@ -0,0 +1,71 @@
+"""PortfolioAnalyticsEngine adapter for the lifecycle-allocation package.
+
+Produces a Merton-style model-implied stock share with human-capital
+adjustment, as a DIAGNOSTIC benchmark against the current allocation — never a
+recommendation to trade. lifecycle-allocation's rates are real by default,
+matching this project's real-rate convention.
+"""
+
+from lifecycle_allocation import (
+    InvestorProfile,
+    recommended_stock_share,
+)
+from lifecycle_allocation import (
+    MarketAssumptions as LifecycleMarketAssumptions,  # monteplan defines the same class name
+)
+
+from planner_lab.schemas.assumptions import AssumptionSet
+from planner_lab.schemas.case_file import CaseFile
+from planner_lab.schemas.results import PortfolioDiagnostics
+
+_REAL_RISK_FREE = 0.02  # the case file carries no risk-free assumption; documented constant
+_DEFAULT_RISK_TOLERANCE = 5  # 1-10 scale; the case file carries no risk-preference field
+_DIAGNOSTIC_NOTE = (
+    "Diagnostic comparison of a lifecycle-model benchmark against the current "
+    "allocation; not a recommendation to change the allocation."
+)
+
+
+class LifecycleAllocationEngine:
+    name = "lifecycle"
+
+    def analyze(self, case: CaseFile, assumptions: AssumptionSet) -> PortfolioDiagnostics:
+        person = case.household.persons[0]
+        age = person.age_in(case.created.year)
+        retirement_age = person.planned_retirement_age or 65
+        if retirement_age <= age:
+            retirement_age = age + 1
+        wealth = case.balance_sheet.investable_assets
+        if wealth <= 0:
+            raise ValueError("lifecycle allocation needs investable assets > 0")
+
+        profile = InvestorProfile(
+            age=age,
+            retirement_age=retirement_age,
+            investable_wealth=wealth,
+            after_tax_income=case.cash_flow.annual_take_home,
+            risk_tolerance=_DEFAULT_RISK_TOLERANCE,
+        )
+        market = LifecycleMarketAssumptions(
+            mu=assumptions.expected_return_real,
+            r=_REAL_RISK_FREE,
+            sigma=assumptions.return_volatility,
+            real=True,
+        )
+        result = recommended_stock_share(profile, market)
+
+        findings: dict[str, float] = {
+            "alpha_recommended": result.alpha_recommended,
+            "alpha_star": result.alpha_star,
+            "alpha_unconstrained": result.alpha_unconstrained,
+            "human_capital": result.human_capital,
+            "hw_ratio": float(result.components["hw_ratio"]),
+            "gamma": float(result.components["gamma"]),
+        }
+        if case.portfolio is not None:
+            findings["current_stock_pct"] = case.portfolio.stock_pct
+        return PortfolioDiagnostics(
+            engine_name=self.name,
+            findings=findings,
+            notes=[result.explain, _DIAGNOSTIC_NOTE],
+        )

planner_lab/adapters/mcp_research/__init__.py

@@ -0,0 +1,3 @@
+from planner_lab.adapters.mcp_research.source import MCPResearchSource, ResearchToolError
+
+__all__ = ["MCPResearchSource", "ResearchToolError"]