"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
fix(data): declare per-market volume units in market-data provenance
shadowinlifeda7ae2e1aefd
diff --git a/agent/backtest/loaders/akshare_loader.py b/agent/backtest/loaders/akshare_loader.pyindex eca72e875..b773198af 100644--- a/agent/backtest/loaders/akshare_loader.py+++ b/agent/backtest/loaders/akshare_loader.py@@ -77,6 +77,11 @@ class DataLoader:name = "akshare"markets = {"a_share", "us_equity", "hk_equity", "futures", "fund", "macro", "forex"}+ # stock_zh_a_hist empirically returns board lots (HKUDS/Vibe-Trading#1062;+ # 600519.SH 2026-07-31 ratio 1.00 vs tencent/eastmoney). Note: akshare's+ # own documentation states shares for this interface — the docs disagree+ # with the actual behavior. Other markets stay undeclared.+ volume_units = {"a_share": "lots"}requires_auth = Falsedef is_available(self) -> bool:diff --git a/agent/backtest/loaders/baostock_loader.py b/agent/backtest/loaders/baostock_loader.pyindex 8fb6b4f13..7e66b9bd8 100644--- a/agent/backtest/loaders/baostock_loader.py+++ b/agent/backtest/loaders/baostock_loader.py@@ -35,6 +35,11 @@ class DataLoader:name = "baostock"markets = {"a_share"}+ # BaoStock natively reports volume in single shares, unlike the other+ # A-share sources which report board lots (HKUDS/Vibe-Trading#1062).+ # Empirically verified 2026-08-11: 600519.SH 2026-07-31 = 5,512,752+ # shares vs tencent/eastmoney 55,128 lots (ratio exactly 100.0).+ volume_units = {"a_share": "shares"}requires_auth = Falsedef is_available(self) -> bool:diff --git a/agent/backtest/loaders/base.py b/agent/backtest/loaders/base.pyindex e19dca51b..ebd1934d0 100644--- a/agent/backtest/loaders/base.py+++ b/agent/backtest/loaders/base.py@@ -617,7 +617,17 @@ def _duckdb_sql_string(path: Path) -> str:@runtime_checkableclass DataLoaderProtocol(Protocol):- """Interface that every data source loader must satisfy."""+ """Interface that every data source loader must satisfy.++ Optional class attribute ``volume_units: dict[str, str]`` (not part of the+ structural check so existing loaders keep working): declares the unit of+ the ``volume`` column per market, keyed by market name — e.g.+ ``{"a_share": "lots", "hk_equity": "shares"}``. ``"lots"`` means board+ lots (1 A-share lot = 100 shares); ``"shares"`` means single shares.+ Sources differ natively (see HKUDS/Vibe-Trading#1062), so consumers must+ read the per-symbol ``volume_unit`` from ``_provenance`` instead of+ assuming a unit; a missing market entry surfaces as ``null`` (undeclared).+ """name: strmarkets: set[str]diff --git a/agent/backtest/loaders/eastmoney_loader.py b/agent/backtest/loaders/eastmoney_loader.pyindex bc9582716..12887545f 100644--- a/agent/backtest/loaders/eastmoney_loader.py+++ b/agent/backtest/loaders/eastmoney_loader.py@@ -54,6 +54,12 @@ class DataLoader:name = "eastmoney"markets = {"a_share", "hk_equity", "us_equity"}+ # Volume unit is market-dependent (HKUDS/Vibe-Trading#1062): the A-share+ # push2 endpoint reports board lots, the HK endpoint single shares —+ # empirically verified 2026-08-11 (600519.SH ratio 1.00 vs tencent;+ # 00700.HK ratio 1.00 vs tencent/yfinance). us_equity stays undeclared+ # until empirically verified.+ volume_units = {"a_share": "lots", "hk_equity": "shares"}requires_auth = Falsedef is_available(self) -> bool:diff --git a/agent/backtest/loaders/mootdx_loader.py b/agent/backtest/loaders/mootdx_loader.pyindex 2fe9d0bbc..f9177c2e1 100644--- a/agent/backtest/loaders/mootdx_loader.py+++ b/agent/backtest/loaders/mootdx_loader.py@@ -69,6 +69,11 @@ class DataLoader:name = "mootdx"markets = {"a_share"}+ # Tongdaxin K-line convention is board lots (HKUDS/Vibe-Trading#1062).+ # Tentative declaration: TDX quote servers were unreachable from the+ # audit environment; the cross-source consistency test pins this at+ # runtime where TDX access exists.+ volume_units = {"a_share": "lots"}requires_auth = Falsedef __init__(self) -> None:diff --git a/agent/backtest/loaders/stooq_loader.py b/agent/backtest/loaders/stooq_loader.pyindex 4b6aeac9b..18c9bff10 100644--- a/agent/backtest/loaders/stooq_loader.py+++ b/agent/backtest/loaders/stooq_loader.py@@ -77,6 +77,9 @@ class DataLoader:name = "stooq"markets = {"us_equity"}+ # Stooq US EOD volume is single shares (universal US convention,+ # HKUDS/Vibe-Trading#1062).+ volume_units = {"us_equity": "shares"}requires_auth = Falsedef __init__(self) -> None:diff --git a/agent/backtest/loaders/tencent_loader.py b/agent/backtest/loaders/tencent_loader.pyindex 7e140356f..7180ce7e9 100644--- a/agent/backtest/loaders/tencent_loader.py+++ b/agent/backtest/loaders/tencent_loader.py@@ -38,6 +38,11 @@ class DataLoader:name = "tencent"markets = {"a_share", "hk_equity"}+ # Volume unit is market-dependent (HKUDS/Vibe-Trading#1062): the A-share+ # endpoint reports board lots (1 lot = 100 shares) while the HK endpoint+ # reports single shares. Empirically verified 2026-08-11 against+ # 600519.SH (55,128 lots) and 00700.HK (31,100,240 shares).+ volume_units = {"a_share": "lots", "hk_equity": "shares"}requires_auth = Falsedef is_available(self) -> bool:diff --git a/agent/backtest/loaders/tushare.py b/agent/backtest/loaders/tushare.pyindex 66bed702f..187c1d595 100644--- a/agent/backtest/loaders/tushare.py+++ b/agent/backtest/loaders/tushare.py@@ -119,6 +119,9 @@ class DataLoader:name = "tushare"markets = {"a_share", "hk_equity", "futures", "fund"}+ # Tushare daily() documents vol in board lots (HKUDS/Vibe-Trading#1062).+ # hk_equity (hk_daily) stays undeclared until empirically verified.+ volume_units = {"a_share": "lots"}requires_auth = Truedef is_available(self) -> bool:diff --git a/agent/backtest/loaders/yahoo_loader.py b/agent/backtest/loaders/yahoo_loader.pyindex 1ccb531c5..a9c54ac17 100644--- a/agent/backtest/loaders/yahoo_loader.py+++ b/agent/backtest/loaders/yahoo_loader.py@@ -178,6 +178,10 @@ class DataLoader:markets = {"us_equity", "hk_equity", "india_equity", "kr_equity", "ca_equity",}+ # Yahoo chart volume is single shares for US/HK equities+ # (HKUDS/Vibe-Trading#1062; HK verified 2026-08-11, 00700.HK ratio 1.00+ # vs tencent/eastmoney). Other equity markets stay undeclared.+ volume_units = {"us_equity": "shares", "hk_equity": "shares"}requires_auth = Falsedef is_available(self) -> bool:diff --git a/agent/backtest/loaders/yfinance_loader.py b/agent/backtest/loaders/yfinance_loader.pyindex de2cd088a..7dd0dcb59 100644--- a/agent/backtest/loaders/yfinance_loader.py+++ b/agent/backtest/loaders/yfinance_loader.py@@ -234,6 +234,10 @@ class DataLoader:markets = {"us_equity", "hk_equity", "india_equity", "kr_equity", "ca_equity", "crypto",}+ # yfinance volume is single shares for US/HK equities+ # (HKUDS/Vibe-Trading#1062; HK verified 2026-08-11, 00700.HK ratio 1.00+ # vs tencent/eastmoney). Crypto base-asset units stay undeclared.+ volume_units = {"us_equity": "shares", "hk_equity": "shares"}requires_auth = Falsedef is_available(self) -> bool:diff --git a/agent/mcp_server.py b/agent/mcp_server.pyindex f7e52b262..f14f85a28 100644--- a/agent/mcp_server.py+++ b/agent/mcp_server.py@@ -1576,6 +1576,12 @@ def get_market_data(even-stride downsample (every step-th bar, last bar pinned)plus truncation metadata. Set max_rows=0 for all rows(unbounded, legacy behavior).++ Volume units: the ``volume`` column unit is source- and market-dependent+ (A-share sources report board lots of 100 shares; HK/US sources report+ single shares). Each symbol's ``_provenance.volume_unit`` states the unit+ of the returned rows ("lots" / "shares"; null = source undeclared) — read+ it before interpreting or comparing volume values across symbols/sources."""return fetch_market_data_json(codes=codes,diff --git a/agent/src/market_data.py b/agent/src/market_data.pyindex d27917e40..3aaf9d6e9 100644--- a/agent/src/market_data.py+++ b/agent/src/market_data.py@@ -114,6 +114,13 @@ def fetch_market_data(the market's :data:`backtest.loaders.registry.FALLBACK_CHAINS` (e.g. cryptoOKX → Binance → CCXT → Yahoo). At most ``max_fallback_attempts`` retriesare attempted before the symbol is recorded as ``_unresolved``.++ With ``include_provenance=True`` each symbol carries ``_provenance``+ metadata including ``volume_unit`` — the unit of the ``volume`` column as+ declared by the serving loader for that market (``"lots"`` = board lots of+ 100 shares, ``"shares"`` = single shares, ``None`` = undeclared). Volume+ units are source- and market-dependent (HKUDS/Vibe-Trading#1062), so+ consumers must read this field instead of assuming a unit."""from backtest.engines._market_hooks import _detect_marketfrom backtest.loaders.base import NoAvailableSourceError@@ -167,6 +174,7 @@ def fetch_market_data(data_map: dict[str, Any] = {}used_source: str | None = None+ provider_cls: type | None = Nonefor attempt_src in attempts:try:loader_cls = loader_resolver(attempt_src)@@ -180,6 +188,7 @@ def fetch_market_data(loader = loader_cls()data_map = loader.fetch(src_codes, start_date, end_date, interval=interval)used_source = attempt_src+ provider_cls = loader_clsif data_map:breakexcept Exception as exc: # noqa: BLE001 — contained per-symbol fallback@@ -202,12 +211,14 @@ def fetch_market_data(row[key] = _json_safe(value)results[symbol] = cap_rows(records, max_rows)if include_provenance:+ volume_units = getattr(provider_cls, "volume_units", None) or {}provenance[symbol] = {"source": used_source or src,"requested_source": source,"detected_source": src,"fallback_used": bool(used_source and used_source != src),"currency_conversion": "none",+ "volume_unit": volume_units.get(market),}unresolved = [diff --git a/agent/src/tools/market_data_tool.py b/agent/src/tools/market_data_tool.pyindex c088ebd1d..3fc5ded9b 100644--- a/agent/src/tools/market_data_tool.py+++ b/agent/src/tools/market_data_tool.py@@ -15,7 +15,10 @@ class MarketDataTool(BaseTool):description = ("Fetch normalized OHLCV market data through the repository loader layer. ""Use this for stock, ETF, index, or crypto price bars before writing raw "- "yfinance/OKX/Tushare scripts."+ "yfinance/OKX/Tushare scripts. Volume units are source- and market-dependent "+ "(A-share sources report board lots of 100 shares, HK/US sources report single "+ "shares); read the per-symbol _provenance.volume_unit field ('lots' / 'shares' / "+ "null=undeclared) before interpreting or comparing volume values.")parameters = {"type": "object",diff --git a/agent/tests/test_loader_volume_units.py b/agent/tests/test_loader_volume_units.pynew file mode 100644index 000000000..1acf8485f--- /dev/null+++ b/agent/tests/test_loader_volume_units.py@@ -0,0 +1,54 @@+"""Pin the volume-unit declarations of equity loaders (HKUDS/Vibe-Trading#1062).++A-share sources natively report board lots (1 lot = 100 shares) while+baostock reports single shares; the tencent/eastmoney loaders are+market-dependent (A-share lots vs HK shares). These pins lock the audit+matrix from issue #1062 so a declaration cannot drift silently — the+cross-source 100x discrepancy that motivated the fix was exactly such a+silent drift.+"""++from __future__ import annotations++import pytest++from backtest.loaders.akshare_loader import DataLoader as AkshareLoader+from backtest.loaders.baostock_loader import DataLoader as BaostockLoader+from backtest.loaders.eastmoney_loader import DataLoader as EastmoneyLoader+from backtest.loaders.local_loader import DataLoader as LocalLoader+from backtest.loaders.mootdx_loader import DataLoader as MootdxLoader+from backtest.loaders.stooq_loader import DataLoader as StooqLoader+from backtest.loaders.tencent_loader import DataLoader as TencentLoader+from backtest.loaders.tushare import DataLoader as TushareLoader+from backtest.loaders.yahoo_loader import DataLoader as YahooLoader+from backtest.loaders.yfinance_loader import DataLoader as YfinanceLoader+++ ("loader_cls", "market", "expected"),+ [+ (TencentLoader, "a_share", "lots"),+ (TencentLoader, "hk_equity", "shares"),+ (EastmoneyLoader, "a_share", "lots"),+ (EastmoneyLoader, "hk_equity", "shares"),+ (BaostockLoader, "a_share", "shares"),+ (MootdxLoader, "a_share", "lots"),+ (AkshareLoader, "a_share", "lots"),+ (TushareLoader, "a_share", "lots"),+ (YahooLoader, "us_equity", "shares"),+ (YahooLoader, "hk_equity", "shares"),+ (YfinanceLoader, "us_equity", "shares"),+ (YfinanceLoader, "hk_equity", "shares"),+ (StooqLoader, "us_equity", "shares"),+ ],+)+def test_loader_volume_unit_declaration(loader_cls, market, expected):+ assert getattr(loader_cls, "volume_units", {})[market] == expected+++def test_undeclared_markets_surface_as_missing_not_wrong():+ """Markets without evidence stay undeclared (null), never guessed."""+ assert "crypto" not in YfinanceLoader.volume_units+ assert "us_equity" not in EastmoneyLoader.volume_units+ assert "hk_equity" not in TushareLoader.volume_units+ assert getattr(LocalLoader, "volume_units", {}) == {}diff --git a/agent/tests/test_market_data_tool.py b/agent/tests/test_market_data_tool.pyindex afe0ad032..22644b4ca 100644--- a/agent/tests/test_market_data_tool.py+++ b/agent/tests/test_market_data_tool.py@@ -93,9 +93,94 @@ def test_market_data_json_can_include_actual_source_provenance():"detected_source": "yahoo","fallback_used": True,"currency_conversion": "none",+ "volume_unit": None,}+def test_market_data_provenance_exposes_declared_volume_unit():+ """Serving loaders declare per-market volume units (#1062)."""+ idx = pd.date_range("2026-01-01", periods=1, freq="D")+ idx.name = "trade_date"+ df = pd.DataFrame(+ {+ "open": [1.0],+ "high": [1.1],+ "low": [0.9],+ "close": [1.05],+ "volume": [100],+ },+ index=idx,+ )++ class _UnitAwareLoader:+ volume_units = {"a_share": "lots", "hk_equity": "shares"}++ def fetch(self, codes, start, end, interval="1D"):+ return {code: df for code in codes}++ payload = json.loads(+ fetch_market_data_json(+ codes=["600519.SH", "0700.HK"],+ start_date="2026-01-01",+ end_date="2026-01-02",+ source="tencent",+ loader_resolver=lambda source: _UnitAwareLoader,+ include_provenance=True,+ )+ )++ assert payload["_provenance"]["600519.SH"]["volume_unit"] == "lots"+ assert payload["_provenance"]["0700.HK"]["volume_unit"] == "shares"+++def test_market_data_provenance_volume_unit_follows_serving_loader():+ """After fallback, the unit comes from the loader that actually served."""+ idx = pd.date_range("2026-01-01", periods=1, freq="D")+ idx.name = "trade_date"+ df = pd.DataFrame(+ {+ "open": [1.0],+ "high": [1.1],+ "low": [0.9],+ "close": [1.05],+ "volume": [100],+ },+ index=idx,+ )++ class _PrimaryLoader:+ volume_units = {"a_share": "lots"}++ def fetch(self, codes, start, end, interval="1D"):+ raise RuntimeError("primary unavailable")++ class _FallbackLoader:+ volume_units = {"a_share": "shares"}++ def fetch(self, codes, start, end, interval="1D"):+ return {codes[0]: df}++ def _resolver(source: str):+ return _PrimaryLoader if source == "tencent" else _FallbackLoader++ payload = json.loads(+ fetch_market_data_json(+ codes=["600519.SH"],+ start_date="2026-01-01",+ end_date="2026-01-02",+ source="tencent",+ loader_resolver=_resolver,+ fallback_chain_provider=lambda source: ["tencent", "baostock"],+ include_provenance=True,+ )+ )++ prov = payload["_provenance"]["600519.SH"]+ assert prov["source"] == "baostock"+ assert prov["fallback_used"] is True+ assert prov["volume_unit"] == "shares"++def test_market_data_json_is_strict_when_loader_returns_nan():idx = pd.date_range("2026-01-01", periods=1, freq="D")