"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Optional Tushare fallback adapters for China-market flow tools.
The public Eastmoney endpoints are free and remain the primary source for these
tools. When they are unavailable, a configured Tushare token can recover the
same research workflow through a separate provider with a compatible envelope.
"""
from __future__ import annotations
import math
from datetime import date, timedelta
from typing import Any
from src.config.accessor import get_env_config
_TUSHARE_TOKEN_PLACEHOLDERS = {"", "your-tushare-token"}
class TushareFallbackUnavailable(RuntimeError):
"""Raised when the optional Tushare fallback cannot be used."""
def _pro_api() -> Any:
token = get_env_config().data.tushare_token.strip()
if token in _TUSHARE_TOKEN_PLACEHOLDERS:
raise TushareFallbackUnavailable("TUSHARE_TOKEN is not configured")
try:
import tushare as ts
except Exception as exc: # noqa: BLE001 - import errors vary by install
raise TushareFallbackUnavailable(f"tushare import failed: {exc}") from exc
return ts.pro_api(token)
def _records(frame: Any) -> list[dict[str, Any]]:
if frame is None:
return []
if bool(getattr(frame, "empty", False)):
return []
if hasattr(frame, "to_dict"):
rows = frame.to_dict("records")
return [row for row in rows if isinstance(row, dict)]
if isinstance(frame, list):
return [row for row in frame if isinstance(row, dict)]
return []
def _compact_date(value: str) -> str:
digits = str(value).strip().replace("-", "")
if len(digits) != 8 or not digits.isdigit():
raise TushareFallbackUnavailable(f"invalid date for tushare fallback: {value!r}")
return digits
def _dashed_date(value: Any) -> str | None:
if value is None:
return None
digits = str(value).strip().replace("-", "")
if len(digits) == 8 and digits.isdigit():
return f"{digits[:4]}-{digits[4:6]}-{digits[6:]}"
return str(value)[:10] if value else None
def _date_window(days: int) -> tuple[str, str]:
end = date.today()
# Market holidays/weekends mean calendar days need slack to recover the
# requested number of trading rows.
start = end - timedelta(days=max(days * 3, 10))
return start.strftime("%Y%m%d"), end.strftime("%Y%m%d")
def _to_float(value: Any) -> float | None:
if value in (None, "", "-"):
return None
try:
return float(value)
except (TypeError, ValueError):
return None
def _net_amount(row: dict[str, Any], buy_key: str, sell_key: str) -> float | None:
buy = _to_float(row.get(buy_key))
sell = _to_float(row.get(sell_key))
if buy is None or sell is None or not math.isfinite(buy) or not math.isfinite(sell):
return None
# Tushare moneyflow amount fields are in 10k CNY; the Eastmoney tool emits
# CNY, so convert to keep the existing bucket units.
value = (buy - sell) * 10_000
return value if math.isfinite(value) else None
def _ts_code(code: str) -> str:
token = code.strip().upper()
if "." in token:
bare, suffix = token.split(".", 1)
if suffix in {"SH", "SZ", "BJ"} and len(bare) == 6 and bare.isdigit():
return f"{bare}.{suffix}"
raise TushareFallbackUnavailable(f"unsupported Tushare symbol: {code}")
for prefix in ("SH", "SZ", "BJ"):
if token.startswith(prefix):
token = token[len(prefix) :]
break
if len(token) != 6 or not token.isdigit():
raise TushareFallbackUnavailable(f"unsupported Tushare symbol: {code}")
if token.startswith(("4", "8", "920")):
suffix = "BJ"
elif token.startswith(("5", "6", "9")):
suffix = "SH"
elif token.startswith(("0", "2", "3")):
suffix = "SZ"
else:
raise TushareFallbackUnavailable(f"unsupported Tushare symbol: {code}")
return f"{token}.{suffix}"
def fetch_fund_flow(symbol: str, *, days: int) -> dict[str, Any]:
"""Read daily Tushare buckets with explicit units and missing observations.
Args:
symbol: A-share instrument accepted by the Tushare adapter.
days: Maximum number of recent trading days to return.
Returns:
Source-labelled rows in CNY, with total flow separate from main orders.
Raises:
TushareFallbackUnavailable: Symbol, credentials or data are unavailable.
"""
ts_code = _ts_code(symbol)
start_date, end_date = _date_window(days)
rows = _records(
_pro_api().moneyflow(ts_code=ts_code, start_date=start_date, end_date=end_date)
)
parsed: list[dict[str, Any]] = []
for row in rows:
large = _net_amount(row, "buy_lg_amount", "sell_lg_amount")
super_large = _net_amount(row, "buy_elg_amount", "sell_elg_amount")
net_total = _to_float(row.get("net_mf_amount"))
net_total = net_total * 10_000 if net_total is not None else None
if net_total is not None and not math.isfinite(net_total):
net_total = None
# moneyflow.net_mf_amount is total net flow, not the main-order bucket.
# https://tushare.pro/document/2?doc_id=170
main = large + super_large if large is not None and super_large is not None else None
if main is not None and not math.isfinite(main):
main = None
parsed.append(
{
"timestamp": _dashed_date(row.get("trade_date")),
"main": main,
"net_total": net_total,
"small": _net_amount(row, "buy_sm_amount", "sell_sm_amount"),
"medium": _net_amount(row, "buy_md_amount", "sell_md_amount"),
"large": large,
"super_large": super_large,
}
)
if not parsed:
raise TushareFallbackUnavailable("tushare returned no fund-flow rows")
parsed.sort(key=lambda item: item.get("timestamp") or "")
parsed = parsed[-days:]
return {
"symbol": symbol,
"ts_code": ts_code,
"source": "tushare",
"rows": parsed,
"methodology": (
"Tushare moneyflow active buy/sell buckets in CNY; main = large + "
"super_large; net_total is the provider's total net flow. "
"Provider classifications may differ from Eastmoney."
),
}
def fetch_dragon_tiger(trade_date: str, code: str | None) -> dict[str, Any]:
compact = _compact_date(trade_date)
ts_code = _ts_code(code) if code else None
pro = _pro_api()
kwargs: dict[str, str] = {"trade_date": compact}
if ts_code:
kwargs["ts_code"] = ts_code
appearances_raw = _records(pro.top_list(**kwargs))
appearances = [
{
"code": str(row.get("ts_code", "")).split(".", 1)[0] or None,
"name": row.get("name"),
"close": row.get("close"),
"change_pct": row.get("pct_change"),
"net_buy": row.get("net_amount"),
"buy_amount": row.get("l_buy"),
"sell_amount": row.get("l_sell"),
"turnover": row.get("amount"),
"reason": row.get("reason"),
}
for row in appearances_raw
]
data: dict[str, Any] = {
"date": _dashed_date(compact),
"count": len(appearances_raw),
"appearances": appearances,
}
if ts_code:
seats_raw = _records(pro.top_inst(trade_date=compact, ts_code=ts_code))
data["code"] = ts_code.split(".", 1)[0]
data["seats"] = [
{
"seat": row.get("exalter"),
"side": row.get("side"),
"buy": row.get("buy"),
"sell": row.get("sell"),
"net": row.get("net_buy"),
"rank": None,
}
for row in seats_raw
]
return data
#: Tushare's northbound fields changed to turnover at the 2024-08-19
#: disclosure cutover (issue #1481). Keep the boundary explicit so a
#: post-cutover turnover value cannot be returned under a net-flow key.
_NORTHBOUND_SEMANTICS_BOUNDARY = "2024-08-19"
_NORTHBOUND_NOTE = (
"HKEX stopped publishing northbound daily net buy on "
f"{_NORTHBOUND_SEMANTICS_BOUNDARY}. From that date onward tushare's "
"hgt/sgt/north_money carry northbound TURNOVER (verified equal to the "
"HKEX official Stock Connect Daily Statistics Total Turnover to the "
"cent); rows before the boundary are NET BUY. Post-cutover rows are "
"returned under turnover_* fields and their net-flow fields are null. "
"Both eras are in million CNY."
)
def fetch_northbound_flow(*, lookback_days: int) -> dict[str, Any]:
"""Fetch northbound Stock-Connect flow via tushare ``moneyflow_hsgt``.
Values are passed through in tushare's native unit (million CNY). The
legacy ×100 rescale to 10k CNY assumed every row was a net buy in
million CNY, but the field semantics changed at the 2024-08-19 HKEX
disclosure reform: post-boundary rows are turnover (cross-verified
against HKEX official daily statistics, see issue #1481), so a single
constant factor cannot serve both eras. The envelope therefore keeps
the raw values and documents the boundary in ``note`` instead.
"""
start_date, end_date = _date_window(lookback_days)
rows = _records(_pro_api().moneyflow_hsgt(start_date=start_date, end_date=end_date))
history: list[dict[str, Any]] = []
for row in rows:
trade_date = _dashed_date(row.get("trade_date"))
if trade_date is None:
continue
shanghai = _to_float(row.get("hgt"))
shenzhen = _to_float(row.get("sgt"))
total = _to_float(row.get("north_money"))
if trade_date >= _NORTHBOUND_SEMANTICS_BOUNDARY:
history.append(
{
"trade_date": trade_date,
"shanghai_connect": None,
"shenzhen_connect": None,
"total": None,
"turnover_shanghai": shanghai,
"turnover_shenzhen": shenzhen,
"turnover_total": total,
}
)
else:
history.append(
{
"trade_date": trade_date,
"shanghai_connect": shanghai,
"shenzhen_connect": shenzhen,
"total": total,
"turnover_shanghai": None,
"turnover_shenzhen": None,
"turnover_total": None,
}
)
history.sort(key=lambda item: item.get("trade_date") or "")
history = history[-lookback_days:]
latest = history[-1] if history else {}
return {
"unit": "CNY million",
"lookback_days": lookback_days,
"note": _NORTHBOUND_NOTE,
"realtime": {
"shanghai_connect": latest.get("shanghai_connect"),
"shenzhen_connect": latest.get("shenzhen_connect"),
"total": latest.get("total"),
"turnover_shanghai": latest.get("turnover_shanghai"),
"turnover_shenzhen": latest.get("turnover_shenzhen"),
"turnover_total": latest.get("turnover_total"),
},
"history": history,
}
def fetch_margin_trading(code: str, *, days: int) -> dict[str, Any]:
ts_code = _ts_code(code)
start_date, end_date = _date_window(days)
rows = _records(
_pro_api().margin_detail(ts_code=ts_code, start_date=start_date, end_date=end_date)
)
normalized = [
{
"trade_date": _dashed_date(row.get("trade_date")),
"financing_balance": _to_float(row.get("rzye")),
"financing_buy": _to_float(row.get("rzmre")),
"financing_repay": _to_float(row.get("rzche")),
"short_balance": _to_float(row.get("rqye")),
"short_volume": _to_float(row.get("rqyl")),
"margin_total_balance": _to_float(row.get("rzrqye")),
}
for row in rows
]
normalized.sort(key=lambda item: item.get("trade_date") or "", reverse=True)
return {"code": ts_code.split(".", 1)[0], "ts_code": ts_code, "rows": normalized[:days]}