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...

budget-coach

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

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.