Evidence-first stock market analysis for AI agents, quant researchers, and investors who want auditable daily notes.
A/HK/US stocks · Funds · Portfolios · JSON Evidence Packs · Data-quality scoring · Multi-source fallback · Investor lenses
Listed in thuquant/awesome-quant via merged PR #48.
stock-analysis turns public market data into deterministic Markdown reports and machine-readable evidence. It is built for repeatable market recaps, not black-box trading signals.
uv tool install stock-analysis
stock-analysis --market daily
stock-analysis --market stock --symbol 600519
stock-analysis --market screen --fiscal-year 2025 --universe-file official_universe.json --filter roe_weighted:gt:8% --sort roe_weighted:desc
stock-analysis --market global --format full --with-holdings --emit-evidenceThe output is for research only and does not constitute investment advice.
Most market "AI analysis" starts with a prompt and ends with a fluent paragraph. stock-analysis starts with evidence:
- Fetch public market data across A-shares, Hong Kong stocks, US stocks, funds, and portfolios.
- Normalize symbols, timestamps, source metadata, and missing fields before writing conclusions.
- Score report quality from six evidence modules instead of pretending every data source worked.
- Emit JSON files that AI agents, notebooks, cron jobs, or human reviewers can inspect and diff.
If a data source fails, the report records the gap. Missing metrics stay missing; they are not filled with zeroes or guessed from nearby signals.
| Committee recap | Buffett recap | Simons recap |
|---|---|---|
2026-07-09 Investment committee recap |
2026-07-09 Buffett recap |
2026-07-09 Simons recap |
| Buffett stock lens | Simons stock lens | Fund profile |
|---|---|---|
Kweichow Moutai 600519 |
Kweichow Moutai 600519 |
Semiconductor ETF 512480 |
Browse the report directory for the six 2026-07-09 Markdown reports, screenshots, social-share assets, and automation examples.
| Capability | What it means |
|---|---|
| Evidence Pack JSON | evidence_YYYYMMDD.json plus M1-M6 module files for audit, automation, and agent handoff. |
| A/HK/US/fund coverage | One CLI for broad market snapshots, single stocks, funds, and portfolio exposure. |
| Data-source routing | Tencent/Sina first where stable, Eastmoney for unique China-market data, browser fallback only when needed. |
| Quality scoring | Reports carry a 100-point evidence quality score and identify missing modules. |
| Investor lenses | Built-in Buffett, Munger, Graham, Simons, Dalio, Duan Yongping, Zhang Kun, and other structured lenses. |
| Portfolio memory | Optional local holdings profile with benchmark comparison, concentration risk, and FX normalization. |
| Deterministic A-share screening | Strict annual-report conditions with official-Universe gating, per-stock PASS/FAIL/UNKNOWN decisions, and one auditable Evidence JSON. |
| Guarded market-data evidence | Northbound flow requires a validated full-day sequence; fund profiles expose per-fund field coverage; listed A-shares/ETFs get 5d/20d/60d price-volume metrics and split-normalized premium/discount series when public samples are complete. |
Install from PyPI:
uv tool install stock-analysis
stock-analysis --market dailyRun from a local checkout:
git clone https://github.com/AdvancingTitans/stock-analysis.git
cd stock-analysis
uv run stock-analysis --market dailyCommon commands:
# Auto-select summary/key-points/full by Beijing market session
stock-analysis --market daily
# Full global recap with auditable JSON evidence
stock-analysis --market global --format full --emit-evidence
# Deterministic single-stock snapshot, no LLM required
stock-analysis --market stock --symbol 600519
# Deterministic fund snapshot with public profile and holdings data
stock-analysis --market fund --symbol 161725
# Deterministic A-share annual-report screen; requires a complete official Security Master snapshot
stock-analysis --market screen --fiscal-year 2025 --universe-file official_universe.json \
--filter roe_weighted:gt:8% --filter revenue_growth_yoy:gt:8% \
--sort roe_weighted:desc --limit 20 --emit-evidence
# Diagnose Tencent, Sina, Eastmoney, browser, and optional mootdx routes
stock-analysis --market diagnoseWhen --emit-evidence is enabled, the CLI writes:
evidence_YYYYMMDD.json
m1_YYYYMMDD.json
m2_YYYYMMDD.json
m3_YYYYMMDD.json
m4_YYYYMMDD.json
m5_YYYYMMDD.json
m6_YYYYMMDD.json
The six-module score is designed for report trust, not performance marketing:
| Module | Focus | Weight |
|---|---|---|
| M1 | Cross-market index state, breadth, liquidity, benchmark context | 20 |
| M2 | Sector and concept rotation | 20 |
| M3 | Short-term sentiment and limit-up structure | 20 |
| M4 | Risk, failed breakouts, downside pressure | 15 |
| M5 | Portfolio exposure, style, concentration, holdings pulse | 15 |
| M6 | Resilient directions and next-session watchlist | 10 |
Full reports keep the same structure even when quality is low, but missing modules are called out naturally in the relevant section.
For current-day A-share reports, whole-market breadth is counted only after every Eastmoney clist page reconciles; a Sina hs_a fallback must paginate to EOF with unique valid codes. Historical reports keep strict breadth unavailable rather than relabeling industry-board components as all-market breadth. Tencent daily K lines add 5d/20d/60d returns, volume z-score, and ATR only when the sample is complete.
stock-analysis is intentionally agent-friendly:
- Deterministic CLI first; LLM layers can consume evidence later.
- Markdown for human review, JSON for machine workflows.
- Explicit source events and fallback reasons.
- Stable command surface for cron jobs, notebooks, Hermes, Codex, Claude Code, and other tool-calling agents.
Example agent prompt:
Run stock-analysis --market global --format full --emit-evidence.
Use the Markdown report for the user-facing recap.
Use evidence_YYYYMMDD.json to verify every strong conclusion before summarizing.
If a module is missing, say which evidence was unavailable instead of guessing.
See examples/agent.md for a daily agent workflow and examples/github-actions-daily-recap.yml for a scheduled GitHub Actions recap that uploads the report plus Evidence Pack.
- Not a trading bot.
- Not a broker integration.
- Not a promise of complete market data.
- Not a replacement for professional financial advice.
- Not a black-box LLM report generator.
| Scenario | Primary route | Fallback route |
|---|---|---|
| A-share quotes and valuation | Tencent → Sina | Eastmoney stock/get |
| A-share indices | Tencent → Sina | Eastmoney index endpoints |
| Board rankings | Eastmoney clist |
Tonghuashun public pages → browser fallback |
| HK quotes | Tencent/Sina | Eastmoney stock/get |
| US quotes | Sina/Tencent | Eastmoney searchapi → stock/get |
| Funds | Eastmoney/Tiantian fund pages | Sina fund fallback |
| Deep tick/order-book data | Optional mootdx |
Basic Tencent/Sina quotes |
Yahoo is intentionally not part of the recommended default path.
The lens engine can render the same evidence through different investment frameworks. Supported lenses include:
buffett, munger, graham, klarman, lynch, o_neil, wood, dalio, soros, livermore, minervini, simons, duan_yongping, zhang_kun, and feng_liu.
Lenses change evidence priority and narrative structure. They do not override data quality rules or invent missing numbers.
Current CLI version: 4.4.2.
LensEngine is the report orchestration layer. The default mode is committee, which combines M1-M6 evidence into a deeper cross-module analysis. Natural-language callers can ask for requests such as "analyze Kweichow Moutai in Buffett mode" or "run an adversarial debate between Buffett and Munger on Tencent." If committee mode fails, the engine falls back to single mode and preserves the fallback reason in metadata.
Committee reports use a fixed spine: executive summary → market index overview → portfolio analysis when complete holdings are available → six-module deep recap → integrated portfolio guidance and risk notes. The closing guidance should cover the current state, benchmark outperformance or underperformance, conditional position actions, the next-session watchlist, and key risks. Evidence appendices stay outside the morning, intraday, midday, and after-close narrative body. If any M1-M6 module is missing, the relevant section must say that the evidence is unavailable.
--market stock --symbol <code> and --market fund --symbol <code> are deterministic evidence views. They do not require users to install any external quote CLI. Browser routes are fallback-only paths for repeated API failures or page-only data. Engineering details belong in evidence and diagnose output, not in the user-facing report body.
Northbound flow is shown only after a current-day full-session validation (coverage through 14:50, sufficient minute samples, and a sane opening baseline). Historical or incomplete streams remain unavailable. Fund-profile completeness is evaluated for every fund and every field, so an ETF with no published fee values cannot be compared as if fees were known. Board rankings carry their source taxonomy, and classifications from different providers are not comparable without normalization.
Listed-fund premium/discount uses Tencent forward-adjusted daily closes against paginated official NAV. Public share-split events are normalized before the two series are compared; any unparseable corporate action suppresses the series. A fund-page annualized tracking-error value is labeled as disclosed metadata, never as a locally recomputed daily tracking error.
Fund profiles use Tiantian Fund's public pingzhongdata page to supplement long-term performance, front-end fees, fund size, and fund manager context. This path does not require login or an API key. Fund snapshots should show long-term performance, front-end fees, fund manager information, and any disclosed gaps.
Investment memory defaults to ~/.stock_analysis/profile.json and can be overridden with STOCK_ANALYSIS_PROFILE. A complete holding must include the symbol, buy date, and either share quantity or purchase amount. If newly supplied user information conflicts with saved investment memory, confirm that the new information is complete, then prefer the user's latest input and overwrite the saved memory.
When a user explicitly asks for a specific investor style, the whole report must be written from that lens. Do not merely append an expert comment at the end. Single-expert and multi-expert reports have different structures, but neither should impersonate an investor or fabricate expert quotes.
Good first contributions:
- Add or harden a public data-source adapter.
- Improve a report template or investor lens.
- Add examples for a new region, symbol type, or agent workflow.
- Report a source failure with
--market diagnoseoutput. - Submit this project to a high-fit Awesome List or agent tool directory.
Start with CONTRIBUTING.md and ROADMAP.md.
Use this one-liner when submitting the project to curated lists:
stock-analysis - Evidence-driven market recap CLI for AI agents and quant researchers, supporting A/HK/US stocks, funds, portfolios, auditable JSON Evidence Packs, data-quality scoring, investor lenses, and multi-source fallback routing.
High-fit targets include awesome-quant-ai, awesome-ai-in-finance, awesome-quant, and awesome-systematic-trading.
uv sync
uv run --with pytest pytest -q
uv run --with ruff ruff checkMIT
This project is for research only and does not constitute investment advice. Markets involve risk.