docs: add China A-share support design plan
Design for integrating AKShare as data vendor to support Chinese A-share stock analysis. Auto-detects market from ticker suffix (.SH/.SZ), routes to AKShare for OHLCV, fundamentals, news, and social sentiment data. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
alexwei12
parent
573f75b3ef
commit
c95253a195
|
|
@ -0,0 +1,140 @@
|
|||
# China A-Share Support for TradingAgents
|
||||
|
||||
## Overview
|
||||
|
||||
Add China A-share (Shanghai SSE / Shenzhen SZSE) stock analysis capability to TradingAgents, using AKShare as the data vendor. The implementation leverages the existing vendor routing framework — no changes to agent logic, LangGraph workflow, or LLM client layer.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
| Decision | Choice | Rationale |
|
||||
|----------|--------|-----------|
|
||||
| Data source | AKShare | Free, no API key, covers OHLCV/fundamentals/news/social sentiment, actively maintained (~18k GitHub stars) |
|
||||
| Chinese data handling | Feed Chinese text directly to LLM | Modern LLMs handle Chinese well; avoids translation overhead and loss of financial terminology accuracy |
|
||||
| Market identification | Ticker suffix auto-detection (`.SH`/`.SZ`) | Zero config for users, no API signature changes, backward compatible |
|
||||
| Implementation scope | All 4 analyst types at once | AKShare supports all data categories; incremental approach saves no real effort |
|
||||
| Global macro news | Auto-switch by ticker market | A-share tickers get Chinese macro news (PBOC, policy); US tickers keep existing logic |
|
||||
| Social sentiment | Append to `get_news` return | Avoids new tool definitions and agent binding changes |
|
||||
|
||||
## Architecture
|
||||
|
||||
### Data Flow
|
||||
|
||||
```
|
||||
propagate("600519.SH", "2026-01-15")
|
||||
│
|
||||
▼
|
||||
ticker_utils.detect_market("600519.SH") → "CN_SH"
|
||||
│
|
||||
▼
|
||||
interface.route_to_vendor() → forces "akshare" for CN tickers
|
||||
│
|
||||
▼
|
||||
akshare_data.py / akshare_news.py
|
||||
│
|
||||
▼
|
||||
Analyst agents receive data (Chinese text) → LLM analyzes normally
|
||||
```
|
||||
|
||||
For US tickers (e.g., `"NVDA"`), the existing yfinance/alpha_vantage routing is unchanged.
|
||||
|
||||
### Routing Priority
|
||||
|
||||
1. Ticker is A-share (`.SH`/`.SZ`) → **force akshare** (ignore config `data_vendors`)
|
||||
2. Ticker is US/other → follow existing config routing (yfinance / alpha_vantage)
|
||||
|
||||
## New Files
|
||||
|
||||
### `tradingagents/dataflows/ticker_utils.py`
|
||||
|
||||
Ticker market detection and parsing utilities.
|
||||
|
||||
```python
|
||||
def detect_market(ticker: str) -> str:
|
||||
"""Detect market from ticker suffix.
|
||||
|
||||
Returns: "CN_SH", "CN_SZ", "US", etc.
|
||||
"""
|
||||
|
||||
def parse_ticker(ticker: str) -> tuple[str, str]:
|
||||
"""Split ticker into code and exchange.
|
||||
|
||||
"600519.SH" → ("600519", "sh")
|
||||
"NVDA" → ("NVDA", "")
|
||||
"""
|
||||
|
||||
def is_china_stock(ticker: str) -> bool:
|
||||
"""Shortcut: returns True for .SH/.SZ tickers."""
|
||||
```
|
||||
|
||||
### `tradingagents/dataflows/akshare_data.py`
|
||||
|
||||
Core stock data and fundamentals via AKShare. All functions return formatted strings matching the existing yfinance output pattern, so analyst prompts work unchanged.
|
||||
|
||||
| Function | AKShare API | Notes |
|
||||
|----------|------------|-------|
|
||||
| `get_stock_data(ticker, start, end)` | `ak.stock_zh_a_hist()` | Daily OHLCV, output as CSV string |
|
||||
| `get_indicators(ticker, start, end)` | OHLCV + `stockstats` calculation | Same approach as yfinance — compute SMA/EMA/MACD/RSI/BOLL from raw OHLCV using stockstats (already a project dependency) |
|
||||
| `get_fundamentals(ticker)` | `ak.stock_individual_info_em()` + `ak.stock_financial_abstract_ths()` | Company overview, Market Cap, PE, ROE, etc. |
|
||||
| `get_balance_sheet(ticker)` | `ak.stock_balance_sheet_by_report_em()` | Balance sheet (Chinese field names, LLM handles directly) |
|
||||
| `get_cashflow(ticker)` | `ak.stock_cash_flow_sheet_by_report_em()` | Cash flow statement |
|
||||
| `get_income_statement(ticker)` | `ak.stock_profit_sheet_by_report_em()` | Income/profit statement |
|
||||
|
||||
### `tradingagents/dataflows/akshare_news.py`
|
||||
|
||||
News, macro, insider, and social sentiment data.
|
||||
|
||||
| Function | AKShare API | Notes |
|
||||
|----------|------------|-------|
|
||||
| `get_news(ticker)` | `ak.stock_news_em()` + `ak.stock_hot_rank_em()` | Company news from Eastmoney, with social heat ranking/sentiment appended at the end |
|
||||
| `get_global_news()` | `ak.news_cctv()` or `ak.stock_zh_a_alerts_cls()` | Chinese macro news (CCTV Finance / CLS alerts), replaces "Federal Reserve" queries |
|
||||
| `get_insider_transactions(ticker)` | `ak.stock_share_hold_change_ths()` | Shareholder increase/decrease holdings |
|
||||
|
||||
## Modified Files
|
||||
|
||||
### `tradingagents/dataflows/interface.py`
|
||||
|
||||
Add market detection before vendor routing:
|
||||
|
||||
```python
|
||||
from .ticker_utils import is_china_stock
|
||||
|
||||
def route_to_vendor(tool_name, category, config, ticker=None):
|
||||
# A-share auto-routing (highest priority)
|
||||
if ticker and is_china_stock(ticker):
|
||||
vendor = "akshare"
|
||||
else:
|
||||
# existing logic: check tool_vendors, then data_vendors
|
||||
vendor = config["tool_vendors"].get(tool_name) or config["data_vendors"].get(category, "yfinance")
|
||||
|
||||
# add akshare dispatch
|
||||
if vendor == "akshare":
|
||||
if category == "news_data":
|
||||
return akshare_news_dispatch(tool_name, ...)
|
||||
else:
|
||||
return akshare_data_dispatch(tool_name, ...)
|
||||
# existing yfinance/alpha_vantage dispatch...
|
||||
```
|
||||
|
||||
### `pyproject.toml` + `requirements.txt`
|
||||
|
||||
Add dependency:
|
||||
```
|
||||
akshare>=1.14.0
|
||||
```
|
||||
|
||||
## Prerequisites & Risks
|
||||
|
||||
| Item | Status | Mitigation |
|
||||
|------|--------|------------|
|
||||
| AKShare library | Not installed | `pip install akshare` — no API key needed |
|
||||
| A-share trading calendar | Chinese holidays differ (Spring Festival, Golden Week) | If date falls on non-trading day, AKShare returns empty data — add fallback to nearest trading day |
|
||||
| Network access | AKShare scrapes Eastmoney/Sina — may be slow or blocked outside China | Document as known limitation; works well in domestic network |
|
||||
| Financial report format | CAS (Chinese Accounting Standards), field names in Chinese | Pass Chinese text directly to LLM — confirmed approach |
|
||||
| Error handling | AKShare calls may fail (network, rate limit) | Wrap all calls in try/except, return friendly error string (matches existing vendor pattern) |
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Hong Kong stocks (`.HK`) — can be added later with same pattern
|
||||
- Real-time/intraday data — current system is daily granularity
|
||||
- Agent prompt translation — LLMs handle mixed language data
|
||||
- Config-based A-share vendor selection — A-share always uses AKShare for now
|
||||
Loading…
Reference in New Issue