README.md

metadata

title: Vitals
emoji: 🩺
colorFrom: blue
colorTo: gray
sdk: docker
app_port: 7860
pinned: false

Vitals — Your portfolio's AI health check

Five AI analyst personas examine your stock portfolio in private; you see the verdict and the treatment plan. Key in your holdings (ticker or company name + entry price, quantity optional), and get:

• Per-holding recommendations — Keep / Buy More / Trim / Sell, decided by deterministic rules from a 5-persona AI conviction panel (Value · Growth · Macro · Technical · Risk).
• Intrinsic value — a Damodaran-style 2-stage DCF per holding (an LLM sets lifecycle assumptions, auditable code does the math), with value-trap guards.
• Portfolio-level review — sector diversification vs healthy bands, concentration (effective N), correlation clusters, beta, Sharpe/drawdown, strategy coherence, and a deterministic OK/WATCH/ALERT risk scorecard that renders even if every LLM call fails.
• Alternatives — gap-filling equity candidates cued from your existing portfolio, merged from two signals (MarketFM quant factor rank + Slipstream smart-money 13F/insider accumulation), plus an optional context intake that unlocks a recommended target portfolio.
• Verdict ledger & standing watch — save a portfolio under an anonymous code; every verdict is logged with its price and later scored per action vs the S&P 500 (the committee keeps a track record it must answer to). A background sweep plus on-demand checks raise alerts on price shocks, 200-day trend breaks, stale verdicts, and cited adverse news events. Case IDs are remembered per device and shareable via ?p=<code> links. Ledger persists to a private HF dataset (VITALS_DATA_REPO, default s-ttp/vitals-data).
• A downloadable, typeset PDF report with the full committee detail, plus a JSON audit trail for every run (inputs, data snapshot with sources and as-of dates, every lens output, model and prompt versions, decisions) so any verdict can be reproduced.

Institutional-grade layer

• Data integrity — Alpha Vantage premium is the primary market-data source (adjusted history, quotes, splits, dividends and earnings calendars, ETF constituents, FX) and Sharadar SF1 (licensed, point-in-time) the primary fundamentals source for US equities; scraped feeds are fallback only (indices and exchanges Alpha Vantage does not map); every field passes a plausibility gate (units and feed errors are nulled and flagged, never fed to a model); every number carries an as-of stamp; London pence/pound and D/E/yield unit traps are normalized.
• Valuation rigor — bear/base/bull intrinsic ranges instead of a point estimate, a reverse DCF ("today's price assumes X%/yr growth"), sector-appropriate models (FFO-based DCF for REITs, justified P/B vs ROE for banks and insurers), and peer percentiles vs the US universe.
• Risk analytics — benchmark chosen by domicile (NIFTY, FTSE, Nikkei… not SPY for everyone) with a base-currency view; historical stress replays (COVID, 2022 rate shock, Q4-2018, 2025 tariff shock) of today's weights; 1-day/1-month VaR and expected shortfall; tracking error; currency exposure; real ETF look-through from disclosed constituents; style-factor tilts; days-to-liquidate per position.
• Reproducibility — each analyst lens is sampled LENS_SAMPLES times (default 2) and medianed so a verdict doesn't flip on re-run; strict schema coercion on every LLM output; prompt and methodology versions stamped on every verdict; per-lens calibration (hit rate vs benchmark) accumulates in the ledger.
• Portfolio-aware recommendations — alternatives are not a stock screen: the engine first diagnoses what this book lacks (sector gaps, overweight, effective positions, crash loss vs stated tolerance, income need, valuation tilt), then scores every live-verified candidate on its measured marginal improvement — correlation to your holdings, effective-N, beta, worst crash replay, yield, DCF gap — and only fit-eligible names reach the CIO and the switch engine. Each pick states the problem it fixes with the number ("moves opposite your holdings (correlation −0.40) · cuts the 2022 replay −53%→−49%"). Deterministic guards a quant rank never applies (peak-cycle earnings in a cyclical business, an extended price, informed money leaving) surface as cautions and cost fit; then the same five analyst lenses screen every shortlisted candidate as a prospective addition — a name the committee would not add (below 52/100) is never recommended or used as a switch destination.
• Portfolio construction — risk decomposition (marginal contribution to risk per holding, Ledoit-Wolf shrinkage covariance), adds chosen jointly (each conditional on the one before it, by variance reduction plus need-fit — two redundant names never both win), constrained sizing (SLSQP under name/sector caps, a turnover budget and a tax penalty) in three scenarios — full rebalance, tax-light, new-cash-only — and the entire risk block re-run on the recommended book (stress replays, VaR, effective positions, health) side by side with today. Instruments (sector ETFs, treasuries, cash, dividend and international ETFs) compete with single stocks as fixes. Guards: earnings-date and ex-dividend checks, client exclusions and a max-positions constraint; every candidate considered but not recommended is listed with the reason.
• Recommendation completeness — every Trim/Sell carries its tax cost (gain and, with an optional purchase date, short- vs long-term treatment); orders carry estimated transaction cost and liquidity notes; investor context now includes loss tolerance and near-term cash need, checked against the stress replays; income/conservative investors get profile-fitting candidates; non-US books get live-verified local-market ideas.
• Engineering QA — pytest regression suite (valuation math, decision validator, schema coercion, sanity gates, a mocked golden end-to-end run) and per-run diagnostics (duration, LLM calls/failures, model versions).

Educational tool — not investment advice. No orders are ever placed; output is analysis only.

Token cost strategy

Every run reports tokens and estimated cost by model and by task in the diagnostics (and a "Model usage this run" line in the report). The model plan, chosen so that judgment stays on the strongest model and mechanics do not pay for reasoning they do not need:

Task	Model	Reasoning	Why
CIO synthesis, pre-mortem, alternatives	Claude Opus 5	adaptive (default)	the one judgment call that shapes the verdict
Portfolio strategist	Claude Sonnet 5	adaptive	structured read of computed metrics
Value / Risk lenses	Claude Sonnet 5	medium effort	rubric scoring against a fact sheet; shared fact-sheet block is prompt-cached
Growth / Technical lenses	GPT-5.6 Sol	provider default	model diversity across the committee
Macro lens	Gemini 3.7 Flash	provider default	cheapest lens, macro positioning only
DCF assumptions, plan narrative	Claude Sonnet 5	low effort	numeric mapping with clip guards; prose
Per-holding rationales	GPT-5.6 Luna	thinking disabled	reason-only sentences with a leading-action guard; split out of the CIO so its response is a third of its former size
Investment memos	GPT-5.6 Luna	thinking disabled	A/B on real payloads: memos as good as Sonnet's at ~1/13 the cost, 10 s vs 17 s
Ticker resolution, listing check, event scan	Gemini 3.1 Flash Lite → Haiku	thinking disabled	10/10 on renamed tickers at 1.0 s a call for ~nothing; Haiku via the cascade
File import	Claude Sonnet 5	thinking disabled	once per import; plain tables never reach a model

Tested and rejected: Luna as a lens (growth-lens scores drifted 7 points from GPT-5.6 Sol against 2.4 points of Sol's own repeat noise — enough to flip Keep/Buy More bands) and Luna for DCF assumptions (lifecycle classifications diverged from Sonnet's). Gemini 3.7 Flash as a value lens tracked Sonnet at 0.93 correlation but is kept on the macro lens only, so the committee stays diverse.

Claude 5 models think by default; on a 24-name book that was 19k thinking tokens on Sonnet alone. Effort levels and disabled thinking remove most of it without touching the tasks where reasoning matters.

Speed on US books

• Sharadar price layer (src/sharadar_prices.py): US prices, 52-week range, moving averages, volume, beta, market cap and multiples come from SEP / SFP / DAILY / TICKERS / ACTIONS in batched calls with no meaningful rate limit; Alpha Vantage is kept for what Sharadar lacks (earnings surprises and estimate revisions, the analyst-target overview, news sentiment, ETF constituents, FX) and remains primary for every non-US market. Earnings dates come from one whole-market calendar call a day.
• Pre-warming: each row resolved at import kicks off the deep fundamentals, eight-year history, street view, news and events in the background, so the analysis finds them cached.
• Batched import verification: one server round trip resolves every imported row in parallel; the ten-year range and split checks run only when the entry price implies an extreme P/L.
• Split CIO: investment memos are written by a parallel writer on the standard model in chunks, so the CIO's own response is a quarter of its former size.
• Time budget: the watchdog scales with book size; past 65% of the budget the candidate committee screen is skipped and past 85% the plan narrative, with the diagnostics saying so.
• Plain tables never wait for a model: a CSV/XLSX with a symbol column and an average-cost column is read directly; the AI extractor handles transaction exports, PDFs and odd layouts on the standard tier. A pre-split entry price is never rewritten silently: the row asks which is right — adjust price and quantity, adjust price only (quantity already post-split), or keep as entered — and the analysis refuses to run until the question is answered; the results row shows what was chosen. A 10:1 split can hide behind an ordinary-looking P/L, and only the investor knows whether their share count is pre- or post-split.
• Pipeline parallelism: the portfolio strategist and the whole candidate pipeline (pool, live verification, fit, screens, committee) run alongside the five-lens panel; books of 30+ names use one sample per lens.
• US-only fast path: a book with no exchange suffixes skips the European panel, ADR bridge, local-idea generation and multi-venue logic deterministically.
• The European panel rebuild yields to running analyses and is throttled to a fraction of the Alpha Vantage budget.

Markets covered

Market	Yahoo suffix	Prices / history / FX	Fundamentals
US (NYSE, NASDAQ)	—	Alpha Vantage	Sharadar (point-in-time)
UK · Germany (Xetra, Frankfurt) · France · Netherlands · Portugal · Belgium · Canada (TSX, TSX-V)	.L .DE .F .PA .AS .LS .BR .TO .V	Alpha Vantage	Alpha Vantage where available, else yfinance (sanitized)
India (NSE, BSE)	.NS .BO	Alpha Vantage BSE line (NSE names are dual-listed at near-identical prices; the NSE symbol is kept)	Sharadar via the company's NYSE/NASDAQ ADR where one exists (HDFC Bank → HDB, Infosys → INFY: ratio fields are the underlying company's, EPS/BVPS derived currency-consistently from local price × P/E, P/B); else yfinance (sanitized)
China (Shanghai, Shenzhen)	.SS .SZ	Alpha Vantage	Sharadar via ADR where one exists (Alibaba → BABA), else yfinance (sanitized)
Switzerland, Italy, Nordics, Japan, Korea, Hong Kong, Australia, Brazil and other Yahoo-suffixed exchanges	e.g. .SW .MI .CO .T .KS .HK .AX .SA	yfinance (fallback)	Sharadar via ADR where one exists (Vale → VALE, TSMC → TSM, Shell, SAP, Novartis…), else yfinance (sanitized)

Several purchases of one stock may be entered as separate rows (same ticker, each lot's price, quantity and date); they are averaged with the average-cost method (quantity-weighted cost, sales as negative quantities reduce the remaining position at that cost — the Section 104 pool logic), the earliest lot dates the position, and US tax notes name the lots still short-term. Without quantities the entry prices are averaged plainly and the row asks for quantities.

Inputs may be tickers, company names (resolved deterministically through Alpha Vantage Symbol Search — preferring the home-market listing over a US OTC ADR, and mapping India to the NSE line — before any LLM is consulted), Bloomberg-style codes ("VOD LN" → resolved with a listing check) or ISINs (OpenFIGI → primary listing). Renamed or demerged tickers are re-searched by their base symbol ("Tata Motors" → TMCV.NS / TMPV.NS). Benchmarks follow the book's domicile (S&P 500, FTSE 100, STOXX Europe 600, DAX, NIFTY 50, SSE Composite…); European books get UCITS instruments, Indian books get NSE-listed BeES ETFs, and local-market ideas are verified live on the same exchanges. Tax notes apply US short/long-term rules only to US listings.

US books — practitioner layer (src/fundamentals.py)

Plain US listings get a deep block computed deterministically from Sharadar history and Alpha Vantage estimates, so the committee argues from numbers rather than adjectives:

• Forensic quality — Piotroski F-score, Altman Z (masked for financials and REITs), Beneish M-score, Sloan accruals, cash conversion (FCF / net income).
• Buffett / Greenblatt / Lynch economics — owner earnings and owner-earnings yield, FCF yield, ROIC and five-year incremental ROIC, EBIT/EV earnings yield, Graham number, PEG on three-year EPS growth, and the Lynch category (fast grower, stalwart, slow grower, cyclical, turnaround, asset play) that decides which metrics matter and which sell triggers apply.
• Capital allocation — buyback yield vs dilution (1y and 5y share count), stock-based compensation as a share of revenue and FCF, FCF payout and the dividend-raise streak.
• Valuation vs the company's own ten-year history — where today's P/E, EV/EBITDA, P/S and P/B sit in the daily distribution (Sharadar DAILY), with the median.
• Earnings momentum — beat count and average surprise over eight quarters, fiscal-year EPS estimate revision over 90 days, up/down revision counts over 30 days.
• Ownership — open-market insider buys and sells over six months (SF2, cash transactions only) and 13F holder / share changes (SF3A, stale or coverage-jump snapshots suppressed).
• Sell discipline — per-holding thesis-break triggers from the same numbers, forensic flags that also screen alternatives (a factor rank never outranks a distress or manipulation flag).

Recommendation discipline for every book with a usable DCF range:

• Payoff asymmetry — bear / base / bull outcomes with probabilities tilted by committee conviction give an expected 12–18 month return and an upside:downside ratio; a "Buy More" must clear 2:1 and +8% or it is downgraded to Keep with the reason shown.
• Sizing guardrail — half-Kelly from expected return and realised volatility, capped at the name cap, shown against the current weight.
• Investment memo per holding (thesis, the debate, what would change our mind), a pre-mortem for the largest position, an explicit "do nothing" verdict when nothing clears the hurdle, tax-loss harvesting pairs (≥10% loss, ≥0.7-correlated non-identical substitute; a broad index fund swaps only into a ≥0.9-correlated broad fund on a different index, e.g. VOO → VTI / SCHX, never a sector fund; 31-day wash-sale note) and wash-sale warnings on loss-making switches.
• Health score = six pillars, shown under the gauge — Prospects 25% (committee conviction, DCF-implied payoff where trusted, quant 12-month excess, growth durability, estimate momentum; growth-stage names are never judged on a mature-company DCF gap), Concentration 20% (name vs cap, top three, sector vs band, largest active bet), Diversification 15% (effective positions, correlated pairs, ballast for cautious profiles), Quality 15% (weight in forensic-flagged names, Piotroski), Drawdown 15% (half efficiency vs structural beta, half absolute fall vs the index; 25% for conservative, 8% for aggressive profiles), Valuation 10% (DCF gap where the model applies, blended toward neutral for the share of the book it does not cover, P/E vs own history). Active sector bets fall back to a static S&P 500 mix when the live profile is unavailable, so the charge cannot appear and vanish between runs. One-year performance is a ±3 tie-breaker only; a breached loss tolerance costs 8; the weakest pillar caps the total (one broken pillar cannot be outvoted by strong prospects).
• A stock-picker's plan never holds an index fund — for a book of 12+ single names with no cautious profile or stated loss tolerance, no ETF enters the candidate pool at all: sector gaps, ballast and diversification are expressed through single names. A conservative profile, a short horizon or a loss tolerance brings defensive instruments back.
• Stock-picker books get stock ideas — a book of 12+ single names is treated as a stock-picker's: the CIO sees single names first, at least two alternatives are single stocks and at most one is an instrument; smaller books or de-risking needs still get instruments.
• Sizing discipline — a new single name enters at a starter size (≈1.5× the typical position, at least 3%, never past the cap); an existing name may at most double or gain three points of the book; instruments are bounded in a large single-name book; the target keeps at least 75% of today's market beta unless the investor asked to de-risk (a growth book is never silently converted into utilities); risk aversion scales with the stated profile; a partial sale of a position below the trading band (min(2%, max(1%, 0.5/n)) — 1.06% in a 47-name book) is replaced by a clean exit or a hold; a size-driven Trim on a backed winner lands between 80% of the cap and the cap (META 24% → 12–15%), never at 40% of the position; of a correlated pair the plan adds to one name only; a sector ETF is sized like a sector bet (never past the name cap or 15%), and every new name the plan buys is explained in the alternatives list; a conservative / income book never adds to a name with beta above 1.15 and needs a flagged idea (peak-cycle, extended, informed money leaving) at ≥66/100.
• The manager's desk — capital follows conviction: fresh money goes only to Buy More verdicts and new ideas (a plain Keep is never topped up; a backed Keep below the trading band is rounded up to a real position; an add is lifted to at most 6% of a broad book, 10% of a small one); proceeds the committee's ideas cannot absorb stay as unallocated cash, presented as dry powder for a watchlist of screened-out names with explicit entry conditions (reclaim the 200-day, pull back to it, wait for revisions to turn). Keeps with weak backing and a negative expected payoff carry a watch tag and are the first source of funds; a sub-band position nobody backs is exited rather than held as dead money. Every sell carries a tax plan (highest-cost lots first, hold a lot that turns long-term within 90 days, split a large long-term gain across two tax years); the plan shows where the risk sits after the trade, a probability-weighted valuation risk/reward (bear/base/bull convergence) for today's and the recommended book, the next 90 days of catalysts (earnings, ex-dividend), and per-holding tripwires with the current number and the date they are next tested. Loss-making growth names are valued on a stated rule-of-40 EV/Sales yardstick instead of a blank. Triage dispositions always agree with the trade list.
• Sector gaps are sourced, not just named — a sector the book lacks is searched six names deep in the quant panel (two for sectors already owned), the top 30 are verified live, the committee screens a second batch whenever a missing sector has no strong candidate, and the shortlist leads with the best strong name from each missing sector so the optimizer can actually move the sector mix. A book with zero Industrials, Materials, Defensive and Utilities once received one Technology idea because its eight gap candidates all failed a screen and nothing replaced them.
• Valuation guardrails — the justified-P/B model is used only for banks, insurers and asset managers with book-value economics (ROE ≤ 35%, book ≥ 15% of price, no leverage-inflated ROE); payment networks and fintechs go on the earnings DCF; when forward EPS is ≥1.4× depressed trailing EPS the DCF anchors on their average and says so; reinvestment is capped at 80% of earnings so a fast grower on a modest accounting ROIC is not priced as value-destroying; an Altman-Z distress flag disqualifies a candidate outright. The CIO synthesis retries on the standard tier after two unusable top-tier replies, JSON parsing repairs control characters and trailing commas, and every unusable model reply is saved under data/cache for diagnosis.
• Loss tolerance as a constraint — when the investor states a loss tolerance, every crash replay becomes a linear constraint in the optimizer, so the proposed book must stay inside the tolerance in each historical window; the scenario table says whether it was reachable.
• A model reply is validated, not trusted — the CIO's answer must carry its verdict (a truncated reply once parsed as an inner fragment and slipped through as an empty verdict, so the report fell back to the scorecard); the retry lowers reasoning effort so the budget goes to the answer, and any fallback is printed in the report's diagnostics note.
• Winners are not sold early — the validator's two-lens dissent tilt (two analysts at 35 or below overriding a momentum-led median) applies only to cyclicals, judged by sector or by industry (semiconductors, memory, autos, steel, chemicals, oil and gas, mining, shipping…); a secular compounder keeps its Keep or Buy More while its growth and trend lenses back it. Size alone still trims any name past 1.25× its cap unless the committee is strongly behind it.
• Orders agree with verdicts — a Keep the committee only lukewarmly backs (conviction under
  55. or that carries a forensic flag gets no adds; a backed Keep outside the overweight sector is never sold below 80% of its weight to fund other buys; only a new position can fill a sector gap and the plan narrative is told so.
• Plan coherence — switch destinations follow the names the order plan actually buys; a "Buy More" is never issued inside the diagnosed overweight sector; bond and cash funds are ballast and are never ejected by the equity lenses in a conservative or short-horizon book; US-listed ADRs derive per-share values from the ADR price and Sharadar ratios (ordinary-share EPS once made TSM look 4× undervalued).
• Benchmark-relative risk for US books — measured factor betas (momentum, quality, value, low-vol, size ETFs), upside / downside capture, Sortino, Calmar, active sector bets vs the S&P 500.

UK / European books — institutional layer

• European factor panel (src/europanel.py): the MarketFM equivalent for Europe, built on the Space from Alpha Vantage — universe = the top ~300 European names by index weight (VGK, SPEU, DBEU, FEZ constituents) mapped to their home listings (LSE, Xetra, Paris, Amsterdam, Lisbon, Brussels; Xetra lines for markets Alpha Vantage does not carry), per-name valuation / quality from the same holding fetch the analysis uses (Alpha Vantage price, Sharadar via ADR, yfinance fill, sanity gates) and momentum / volatility from Alpha Vantage adjusted daily history, cross-sectional percentile ranks and a style-balanced composite (value, quality, momentum, low-vol). Refreshed daily in the background; data/europanel.json ships with the last build. European-heavy books (≥50% weight in European listings) draw quant-ranked candidates from it first, and European holdings get peer percentiles against the European universe, not the US one.
• European sector UCITS instruments: iShares STOXX Europe 600 sector ETFs (Xetra) and IPRP (European property) fill sector gaps for European books, alongside the broad / gilt / gold / dividend / min-vol UCITS set.
• Cost & tax realism: the order plan adds UK stamp duty (0.5%), Irish stamp duty, French, Italian and Spanish FTTs and HK stamp duty on home-market share purchases (ETFs exempt); an account wrapper input (taxable / ISA / SIPP / IRA) switches capital-gains notes off inside tax-sheltered wrappers; foreign dividend payers carry a withholding-tax note.

Space secrets

Secret	Required	Purpose
ANTHROPIC_API_KEY	recommended	Claude — Value & Risk analysts, DCF assumptions, strategist, CIO.
OPENAI_API_KEY	recommended	GPT — Growth & Technical analysts. Different models give independent opinions; with any one key the others cascade onto it.
GEMINI_API_KEY	recommended	Gemini — Macro analyst + name→ticker fallback.
ALPHAVANTAGE_API_KEY	recommended	Premium market data (primary): history, quotes, splits, calendars, ETF constituents, FX, news. AV_CALLS_PER_MIN (default 75) sets the limiter.
HF_TOKEN	optional	Read the private MarketFM panel dataset (quant ranks + alternatives pool).
NASDAQ_DATA_LINK_API_KEY	recommended	Sharadar SF1 — licensed, point-in-time US fundamentals as the primary source (and REIT FFO inputs).

With no LLM key at all the app still runs and shows the quantitative summary.

Models are tier-routed by task demand (all env-overridable): synthesis & valuation judgment on Claude Opus 5 (LLM_MODEL_TOP), Value/Risk lenses + import on Claude Sonnet 5 (LLM_MODEL), Growth/Technical lenses on GPT-5.6 Sol (OPENAI_MODEL), Macro on Gemini 3.7 Flash (GEMINI_MODEL), utilities on Claude Haiku 4.5 (LLM_MODEL_FAST). Other config: RUNS_PER_DAY (default 25), MAX_HOLDINGS (default 25), CACHE_TTL_HOURS (default 6).

Other env vars: LENS_SAMPLES (default 2), MAX_CONCURRENT_RUNS (default 2).

Run locally

pip install -r requirements.txt
uvicorn app:app --port 7860

Policy validation

scripts/backtest_fit_policy.py walks forward quarterly over ~5 years on three seed books and compares the greedy variance-reduction add rule against random adds, momentum adds and no adds (12-month holds); results land in data/policy_backtest.json.

Latest run (2021-Q1 → 2025-Q2, 18 rebalance dates per seed): the greedy rule delivered the lowest volatility and shallowest max drawdown in every seed book (tech-concentrated: 31.6% vol / −24.0% DD vs 33.7% / −25.8% random, 35.4% / −26.7% momentum, 41.4% / −31.1% with no adds) and the best Sharpe on the tech book (1.34); on the income and mid-cap books momentum adds earned more return. Read it plainly: the construction rule reliably buys diversification, not alpha — return is the job of the fit scoring and the analyst committee layered on top.

Tests

pip install -r requirements-dev.txt
pytest

Architecture

FastAPI + SSE progress stream + vanilla JS frontend (no build step). The analysis pipeline (src/orchestrator.py) runs in-process: resolve holdings → fetch market data (yfinance global, Alpha Vantage enrichment) → deterministic portfolio metrics → Damodaran DCF → batched 5-persona conviction panel → portfolio strategist → CIO synthesis. LLM outputs are gated by deterministic validators (actions come from conviction-median rules, never from free-form LLM text); every LLM stage fails open.