stockproof 0.3.0__tar.gz

stockproof-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jitao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stockproof-0.3.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: stockproof
+Version: 0.3.0
+Summary: LLM stock research with cited sources (news, earnings, filings), tested on 10 years of point-in-time data: quant lab, portfolio check-up, web dashboard, DeepSeek Harness / MCP plugin. US, China A-shares, HK.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/taoqizhang55-code/stockproof
+Project-URL: Issues, https://github.com/taoqizhang55-code/stockproof/issues
+Keywords: stocks,llm,sentiment,earnings,a-shares,deepseek,deepseek-harness,event-study,backtesting,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Natural Language :: English
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Requires-Dist: pandas>=1.3
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: cn
+Requires-Dist: akshare; python_version >= "3.11" and extra == "cn"
+Provides-Extra: research
+Requires-Dist: yfinance; extra == "research"
+Provides-Extra: mcp
+Requires-Dist: mcp; python_version >= "3.10" and extra == "mcp"
+Dynamic: license-file
+
+# stockproof · 有据
+
+**An LLM reads stock news, earnings reports and company announcements for you, with every point linked to its
+source. A research toolkit then checks each signal against years of prices, and the app tells you what that
+check found.** US stocks, China A-shares and Hong Kong. English and 中文.
+
+[![tests](https://github.com/taoqizhang55-code/stockproof/actions/workflows/tests.yml/badge.svg)](https://github.com/taoqizhang55-code/stockproof/actions/workflows/tests.yml)
+![python](https://img.shields.io/badge/python-3.10%2B-blue) ![license](https://img.shields.io/badge/license-MIT-green)
+· [中文说明](https://github.com/taoqizhang55-code/stockproof/blob/main/README.zh-CN.md)
+
+**Try it offline in 30 seconds** (no API key, no time limit). The demo opens the full dashboard on bundled real
+data; only buttons that need the internet or an AI model are turned off:
+
+```bash
+pip install stockproof
+stockproof demo
+```
+
+No GitHub account or git needed. In mainland China, a mirror is faster:
+`pip install stockproof -i https://pypi.tuna.tsinghua.edu.cn/simple`
+
+Liked it? The [10-minute tour](#10-minute-tour) takes you from the demo to your own stocks, a backtest and a
+portfolio check-up.
+
+![Screen and evidence scorecard](https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/screen.png)
+
+## What it does
+
+**Daily stock watching**
+
+| | Command | What you get |
+|---|---|---|
+| **News mood** | `scan` | Headlines for each stock, scored by an LLM for **relevance** and sentiment. Stories about other companies and repeats of the same event are dropped. |
+| **Earnings** | `earnings` | The company's own release (SEC 8-K/6-K, Eastmoney for China) read by the LLM: tone, guidance, key points and risks, plus the **earnings surprise (SUE)** from point-in-time EPS. |
+| **Announcements** | dashboard | A-share and HK filings are classified by importance (insider selling, regulator letters, buybacks, big contracts and more), and the important ones are summarized. |
+| **Why did it move?** | dashboard | For an unusual move, the LLM explains it using only the news, filings and reports published around that day, cites each one, and says so when nothing explains the move. |
+| **What changed?** | dashboard | The latest two reports compared: results, outlook, new risks, business and payouts. |
+| **Daily digest · calendar · schedule** | `daily`, `calendar`, `schedule` | A daily summary of your watchlist, upcoming reports, and an automatic run every evening (macOS, Windows, Linux), with a desktop notification. |
+
+**Screen and scorecards**
+
+| | Command | What you get |
+|---|---|---|
+| **Whole-market screen** | `screen` | Every A-share ranked by earnings surprise, growth, ROE and trend, with at most 3 per industry and plain-language reasons. Any stock's rank can be looked up. |
+| **Evidence scorecard** | `scorecard` | 0–100 per dimension, with cited evidence, positives and risks. **Each dimension shows whether history tests found it useful, and only tested dimensions count toward the total.** |
+
+**Research and the quant lab**
+
+| | Command | What you get |
+|---|---|---|
+| **Research** | `research` | Event studies and cost-aware backtests: does any of this predict returns? |
+| **Policy signals** | `policy` | 新闻联播 since 2016, read for industry policy: stance and strength on the wording ladder (研究 → 稳步推进 → 加快 → 大力支持). |
+| **Quant lab** | `lab` | Backtest **any** idea described as a small spec (earnings, 业绩预告, policy signals, factors) on point-in-time history, with an illustrated report. The last 2 years are **locked** until you confirm once, and every variant you try **raises the bar** for significance. |
+
+**Your portfolio, and AI agents**
+
+| | Command | What you get |
+|---|---|---|
+| **Portfolio check-up** | `portfolio` | Your holdings on real price history: concentration, holdings that secretly move together, where the risk comes from, and replays of the 2015 / 2018 / 2020 / 2021–22 / 2024 crashes on today's weights. |
+| **AI agents** | `mcp` | 23 MCP tools (DeepSeek Harness plugin in `dsh-plugin/`; Claude and Cursor work too). Every feature above can be asked in plain words ("what can you do?" lists them), and the agent can **do research it can't do alone**: run backtests on real data, screen 5,000 stocks, check your portfolio. |
+
+Everything runs in one local web page (`stockproof dashboard`). The **Home** tab shows what you can do, with clickable examples; the **Lab** tab backtests ideas from a form, no JSON needed; the **Portfolio** tab checks up your holdings and remembers them for next time. The first time you use stockproof in DeepSeek Harness, the agent lists everything it can do and suggests trying the dashboard; after that, ask "what can you do?", type `/stockproof` for ready-made requests, or say "open the dashboard". Say "open the dashboard's lab tab" to jump to a page. Running `stockproof` with no arguments prints the same grouped menu, and in DeepSeek Harness typing `/` lists ready-made prompts (check up a portfolio, backtest an idea, why did it move…).
+
+<p align="center"><img src="https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/dashboard.png" width="64%" alt="Dashboard"> <img src="https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/scorecard.png" width="30%" alt="Evidence scorecard"></p>
+
+### What an LLM can't do alone — and can with stockproof
+
+Ask DeepSeek Harness *"A 股业绩大超预期的公司，财报公布后第二天买入持有 20 天，扣费后能跑赢吗？"*. The model turns the
+question into a spec, the lab runs it on ten years of point-in-time A-share data, and a report opens in your browser.
+The answer was **no**: −3.6% a year (t = −2.0), positive in 3 of 4 years before 2020 and negative every year from 2020 to 2024. Ask for a variant
+and the agent reports that the significance bar went up with the number of tries.
+
+![DeepSeek Harness runs a backtest with stockproof](https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/dsh_lab.png)
+
+<p align="center"><img src="https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/lab_report.png" width="48%" alt="Quant lab report"> <img src="https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/portfolio.png" width="48%" alt="Portfolio check-up"></p>
+
+In DeepSeek Harness, type `/stockproof` for ten ready-made requests:
+
+<p align="center"><img src="https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/dsh_skills.png" width="80%" alt="stockproof skills in the DeepSeek Harness / menu"></p>
+
+## What the research found
+
+Run on the author's data (2016–2026). Each result is a click away in the Research tab, with t-statistics and caveats.
+
+| Question | Answer |
+|---|---|
+| Do prices react to earnings surprises? | **Yes, on the day.** Good minus bad SUE: US large caps +1.7% (t = 5.4), CSI 300 +2.0% (t = 17.4). Dated by the 10-Q or legal deadline instead, the reaction is gone, so the real date matters. |
+| Does the LLM's reading add anything? | **Yes, for the reaction.** On 472 US releases, tone explains the day's move where SUE does not (tone t = 3.1, SUE t = −0.5; R² 0.004 → 0.035). A-shares: negative tone −1.3% (t = −4.2). |
+| …and does it predict what happens next? | **No.** Tone does not predict days 2–61 (t = 0.6). |
+| Post-earnings drift? | Gone in US large caps since 2021. Still present in A-shares (+2.2%, t = 2.5), **but long-only it earns +0.3%/yr after costs** (t = 0.2): the drift sits on the short side, which A-share investors can hardly trade. |
+| Does a fundamentals screen beat the market? | **No.** Top 30 by the composite score: +1.3%/yr vs the same universe (t = 0.5). Momentum alone: +6.4%/yr (t = 1.5, not significant). |
+| Does 新闻联播 policy wording predict industry returns? | **Not tradably.** Over 8,490 new central measures, the strength of the wording is priced in **before the open** (+0.03%, t = 5.3; strongest level +0.12%). Afterwards, supported industries do slightly worse. Backtest: +0.6%/yr (t = 0.4). |
+
+The pattern holds across all of these: public information is priced fast. So stockproof helps you **read and check
+evidence faster**. It does not hand you a trading signal, and the app says this wherever it shows a score.
+
+## Principles
+
+- **Cited, not invented.** The LLM may only use the numbered items it is given. Uncited points are dropped, and
+  "unexplained" is an allowed answer.
+- **Scores carry their track record.** ✓ useful in tests · tested, not significant · ? not tested yet.
+- **Point-in-time.** EPS as first reported, real announcement dates, entry after the news. No peeking ahead.
+- **Any LLM.** DeepSeek (default), OpenAI, Qwen, a local Ollama model, or any OpenAI-compatible API. Each
+  item is read once and cached in SQLite, so daily use costs cents.
+- **No paid data.** SEC EDGAR, Yahoo/Google News RSS, Nasdaq, and Eastmoney / Sina / CCTV / Shenwan via AKShare.
+- **Local and private.** The dashboard listens on 127.0.0.1 only and refuses requests from other websites. API
+  keys are read from the environment and never written to disk.
+
+## Install
+
+Python 3.10+ (3.11+ for China markets).
+
+Works on macOS, Windows and Linux (tested on all three in CI).
+
+```bash
+pip install "stockproof[cn,mcp]"
+```
+
+Then give it an API key (DeepSeek by default; `stockproof providers` lists the others). US earnings also need a
+contact for the SEC.
+
+**macOS / Linux** — add to `~/.zshrc` (or `~/.bashrc`) so it is kept, then open a new terminal:
+
+```bash
+export DEEPSEEK_API_KEY="sk-..."
+export STOCKPROOF_SEC_CONTACT="Your Name you@example.com"
+```
+
+**Windows** — in PowerShell (saved for your user; open a new window afterwards):
+
+```powershell
+setx DEEPSEEK_API_KEY "sk-..."
+setx STOCKPROOF_SEC_CONTACT "Your Name you@example.com"
+```
+
+Then start the dashboard:
+
+```bash
+stockproof dashboard
+```
+
+Add stocks in the page (`AAPL`, `600519`, `300750`, `00700` …) and click **Refresh news** / **Refresh earnings**.
+
+## 10-minute tour
+
+After [installing](#install) and setting your API key:
+
+1. **Look around the demo (2 min).** `stockproof demo`, then open each tab. The Home tab shows what you can do,
+   with examples to click.
+2. **Your own stocks (3 min).** `stockproof dashboard` → Stocks tab → type a few codes (`AAPL, 600519, 00700`) →
+   **Add** → **Refresh news**, then **Refresh earnings**. The first refresh takes about a minute per stock. Click a
+   row for its news, earnings read and announcements; click **Why?** next to an unusual move.
+3. **Test an idea (2 min).** Lab tab → click a template, e.g. "Buy after big earnings beats, hold 20 days" →
+   **Backtest**. Read the verdict, then change a condition and run it again: the significance bar goes up
+   with each variant you try.
+4. **Check your portfolio (1 min).** Portfolio check-up tab → type your holdings (`600519 100, AAPL 50`) → **Check my
+   portfolio**. The report shows concentration, holdings that move together and how today's weights did in
+   past crashes.
+5. **Ask in plain words (1 min, optional).** `stockproof mcp --install-dsh`, restart DeepSeek Harness, type
+   `/stockproof` or ask "what can you do?".
+6. **Keep it up to date (1 min).** `stockproof schedule --time 21:00` refreshes your watchlist every evening and
+   writes the daily digest (macOS, Windows, Linux).
+
+## Commands
+
+```bash
+stockproof dashboard                         # everything in one local page
+stockproof scan AAPL 600519 00700 --lang zh  # news mood report
+stockproof earnings AAPL MSFT --open         # latest releases read by the LLM, with SUE
+stockproof screen --top 30                   # whole-market A-share screen
+stockproof screen --backtest --skip-screen   # test the screening rule on history
+stockproof scorecard                         # evidence cards for the screen's top 10
+stockproof scorecard 600519 NVDA             # …or for any stocks
+stockproof research --market cn --open       # earnings event study + backtest (us / cn)
+stockproof policy                            # 新闻联播 policy study (first run: a few hours of downloads)
+stockproof daily                             # one refresh of the watchlist + daily digest
+stockproof schedule --time 21:00             # run `daily` every evening (macOS, Windows, Linux)
+stockproof calendar                          # who reports in the next two weeks
+stockproof mcp --install-dsh                 # add to DeepSeek Harness on this computer (desktop app too)
+stockproof lab caps                          # quant lab: what can be tested here
+stockproof lab run '{"type":"earnings","filters":[{"field":"sue","op":">=","value":2}],"hold_days":20}' --open
+stockproof lab confirm <id>                  # one shot on the locked holdout
+stockproof portfolio "600519 100, 00700 300, AAPL 50"   # portfolio check-up
+stockproof demo                              # offline demo, no key
+```
+
+Chinese codes can be typed in any common form: `600519`, `600519.SS`, `300750`, `920001`, `700`, `0700.HK`.
+
+## How the pieces work
+
+<details><summary><b>News relevance</b></summary>
+
+A feed for MRK also returns stories about the German Merck KGaA, a feed for GE returns GE HealthCare news, and
+NVDA appears in every "stock market today" article (in one scan only 2 of 14 headlines were really about
+Nvidia). The model gives each headline a relevance score (0–1) and a sentiment score (−1 to +1), with a reason.
+Off-topic stories stay visible but are not counted. When several headlines cover the same event, the model
+marks them as duplicates, so the event counts once.
+</details>
+
+<details><summary><b>Earnings and SUE</b></summary>
+
+SUE = (this quarter's EPS − the same quarter last year) / standard deviation of the previous 8 such changes,
+using EPS as first reported. US quarters come from SEC XBRL, and Q4 = full year − Q1–Q3. A-share reports are
+year-to-date totals, so single quarters are derived by subtraction. Announcement dates come from the 8-K
+Item 2.02 filing (after 16:00 New York time counts as the next day) or from Eastmoney's 预约披露 actual
+disclosure date.
+</details>
+
+<details><summary><b>Screen and scorecard</b></summary>
+
+- **Screen:** fundamentals for all ~5,200 A-shares come from Eastmoney's 业绩报表 tables (one download per report period).
+  - Filters: no ST stocks, market value ≥ 50亿, at least 2 years listed.
+  - Score: the average percentile of five factors.
+- **Scorecard:** six dimensions plus industry policy, with one LLM call per stock per day.
+  - Earnings quality asks whether growth comes from the core business and is backed by cash, or from one-offs.
+  - Announcements count each kind of event once, since one buyback can produce ten filings.
+</details>
+
+<details><summary><b>Backtests</b></summary>
+
+- **Entry and holding:** entry at the close after the reaction (earnings) or at the next open (policy), with
+  capital split into slots and empty slots holding the market.
+- **A-share costs and trading rules:**
+  - Commission 0.025% per side, slippage 0.1% per side.
+  - Stamp duty on sales: 0.1%, or 0.05% from 2023-08-28.
+  - Price limits are respected, at 10% / 20% / 30% depending on the board.
+- **Benchmark:** the equal-weighted average of the stocks studied, because today's CSI 300 members beat the
+  index by 13% a year (survivorship).
+</details>
+
+## Data sources and limits
+
+- **Sources:** SEC EDGAR, Nasdaq, Yahoo/Google News RSS, and Eastmoney, Sina, CCTV and Shenwan via AKShare.
+  - These are free, public, unofficial endpoints. They can change or rate-limit you.
+  - stockproof slows down, retries, and stops with a clear message when a source refuses.
+  - `tools/*_probe.py` checks which sources work from your network.
+- **LLM errors:** models can misread. Every point links to the original, so check it.
+- **Not investment advice.** The research above is part of the reason this tool doesn't give buy or sell calls.
+
+## Development
+
+```bash
+pip install -e ".[dev,mcp]"
+pytest              # ~180 offline tests: fake feeds, fake LLM, fake AKShare; no key or network needed
+python tools/make_demo.py   # rebuild the demo bundle from your own stockproof_data
+```
+
+MIT License.

stockproof-0.3.0/README.md

@@ -0,0 +1,248 @@
+# stockproof · 有据
+
+**An LLM reads stock news, earnings reports and company announcements for you, with every point linked to its
+source. A research toolkit then checks each signal against years of prices, and the app tells you what that
+check found.** US stocks, China A-shares and Hong Kong. English and 中文.
+
+[![tests](https://github.com/taoqizhang55-code/stockproof/actions/workflows/tests.yml/badge.svg)](https://github.com/taoqizhang55-code/stockproof/actions/workflows/tests.yml)
+![python](https://img.shields.io/badge/python-3.10%2B-blue) ![license](https://img.shields.io/badge/license-MIT-green)
+· [中文说明](https://github.com/taoqizhang55-code/stockproof/blob/main/README.zh-CN.md)
+
+**Try it offline in 30 seconds** (no API key, no time limit). The demo opens the full dashboard on bundled real
+data; only buttons that need the internet or an AI model are turned off:
+
+```bash
+pip install stockproof
+stockproof demo
+```
+
+No GitHub account or git needed. In mainland China, a mirror is faster:
+`pip install stockproof -i https://pypi.tuna.tsinghua.edu.cn/simple`
+
+Liked it? The [10-minute tour](#10-minute-tour) takes you from the demo to your own stocks, a backtest and a
+portfolio check-up.
+
+![Screen and evidence scorecard](https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/screen.png)
+
+## What it does
+
+**Daily stock watching**
+
+| | Command | What you get |
+|---|---|---|
+| **News mood** | `scan` | Headlines for each stock, scored by an LLM for **relevance** and sentiment. Stories about other companies and repeats of the same event are dropped. |
+| **Earnings** | `earnings` | The company's own release (SEC 8-K/6-K, Eastmoney for China) read by the LLM: tone, guidance, key points and risks, plus the **earnings surprise (SUE)** from point-in-time EPS. |
+| **Announcements** | dashboard | A-share and HK filings are classified by importance (insider selling, regulator letters, buybacks, big contracts and more), and the important ones are summarized. |
+| **Why did it move?** | dashboard | For an unusual move, the LLM explains it using only the news, filings and reports published around that day, cites each one, and says so when nothing explains the move. |
+| **What changed?** | dashboard | The latest two reports compared: results, outlook, new risks, business and payouts. |
+| **Daily digest · calendar · schedule** | `daily`, `calendar`, `schedule` | A daily summary of your watchlist, upcoming reports, and an automatic run every evening (macOS, Windows, Linux), with a desktop notification. |
+
+**Screen and scorecards**
+
+| | Command | What you get |
+|---|---|---|
+| **Whole-market screen** | `screen` | Every A-share ranked by earnings surprise, growth, ROE and trend, with at most 3 per industry and plain-language reasons. Any stock's rank can be looked up. |
+| **Evidence scorecard** | `scorecard` | 0–100 per dimension, with cited evidence, positives and risks. **Each dimension shows whether history tests found it useful, and only tested dimensions count toward the total.** |
+
+**Research and the quant lab**
+
+| | Command | What you get |
+|---|---|---|
+| **Research** | `research` | Event studies and cost-aware backtests: does any of this predict returns? |
+| **Policy signals** | `policy` | 新闻联播 since 2016, read for industry policy: stance and strength on the wording ladder (研究 → 稳步推进 → 加快 → 大力支持). |
+| **Quant lab** | `lab` | Backtest **any** idea described as a small spec (earnings, 业绩预告, policy signals, factors) on point-in-time history, with an illustrated report. The last 2 years are **locked** until you confirm once, and every variant you try **raises the bar** for significance. |
+
+**Your portfolio, and AI agents**
+
+| | Command | What you get |
+|---|---|---|
+| **Portfolio check-up** | `portfolio` | Your holdings on real price history: concentration, holdings that secretly move together, where the risk comes from, and replays of the 2015 / 2018 / 2020 / 2021–22 / 2024 crashes on today's weights. |
+| **AI agents** | `mcp` | 23 MCP tools (DeepSeek Harness plugin in `dsh-plugin/`; Claude and Cursor work too). Every feature above can be asked in plain words ("what can you do?" lists them), and the agent can **do research it can't do alone**: run backtests on real data, screen 5,000 stocks, check your portfolio. |
+
+Everything runs in one local web page (`stockproof dashboard`). The **Home** tab shows what you can do, with clickable examples; the **Lab** tab backtests ideas from a form, no JSON needed; the **Portfolio** tab checks up your holdings and remembers them for next time. The first time you use stockproof in DeepSeek Harness, the agent lists everything it can do and suggests trying the dashboard; after that, ask "what can you do?", type `/stockproof` for ready-made requests, or say "open the dashboard". Say "open the dashboard's lab tab" to jump to a page. Running `stockproof` with no arguments prints the same grouped menu, and in DeepSeek Harness typing `/` lists ready-made prompts (check up a portfolio, backtest an idea, why did it move…).
+
+<p align="center"><img src="https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/dashboard.png" width="64%" alt="Dashboard"> <img src="https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/scorecard.png" width="30%" alt="Evidence scorecard"></p>
+
+### What an LLM can't do alone — and can with stockproof
+
+Ask DeepSeek Harness *"A 股业绩大超预期的公司，财报公布后第二天买入持有 20 天，扣费后能跑赢吗？"*. The model turns the
+question into a spec, the lab runs it on ten years of point-in-time A-share data, and a report opens in your browser.
+The answer was **no**: −3.6% a year (t = −2.0), positive in 3 of 4 years before 2020 and negative every year from 2020 to 2024. Ask for a variant
+and the agent reports that the significance bar went up with the number of tries.
+
+![DeepSeek Harness runs a backtest with stockproof](https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/dsh_lab.png)
+
+<p align="center"><img src="https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/lab_report.png" width="48%" alt="Quant lab report"> <img src="https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/portfolio.png" width="48%" alt="Portfolio check-up"></p>
+
+In DeepSeek Harness, type `/stockproof` for ten ready-made requests:
+
+<p align="center"><img src="https://raw.githubusercontent.com/taoqizhang55-code/stockproof/main/docs/images/dsh_skills.png" width="80%" alt="stockproof skills in the DeepSeek Harness / menu"></p>
+
+## What the research found
+
+Run on the author's data (2016–2026). Each result is a click away in the Research tab, with t-statistics and caveats.
+
+| Question | Answer |
+|---|---|
+| Do prices react to earnings surprises? | **Yes, on the day.** Good minus bad SUE: US large caps +1.7% (t = 5.4), CSI 300 +2.0% (t = 17.4). Dated by the 10-Q or legal deadline instead, the reaction is gone, so the real date matters. |
+| Does the LLM's reading add anything? | **Yes, for the reaction.** On 472 US releases, tone explains the day's move where SUE does not (tone t = 3.1, SUE t = −0.5; R² 0.004 → 0.035). A-shares: negative tone −1.3% (t = −4.2). |
+| …and does it predict what happens next? | **No.** Tone does not predict days 2–61 (t = 0.6). |
+| Post-earnings drift? | Gone in US large caps since 2021. Still present in A-shares (+2.2%, t = 2.5), **but long-only it earns +0.3%/yr after costs** (t = 0.2): the drift sits on the short side, which A-share investors can hardly trade. |
+| Does a fundamentals screen beat the market? | **No.** Top 30 by the composite score: +1.3%/yr vs the same universe (t = 0.5). Momentum alone: +6.4%/yr (t = 1.5, not significant). |
+| Does 新闻联播 policy wording predict industry returns? | **Not tradably.** Over 8,490 new central measures, the strength of the wording is priced in **before the open** (+0.03%, t = 5.3; strongest level +0.12%). Afterwards, supported industries do slightly worse. Backtest: +0.6%/yr (t = 0.4). |
+
+The pattern holds across all of these: public information is priced fast. So stockproof helps you **read and check
+evidence faster**. It does not hand you a trading signal, and the app says this wherever it shows a score.
+
+## Principles
+
+- **Cited, not invented.** The LLM may only use the numbered items it is given. Uncited points are dropped, and
+  "unexplained" is an allowed answer.
+- **Scores carry their track record.** ✓ useful in tests · tested, not significant · ? not tested yet.
+- **Point-in-time.** EPS as first reported, real announcement dates, entry after the news. No peeking ahead.
+- **Any LLM.** DeepSeek (default), OpenAI, Qwen, a local Ollama model, or any OpenAI-compatible API. Each
+  item is read once and cached in SQLite, so daily use costs cents.
+- **No paid data.** SEC EDGAR, Yahoo/Google News RSS, Nasdaq, and Eastmoney / Sina / CCTV / Shenwan via AKShare.
+- **Local and private.** The dashboard listens on 127.0.0.1 only and refuses requests from other websites. API
+  keys are read from the environment and never written to disk.
+
+## Install
+
+Python 3.10+ (3.11+ for China markets).
+
+Works on macOS, Windows and Linux (tested on all three in CI).
+
+```bash
+pip install "stockproof[cn,mcp]"
+```
+
+Then give it an API key (DeepSeek by default; `stockproof providers` lists the others). US earnings also need a
+contact for the SEC.
+
+**macOS / Linux** — add to `~/.zshrc` (or `~/.bashrc`) so it is kept, then open a new terminal:
+
+```bash
+export DEEPSEEK_API_KEY="sk-..."
+export STOCKPROOF_SEC_CONTACT="Your Name you@example.com"
+```
+
+**Windows** — in PowerShell (saved for your user; open a new window afterwards):
+
+```powershell
+setx DEEPSEEK_API_KEY "sk-..."
+setx STOCKPROOF_SEC_CONTACT "Your Name you@example.com"
+```
+
+Then start the dashboard:
+
+```bash
+stockproof dashboard
+```
+
+Add stocks in the page (`AAPL`, `600519`, `300750`, `00700` …) and click **Refresh news** / **Refresh earnings**.
+
+## 10-minute tour
+
+After [installing](#install) and setting your API key:
+
+1. **Look around the demo (2 min).** `stockproof demo`, then open each tab. The Home tab shows what you can do,
+   with examples to click.
+2. **Your own stocks (3 min).** `stockproof dashboard` → Stocks tab → type a few codes (`AAPL, 600519, 00700`) →
+   **Add** → **Refresh news**, then **Refresh earnings**. The first refresh takes about a minute per stock. Click a
+   row for its news, earnings read and announcements; click **Why?** next to an unusual move.
+3. **Test an idea (2 min).** Lab tab → click a template, e.g. "Buy after big earnings beats, hold 20 days" →
+   **Backtest**. Read the verdict, then change a condition and run it again: the significance bar goes up
+   with each variant you try.
+4. **Check your portfolio (1 min).** Portfolio check-up tab → type your holdings (`600519 100, AAPL 50`) → **Check my
+   portfolio**. The report shows concentration, holdings that move together and how today's weights did in
+   past crashes.
+5. **Ask in plain words (1 min, optional).** `stockproof mcp --install-dsh`, restart DeepSeek Harness, type
+   `/stockproof` or ask "what can you do?".
+6. **Keep it up to date (1 min).** `stockproof schedule --time 21:00` refreshes your watchlist every evening and
+   writes the daily digest (macOS, Windows, Linux).
+
+## Commands
+
+```bash
+stockproof dashboard                         # everything in one local page
+stockproof scan AAPL 600519 00700 --lang zh  # news mood report
+stockproof earnings AAPL MSFT --open         # latest releases read by the LLM, with SUE
+stockproof screen --top 30                   # whole-market A-share screen
+stockproof screen --backtest --skip-screen   # test the screening rule on history
+stockproof scorecard                         # evidence cards for the screen's top 10
+stockproof scorecard 600519 NVDA             # …or for any stocks
+stockproof research --market cn --open       # earnings event study + backtest (us / cn)
+stockproof policy                            # 新闻联播 policy study (first run: a few hours of downloads)
+stockproof daily                             # one refresh of the watchlist + daily digest
+stockproof schedule --time 21:00             # run `daily` every evening (macOS, Windows, Linux)
+stockproof calendar                          # who reports in the next two weeks
+stockproof mcp --install-dsh                 # add to DeepSeek Harness on this computer (desktop app too)
+stockproof lab caps                          # quant lab: what can be tested here
+stockproof lab run '{"type":"earnings","filters":[{"field":"sue","op":">=","value":2}],"hold_days":20}' --open
+stockproof lab confirm <id>                  # one shot on the locked holdout
+stockproof portfolio "600519 100, 00700 300, AAPL 50"   # portfolio check-up
+stockproof demo                              # offline demo, no key
+```
+
+Chinese codes can be typed in any common form: `600519`, `600519.SS`, `300750`, `920001`, `700`, `0700.HK`.
+
+## How the pieces work
+
+<details><summary><b>News relevance</b></summary>
+
+A feed for MRK also returns stories about the German Merck KGaA, a feed for GE returns GE HealthCare news, and
+NVDA appears in every "stock market today" article (in one scan only 2 of 14 headlines were really about
+Nvidia). The model gives each headline a relevance score (0–1) and a sentiment score (−1 to +1), with a reason.
+Off-topic stories stay visible but are not counted. When several headlines cover the same event, the model
+marks them as duplicates, so the event counts once.
+</details>
+
+<details><summary><b>Earnings and SUE</b></summary>
+
+SUE = (this quarter's EPS − the same quarter last year) / standard deviation of the previous 8 such changes,
+using EPS as first reported. US quarters come from SEC XBRL, and Q4 = full year − Q1–Q3. A-share reports are
+year-to-date totals, so single quarters are derived by subtraction. Announcement dates come from the 8-K
+Item 2.02 filing (after 16:00 New York time counts as the next day) or from Eastmoney's 预约披露 actual
+disclosure date.
+</details>
+
+<details><summary><b>Screen and scorecard</b></summary>
+
+- **Screen:** fundamentals for all ~5,200 A-shares come from Eastmoney's 业绩报表 tables (one download per report period).
+  - Filters: no ST stocks, market value ≥ 50亿, at least 2 years listed.
+  - Score: the average percentile of five factors.
+- **Scorecard:** six dimensions plus industry policy, with one LLM call per stock per day.
+  - Earnings quality asks whether growth comes from the core business and is backed by cash, or from one-offs.
+  - Announcements count each kind of event once, since one buyback can produce ten filings.
+</details>
+
+<details><summary><b>Backtests</b></summary>
+
+- **Entry and holding:** entry at the close after the reaction (earnings) or at the next open (policy), with
+  capital split into slots and empty slots holding the market.
+- **A-share costs and trading rules:**
+  - Commission 0.025% per side, slippage 0.1% per side.
+  - Stamp duty on sales: 0.1%, or 0.05% from 2023-08-28.
+  - Price limits are respected, at 10% / 20% / 30% depending on the board.
+- **Benchmark:** the equal-weighted average of the stocks studied, because today's CSI 300 members beat the
+  index by 13% a year (survivorship).
+</details>
+
+## Data sources and limits
+
+- **Sources:** SEC EDGAR, Nasdaq, Yahoo/Google News RSS, and Eastmoney, Sina, CCTV and Shenwan via AKShare.
+  - These are free, public, unofficial endpoints. They can change or rate-limit you.
+  - stockproof slows down, retries, and stops with a clear message when a source refuses.
+  - `tools/*_probe.py` checks which sources work from your network.
+- **LLM errors:** models can misread. Every point links to the original, so check it.
+- **Not investment advice.** The research above is part of the reason this tool doesn't give buy or sell calls.
+
+## Development
+
+```bash
+pip install -e ".[dev,mcp]"
+pytest              # ~180 offline tests: fake feeds, fake LLM, fake AKShare; no key or network needed
+python tools/make_demo.py   # rebuild the demo bundle from your own stockproof_data
+```
+
+MIT License.

stockproof-0.3.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stockproof"
+version = "0.3.0"
+description = "LLM stock research with cited sources (news, earnings, filings), tested on 10 years of point-in-time data: quant lab, portfolio check-up, web dashboard, DeepSeek Harness / MCP plugin. US, China A-shares, HK."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["stocks", "llm", "sentiment", "earnings", "a-shares", "deepseek", "deepseek-harness", "event-study", "backtesting", "mcp"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Natural Language :: Chinese (Simplified)",
+    "Natural Language :: English",
+]
+dependencies = [
+    "requests>=2.25",
+    "pandas>=1.3",
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+# China markets (A-shares, Hong Kong). AKShare needs Python 3.11+
+cn = ["akshare; python_version >= \"3.11\""]
+# price download for `stockproof research --download`
+research = ["yfinance"]
+# `stockproof mcp`: tools for AI agents (MCP needs Python 3.10+)
+mcp = ["mcp; python_version >= \"3.10\""]
+
+[project.urls]
+Homepage = "https://github.com/taoqizhang55-code/stockproof"
+Issues = "https://github.com/taoqizhang55-code/stockproof/issues"
+
+[project.scripts]
+stockproof = "stockproof.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["stockproof", "stockproof.*"]
+
+[tool.setuptools.package-data]
+stockproof = ["demo_data/*", "demo_data/**/*"]

stockproof-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stockproof-0.3.0/setup.py

@@ -0,0 +1,5 @@
+# Lets older pip versions (before 21.3) do an editable install: pip install -e .
+# All real settings live in pyproject.toml.
+from setuptools import setup
+
+setup()

stockproof-0.3.0/stockproof/__init__.py

@@ -0,0 +1,15 @@
+"""stockproof (有据): an LLM reads stock news, earnings and filings with cited sources, and history checks what matters."""
+
+import os as _os
+
+__version__ = "0.3.0"
+
+
+def compat_env() -> None:
+    """The project was called marketmood until 0.2: keep reading the old MARKETMOOD_* variables."""
+    for k, v in list(_os.environ.items()):
+        if k.startswith("MARKETMOOD_"):
+            _os.environ.setdefault("STOCKPROOF_" + k[len("MARKETMOOD_"):], v)
+
+
+compat_env()

stockproof-0.3.0/stockproof/__main__.py

@@ -0,0 +1,5 @@
+"""Allows `python3 -m stockproof ...` without installing."""
+from stockproof.cli import main
+
+if __name__ == "__main__":
+    main()