# budget-coach

Personal-budgeting and money-coaching microservice: split take-home income into the 50/30/20 rule (needs/wants/savings) or any custom ratio; build a zero-based envelope budget across custom spending...


A **personal-budgeting & money-coaching microservice**. Deterministic household-finance math:
allocate income by the 50/30/20 rule, build zero-based envelope budgets, plan debt payoff with the
snowball **and** avalanche methods (and compare them), project savings growth, size an emergency
fund, and compute a savings rate. Coaching tools *also* attach an optional plain-English LLM tip and
silently fall back offline; results are tagged `mode: 'heuristic' | 'llm'`. The numbers are always
pure math — a model never affects them.

## Tools

| Tool | Input | Output |
|---|---|---|
| `allocate` | `{ income, options:{needs?,wants?,savings?} \| {ratios} }` | Income split into needs/wants/savings (50/30/20 default) or a custom ratio, summing exactly to income. **+optional tip.** |
| `envelope` | `{ income, categories }` | Zero-based envelope budget; per-category % of income + surplus/overspent/balanced status. |
| `debtSnowball` | `{ debts:[{name,balance,apr,minPayment}], extra? }` | Payoff simulation, smallest-balance-first: months to payoff, total interest, per-debt order. |
| `debtAvalanche` | `{ debts, extra? }` | Same simulation, highest-APR-first (cheapest total interest) — compare against snowball. |
| `savingsProjection` | `{ monthly, rate, months, options:{principal?} }` | Compound growth of a monthly contribution: future value, interest earned, yearly milestones. **+optional tip.** |
| `emergencyFund` | `{ expenses, options:{targetMonths?,current?} }` | Target fund = expenses × months of runway; the gap and a funding rating. |
| `savingsRate` | `{ income, savings }` | Savings ÷ income %, with a health rating against the 15–20% benchmark. |

APR accepts either a decimal (`0.1999`) or a percent (`19.99`).

## Usage

```js
import pack from './index.js';

pack.adapters.allocate({ income: 4000 });
// -> { rule:'50/30/20', buckets:{ needs:2000, wants:1200, savings:800 }, ... }

pack.adapters.debtAvalanche({
  debts: [
    { name: 'Card A', balance: 2000, apr: 22, minPayment: 50 },
    { name: 'Card B', balance: 5000, apr: 8,  minPayment: 100 },
  ],
  extra: 300,
});
// -> { strategy:'avalanche', monthsToPayoff: N, totalInterest: X, payoffOrder:[...] }
```

## DRY boundaries

- **Distinct from `finance`.** `finance` owns loan amortization, mortgages, time-value-of-money
  (PV/FV/NPV/IRR/PMT), depreciation, and currency formatting. `budget-coach` owns *household
  budgeting*, *debt-payoff ordering/comparison*, and *savings / emergency-fund planning*. The
  savings-projection compounding here is a budgeting tool (recurring contribution + goal framing),
  not a TVM primitive.
- Self-contained: the only cross-pack import is `../_shared/llm.js`.
- Pure ESM, Node built-ins only, zero npm deps.


---
Source: shared/engines/adapters/domain/budget-coach/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/budget-coach