Finance Data Research Hub

AI 驅動的美股投資研究平台 — 基本面分析、技術分析、市場數據、SEC 文件，全部繁體中文。

Live site: yennanliu.github.io/finance_data (English + 繁體中文)

An automated research pipeline for US (and Taiwan) equities. Scheduled jobs fetch market and SEC data, an LLM writes structured reports in Traditional Chinese, a nightly audit checks every figure it can, and the results are published as a static MkDocs site.

---

Features

AI reports	12 analysis types. Fundamental and technical reports run daily; earnings-call, insider, 13F, valuation and more run on demand
Checked figures	Derived numbers (TTM, FCF, WACC, multiples) are computed in Python and quoted by the model. The §8.8 fair-value sum is recomputed and corrected after generation
Market Data	10-year daily OHLCV plus SEC quarterly fundamentals per ticker: candles, drawdown, volatility, financial statements, valuation bands, DCF and reverse DCF. Downloadable as CSV / JSON
Market news	Daily per-ticker digest from Yahoo, RSS feeds and Perplexity Discover
QA audit	Nightly rule-based checks plus a cross-provider LLM review, committed to qa/
SEC filings	10-K, 10-Q, 13-F and 6-K archives (10-k/, 10-q/, 13-f/, 6-k/)
Research notes	NotebookLM deep dives (notebook_llm/) and investor-day materials (investor_day/)

Coverage

• Daily fundamental (36): 0050, 2330.TW, TSLA, PL, GRAB, TSM, GOOG, AMZN, MSFT, SOFI, PLTR, RKLB, ONDS, AVAV, KTOS, META, AMD, NVDA, NU, VST, ORCL, INTC, SPCX, AVGO, NBIS, MU, SKHY, WDC, SNDK, MRVL, SOXQ, SOXX, WQTM, VTI, QQQ, ROBO
• Daily technical (25): the first 25 of the above (0050 … NBIS)
• Analysis types (12): fundamental-analysis, technical-analysis, stock-eval, stock-valuation, financial-report-analyst, earnings-call-analysis, insider-trading, institutional-ownership, sector-analysis, economics-analysis, portfolio-review, report-generator

The schedule is data-driven: scripts/.ticker_schedule.json.

---

How it works

┌──────────────┐    ┌──────────────────┐    ┌──────────────┐    ┌──────────────┐
│  Data fetch  │───▶│   LLM analysis   │───▶│   QA audit   │───▶│   Publish    │
│  yfinance    │    │ Gemini → OpenAI  │    │ rules + LLM  │    │ MkDocs       │
│  SEC XBRL    │    │ (Claude opt-in)  │    │ judge        │    │ GitHub Pages │
│  scrapers    │    │ 繁中 reports      │    │ nightly      │    │ nightly      │
└──────────────┘    └──────────────────┘    └──────────────┘    └──────────────┘

1. Fetch. yfinance, Finviz / StockAnalysis / Roic.ai scrapers and SEC companyfacts. Prices and fundamentals are kept as committed CSV stores in data/.
2. Analyse. scripts/generate_analysis.py builds a context per analysis type and calls the LLM chain (fundamental reports: OpenAI gpt-6-luna first, Gemini as fallback; other types: Gemini gemini-3.8-flash first, OpenAI as fallback). Reports land in ai_gen_report/.
3. Audit. qa_report_quality.yml checks reports nightly. See docs/QA_AUDIT.md.
4. Publish. scripts/build_docs.py turns reports and stores into the site; deploy.yml builds and deploys it at 04:00 UTC.

---

Quick start

Requires uv. It installs the pinned Python (3.11) for you.

Clone (lightweight)

The full history is ~1 GB, mostly PDFs. A partial clone with sparse checkout skips the PDF folders:

git clone --filter=blob:none --no-checkout [email protected]:yennanliu/finance_data.git
cd finance_data
git sparse-checkout set --no-cone '/*' '!notebook_llm/' '!10-k/' '!10-q/'
git checkout main

Set the sparse patterns before the first checkout. git sparse-checkout disable brings the PDFs back.

Generate a report

uv sync --extra dev

export GEMINI_API_KEY="..."       # default provider
export OPENAI_API_KEY="sk-..."    # fallback
export ANTHROPIC_API_KEY="sk-..." # optional: --provider claude

uv run python scripts/generate_analysis.py AAPL     # fundamental-analysis
uv run python scripts/generate_analysis.py MSFT --analysis-type technical-analysis
uv run python scripts/generate_analysis.py NVDA --analysis-type stock-valuation --provider openai

Output goes to ai_gen_report/fundamental/<ticker>/, ai_gen_report/technical/<ticker>/ or ai_gen_report/stock/<ticker>/.

Run the tests

uv run pytest tests/ -v    # offline, no API keys needed

Build the site locally

uv pip install "mkdocs-material==9.5.*" mkdocs-awesome-pages-plugin minify-html
uv run python scripts/build_docs.py
uv run mkdocs serve

Download SEC filings

uv run python scripts/download_10k_edgar.py AAPL --years 5    # 10-K PDFs from EDGAR
uv run python scripts/download_10q_edgar.py AAPL              # 10-Q PDFs from EDGAR
uv run python scripts/download_10k_pdf.py meta-platforms-inc  # from annualreports.com

Trigger CI runs

gh workflow run daily_analysis.yml -f ticker=MSFT -f analysis_type=technical-analysis
make analyze TICKERS="NVDA TSLA" TYPES="fundamental-analysis,technical-analysis"
make deep-dive TICKERS="NVDA"    # earnings-call, insider, 13F and HTML report
make help                        # all targets

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗