FinPath

Free AI financial coaching that never hallucinates the math.

Comment

Inspiration

I've been interested in quantitative finance for a while — the math of compounding, amortization, and interest optimization is genuinely elegant. But this project started from a different place.

My family immigrated to the US, and I grew up watching relatives make financial decisions that hurt them not because they were careless, but because they had no access to anyone who could explain the system. A credit card at 24% APR sounds like a number. What it actually means — that a \\$5,000 balance costs you over \\$100/month in pure interest before you pay a single dollar of principal — is the kind of thing a financial advisor tells a client paying \\$200/hour. Most people never hear it.

That gap bothered me. When I saw STEMinate Hacks had a Social Good track, the idea came quickly: build the thing that should have already existed.

The Core Insight: The Engine Computes. The AI Coaches.

The thing I kept noticing about "AI finance" demos is that they let the language model do arithmetic. That's exactly backwards. LLMs are pattern-matchers that produce plausible-sounding text — ask one to amortize a loan and it might get it right, or it might hallucinate a number that's off by hundreds of dollars. When someone's rent is on the line, that isn't a corner case — it's a failure mode.

So FinPath is built around a strict separation of concerns: a deterministic TypeScript engine (lib/finance.ts) computes every number the user sees. The LLM receives those exact figures and is explicitly instructed never to recompute or contradict them. Its only job is to explain the results in plain English.

How I Built It

The Financial Engine

lib/finance.ts is a pure-function module — no I/O, no LLM, safe to run on both client and server. It does four things:

1. Financial Health Score

A 100-point transparent rubric:

$$\text{Score} = S_{\text{savings}} + S_{\text{debt}} + S_{\text{housing}} + S_{\text{emergency}}$$

Each sub-score is a clamped linear scale toward a benchmark. For example:

$$S_{\text{savings}} = 30 \cdot \text{clamp}!\left(\frac{r_{\text{savings}}}{0.20}\right), \qquad S_{\text{debt}} = 25 \cdot \text{clamp}!\left(1 - \frac{r_{\text{debt}}}{0.40}\right)$$

The thresholds — 20% savings rate, debt minimums under 15% of income, housing under 30%, 3-month emergency cushion — are grounded in standard personal finance benchmarks. Every sub-score is shown to the user with the exact metric behind it. No black box.

2. Debt Payoff Simulation

A month-by-month amortization loop comparing two strategies:

  • Avalanche — target the highest-APR debt first. Mathematically optimal: minimizes total interest paid.
  • Snowball — target the lowest-balance debt first. Behaviorally optimal: fastest first win builds momentum.

For a debt with balance \(B_t\) and monthly rate \(r = \text{APR} / 1200\), each month accrues:

$$I_t = B_t \cdot r$$

After paying the minimum \(m\) plus extra \(e\) freed from cleared debts:

$$B_{t+1} = \max!\left(0,\ B_t + I_t - m - e\right)$$

The simulation runs until all balances reach zero (capped at 600 months), recording total interest paid, months to debt-free, and each debt's exact payoff month. The interactive slider reruns the full comparison live on every drag — no debouncing needed, the simulation completes in under a millisecond.

3. Emergency Fund Timeline

Given monthly surplus \(s\) and current savings \(S_0\), months to a 3-month fund:

$$t_3 = \left\lceil \frac{\max(0,\ 3E - S_0)}{s} \right\rceil$$

where \(E\) is monthly total spending.

4. Strategy Recommendation

Avalanche is recommended unless: the interest difference is under \\$50 and snowball clears a first debt measurably faster. That edge case is where psychological momentum genuinely outweighs the math.

The AI Layer

After the engine runs server-side, the exact computed figures are injected into a structured prompt sent to Groq + LLaMA 3.3 70B. Groq's inference is fast enough to stream the narrative while the user is still reading the computed plan. The system prompt contains one hard rule: never recompute or contradict the engine's numbers. The AI narrates; the engine is the source of truth.

The Stack

Layer Technology
Framework Next.js 14 (App Router)
Language TypeScript throughout
AI inference Groq API, LLaMA 3.3 70B, streaming
Styling Tailwind + custom CSS design system
Charts Hand-built SVG — no charting library
Deploy Vercel

Challenges

Making the math trustworthy. The hardest part wasn't writing the amortization loop — it was being rigorous about edge cases. What happens when the user's minimum payments exceed their income? When two debts have identical APRs? When extra payments are zero? Each case needed explicit handling so the simulation never produces a misleading result.

The AI/engine boundary. It's tempting to let the LLM "fill in" numbers the engine didn't compute. I had to write a system prompt that was strict enough to prevent that without making the coaching feel robotic. Several iterations of prompt engineering went into getting a tone that's warm and specific without ever inventing a figure.

Demo mode without degrading the experience. I wanted judges (and users) without a Groq API key to still see the full product. The solution was making the computed plan entirely independent of the AI from the start — the dashboard renders instantly from the engine, and the coaching terminal falls back to a realistic mock narrative that mirrors what the real model would say. The math is always accurate either way.

What I Learned

The biggest lesson was about where to trust AI and where not to. I came in thinking the hard problem was the prompt engineering. The hard problem was actually the TypeScript — getting the amortization logic right, making the health score rubric defensible, ensuring the simulator handles every debt configuration correctly. Once the engine was solid, the AI layer was almost easy.

I also learned that access is a product problem as much as a technical one. A correct financial calculator is not enough — the interactive slider, the streaming narrative, the one-click demo — all of that exists because the person who needs this tool the most has the least patience for a form that asks too much.

Built With

Share this project:

Updates