The problem
Retail investing tools split into two camps. Screeners like Finviz give you every number and no interpretation — you're on your own to decide what a 12% gross-margin decline means. Robo-advisors give you interpretation and no transparency — a recommendation with no visible reasoning behind it.
Neither does what a real research desk does: assign the question to specialists, let them disagree, and synthesize a view you can interrogate.
Finava is that desk. Ask about a stock and fifteen specialist agents — DCF, earnings, insider flow, macro, options positioning, competitive dynamics, and more — each run their own analysis against live market data, then a lead agent synthesizes them into a single written verdict with the disagreements left visible.
What it does
| |
|---|
| Deep research | 15 specialist agents analyze a ticker in parallel, streamed live as each one finishes |
| Finava Score | A deterministic 15-factor, 6-pillar composite computed from real fundamentals — not an LLM guess |
| Interactive DCF | A real discounted-cash-flow model with adjustable assumptions, not a static number |
| Portfolio intelligence | Link a brokerage via Plaid; get position-aware analysis benchmarked against the S&P 500 |
| Investor DNA | Infers your investing style from your actual holdings and P&L, then frames every stock through that lens |
| Research board | A scored, filterable leaderboard across the S&P 500 |
How it works
A lead orchestrator decides which specialists a question actually needs, fans them out concurrently, and synthesizes their returns. Each agent is an isolated module with its own prompt, its own tools, and its own test file.
flowchart TB
Q["User question"] --> R["Router<br/><i>Haiku — classifies intent</i>"]
R --> O["Lead orchestrator<br/><i>picks the crew, fans out</i>"]
O --> A1["DCF"]
O --> A2["Earnings"]
O --> A3["Insider"]
O --> A4["Macro"]
O --> A5["Options"]
O --> A6["+ 10 more"]
A1 & A2 & A3 & A4 & A5 & A6 --> S["Synthesis<br/><i>one verdict, disagreements kept</i>"]
S --> U["Streamed to the client"]
D[("Market data<br/>Polygon · Finnhub · Alpaca<br/>SEC EDGAR · Perplexity")] -.-> A1
D -.-> A2
D -.-> A3
D -.-> A4
D -.-> A5
D -.-> A6
Models are routed per agent rather than picked globally. Each specialist runs on the model calibrated for its job, and the UI badges which one produced what — so the reasoning stays attributable:
| Brand | Role |
|---|
| Claude (Sonnet 4.6 / Haiku 4.5) | Synthesis and judgment |
| GPT-5.5 | The numbers |
| Gemini 2.5 Flash | High-volume reading |
| Grok 4.3 | Live social signal |
| Perplexity | Live web grounding |
Engineering notes
The parts that were harder than they look:
- Concurrent streaming — a headless chat engine lets multiple conversations stream simultaneously, with optimistic UI that survives a reload mid-run.
- Cost control — every LLM call is metered per user through an
AsyncLocalStorage context, with a cost-weighted credit system, an in-run kill-switch that aborts a runaway agent mid-execution, and automatic provider failover.
- Tenant isolation — agent memory and the risk cache are partitioned by user ID. A shared cache key across tenants is the kind of bug that leaks one user's portfolio into another's analysis.
- No-fabrication guardrail — a shared accuracy rule is injected into every report prompt. Agents must return an explicit Unavailable rather than inventing a plausible number, which matters more in finance than almost anywhere else.
- SSRF protection — outbound fetches for user-supplied URLs resolve and pin the IP before connecting, so a hostname can't re-resolve to a private address between check and use.
- Deterministic scoring — the Finava Score is computed from real fundamentals in plain TypeScript. Asking a language model to produce a number and calling it a score is not a score.
Verified on the current commit: 767 tests across 119 test files, 81% line coverage behind a ratchet that CI refuses to let drop, and 50 API routes.
Tech stack
Framework Next.js 16 (App Router, React 19, TypeScript)
AI OpenRouter → Claude · GPT · Gemini · Grok · Perplexity
Data Polygon · Finnhub · Alpaca · SEC EDGAR · Perplexity
Infra Firebase (Auth + Firestore) · Plaid · Stripe · Vercel
Testing Vitest with a coverage ratchet · GitHub Actions CI
Running locally
Requires Node 22+.
git clone https://github.com/LBB2005/finava.git
cd finava
npm install
cp .env.example .env.local # then fill in your keys
npm run dev
.env.example documents every variable and marks which are required. The server validates required vars at boot and refuses to start in production without them. Firebase and at least one market-data provider are needed for a useful local run; the rest degrade gracefully.
npm run lint # eslint
npm run typecheck # tsc --noEmit
npm test # vitest
npm run test:cov # vitest + coverage ratchet
CI runs all four plus a production build on every push and pull request.
Project structure
src/
├── agents/ # orchestrator, 15 specialist sub-agents, skills, tools
│ ├── ceo.ts # lead orchestrator — crew selection and synthesis
│ ├── sub-agents/ # one module + one test file per specialist
│ └── skills/ # per-agent prompts and output contracts
├── app/
│ ├── api/ # 50 route handlers
│ └── (pages)/ # stock, chat, portfolio, research, watchlist, dna
├── components/ # UI, organized by surface
├── lib/ # scoring, DCF, market-data clients, auth, metering
└── test/ # shared test setup
Disclaimer
Finava is a research tool, not an investment adviser. Nothing it produces is personalized financial advice. AI-generated analysis can be wrong, and the app labels it as such throughout. Always do your own research.
License
MIT — see LICENSE.
