awesome-stock-analysis

awesome-stock-analysis

Beautiful, single-file HTML investment research reports for any US stock. Run one command, get a magazine-quality analysis with cyclicality-aware DCF, sentiment-buffered verdict, and 40+ inline term tooltips. Bilingual EN / 中.

Why

Most stock-research output is either bone-dry spreadsheet exports or marketing-fluff terminal screenshots. This pipeline produces something that reads like a research note from a top-tier sell-side desk — but generated from a single command.

The valuation methodology is also explicitly cycle-aware. Most DCF templates use historical FCF growth, which systematically misprices cyclicals (memory, autos, steel, etc.) because the latest year is rarely "normal." This pipeline uses Q-annualized × P/E multiple as the primary anchor — most current run-rate signal — with three other DCF lenses for cross-check.

Features

• Single-file HTML report, ~90KB, opens in any browser, no server / build step needed
• 4 DCF methods auto-computed and compared: Q-annualized, Forward FCF-adjusted, Forward Pure EPS, Historical FCF
• Cyclicality detection from income data (not industry name) — NVDA correctly tagged secular, MU correctly tagged cyclical
• Sentiment buffer softens fundamental SELL on parabolic stocks (don't fight the tape) — +2 buffer when sentiment ≥ 80
• Bilingual EN / 中 — runtime toggle button, persisted via localStorage
• 40+ inline tooltips — hover any metric for definition (both languages)
• Inline SVG charts — revenue bars, quarterly trend, DCF horizontal bars, price line with SMA50/SMA200 overlays
• Warm editorial design — cream paper background, Charter serif headlines, Claude coral accent — reads like The Economist, not Robinhood
• Self-contained — no external CSS, no JS libraries, works offline, prints nicely
• Fast — ~10 seconds end-to-end for one ticker

Quick start

git clone https://github.com/justinz183/awesome-stock-analysis.git
cd awesome-stock-analysis
export FMP_API_KEY="your_fmp_premium_key"
./run.sh NVDA               # interactive language prompt → opens in browser
./run.sh AAPL --lang=zh     # skip prompt, default Chinese
./run.sh TSLA --no-open     # don't auto-open

Output: reports/<TICKER>/report.html

Example

$ ./run.sh MU
[1/3] Fetching FMP data...
  ✓ profile          (2481 bytes)
  ✓ quote            (453 bytes)
  ✓ income_quarter   (11120 bytes)
  ... (20 endpoints)

[2/3] Analyzing (DCF + verdict + cycle classification)...
  MU    Micron Technology, Inc.
  Price $762.10  |  Cap $859B  |  Class: cyclical
  Rating: REDUCE (final -1 = fundamental -3 + sentiment buffer +2)
  Sentiment: 100/100 (extreme_bullish)
  Primary DCF (qtr_run_rate) base: $676.48 (-11.2%)

[3/3] Building HTML report (lang=en)...
  ✓ reports/MU/report.html

Full sample report rendered:

How it works

3-stage pipeline:

fetch_fmp.sh         analyze.py               build_html.py
─────────────        ──────────────           ─────────────
20 FMP endpoints  →  4 DCF methods,        →  Self-contained HTML
                     cyclicality,             with inline SVG,
                     sentiment,               i18n spans,
                     verdict scoring          tooltips

1. lib/fetch_fmp.sh <TICKER> <OUT_DIR> — pulls 20 stable-API endpoints into OUT_DIR/data/*.json
2. lib/analyze.py <DATA_DIR> <OUT_DIR> — computes DCFs, classifies cyclical/secular, scores verdict with sentiment buffer → OUT_DIR/analysis.json
3. lib/build_html.py <ANALYSIS> <OUT> [lang] — renders the HTML report

The orchestrator run.sh wires them together and handles language selection.

Valuation methodology

This pipeline computes 4 DCF anchors and picks one as primary based on the stock's character:

Cyclicality is detected from income data, not industry name:

• Any negative-income year in 5y history → cyclical
• OR peak income year is not in the latest 2 years → cyclical
• Otherwise → secular growth

This correctly distinguishes NVDA (secular: peak NI is FY26, the latest) from MU (cyclical: peak NI was FY22, then a $5.8B loss year, then recovery).

Sentiment buffer adjusts the fundamental verdict score when sentiment and fundamentals strongly diverge:

• Sentiment ≥ 80 (parabolic) AND fundamentals bearish → +2 (don't fight the tape)
• Sentiment ≥ 65 AND fundamentals bearish → +1
• Sentiment ≤ 20 (capitulation) AND fundamentals bullish → +1 (contrarian lean)

The MU example above: fundamentals say SELL (-3 score) but extreme bullish sentiment (+695% YoY) adds +2 → final REDUCE ("gradually exit, don't fight the tape").

See docs/valuation-methods.md for full formulas.

Use as a Claude Code skill

This project is also packaged as a Claude Code skill. Install:

# Copy to Claude skills folder
cp -r awesome-stock-analysis ~/.claude/skills/

# Now in any Claude Code session, just say:
# "analyze NVDA" or "美股投研报告 AAPL"
# Claude will auto-detect and use this skill.

The SKILL.md file is the integration manifest. See it for the full skill triggers and Claude-side workflow.

Requirements

• FMP API key (Premium $59/mo) for full coverage — export FMP_API_KEY="...".
  • The Basic free tier only covers Mag-7 + a handful of others. Most tickers (MU, AVGO, TXN, QCOM, ASML, etc.) require Starter+ for financials.
  • Quarterly data requires Premium tier.
  • See docs/data-sources.md for the full tier breakdown.
• Python 3 (no extra packages — uses only stdlib)
• Bash 3.2+ (works on macOS default)
• A modern browser to view reports (any will do — Chrome, Safari, Firefox, Edge)

Documentation

• docs/design-system.md — full warm-paper Claude-style aesthetic spec (colors, typography, components)
• docs/valuation-methods.md — DCF formulas, cyclicality detection, sentiment buffer math
• docs/html-gotchas.md — 15 bugs encountered + fix patterns. Read before modifying HTML
• docs/data-sources.md — FMP tier guide, endpoint reference, error patterns

Extending

License

MIT — see LICENSE. Free to use, modify, and ship. Attribution appreciated but not required.

Acknowledgments

Built iteratively in conversation with Claude (Anthropic). Data via Financial Modeling Prep. Inspired by editorial design from The Economist, Stratchery, and Anthropic's own brand language.

This is not investment advice. Reports are programmatically generated and should be one input among many in your research process.