"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(market-data): stamp the price-adjustment caliber on served frames (#1301)
Yufeng Hea1dd2876c800
diff --git a/agent/backtest/engines/base.py b/agent/backtest/engines/base.pyindex 9ac954c39..d5102be51 100644--- a/agent/backtest/engines/base.py+++ b/agent/backtest/engines/base.py@@ -1079,6 +1079,9 @@ class BaseEngine(ABC):)# 9. Trust Layer run card+ card_warnings = list(config.get("content_filter_warnings") or [])+ if config.get("_run_card_caliber_warning"):+ card_warnings.append(config["_run_card_caliber_warning"])from backtest.run_card import write_run_cardwrite_run_card(run_dir,@@ -1086,7 +1089,7 @@ class BaseEngine(ABC):m,data_sources=_run_card_data_sources(config, loader),strategy_path=run_dir / "code" / "signal_engine.py",- warnings=config.get("content_filter_warnings") or None,+ warnings=card_warnings or None,)# Print scalar metrics (skip nested dicts for JSON compat).diff --git a/agent/backtest/loaders/registry.py b/agent/backtest/loaders/registry.pyindex 7e2298f51..6f315a852 100644--- a/agent/backtest/loaders/registry.py+++ b/agent/backtest/loaders/registry.py@@ -167,6 +167,90 @@ FALLBACK_CHAINS: dict[str, list[str]] = {}+# ---------------------------------------------------------------------------+# Price caliber: what the served prices actually mean, per source (#1301)+# ---------------------------------------------------------------------------++#: A value lands here only when it is measured against live payloads (the+#: #1301 chain table) or pinned by the loader's own endpoint/parameter+#: choice. Anything unverified resolves to "unknown" on purpose: origin-side+#: adjustment is invisible from loader code (yahoo serves split-adjusted+#: quotes with zero adjustment logic in this repo), so an unmeasured source+#: must say "unknown" rather than a guessed caliber.+PRICE_CALIBER_BY_SOURCE: dict[str, str] = {+ # Split- and dividend-adjusted.+ "yahoo": "split_dividend", # quote series split-adjusted at origin, scaled to adjclose+ "yfinance": "split_dividend", # auto_adjust=True+ "eastmoney": "split_dividend", # fqt=1 (forward-adjusted) on every kline call+ "tencent": "split_dividend", # fqkline qfq+ "akshare": "split_dividend", # adjust="qfq", including the stock_us_hist path+ "baostock": "split_dividend", # adjustflag="2"+ "tushare": "split_dividend", # adj_factor applied via cn_adjust (A-share/fund)+ # Split-adjusted only.+ "pykrx": "split", # get_market_ohlcv_by_date(adjusted=True), Naver-backed+ # Unadjusted.+ "sina": "raw",+ "tiingo": "raw", # fetches adjusted columns and deliberately drops them+ "fmp": "raw", # historical-price-full only, never the adjusted variant+ "alphavantage": "raw", # TIME_SERIES_DAILY, not the _ADJUSTED endpoint+ "longbridge": "raw", # pins AdjustType.NoAdjust+}++#: Per-(source, market) exceptions to the per-source table.+PRICE_CALIBER_BY_SOURCE_MARKET: dict[tuple[str, str], str] = {+ # Tushare publishes no HK adjustment-factor series, so its HK path is raw.+ ("tushare", "hk_equity"): "raw",+}++#: Markets with no corporate-action adjustment concept. Their sources stamp+#: "na" and stay out of mixed-caliber comparisons.+_NA_CALIBER_MARKETS = frozenset({"crypto", "forex", "futures", "macro"})++#: Calibers that participate in mixed-caliber comparison. "unknown" and "na"+#: never do: the first is unmeasured, the second has nothing to adjust for.+_COMPARABLE_CALIBERS = frozenset({"raw", "split", "split_dividend"})+++def price_caliber(source: str, market: str | None = None) -> str:+ """Return the adjustment caliber of ``source``'s served prices.++ One of "raw", "split", "split_dividend", "na" (a market without+ corporate actions), or "unknown" (an unmeasured source).+ """+ if market in _NA_CALIBER_MARKETS:+ return "na"+ return PRICE_CALIBER_BY_SOURCE_MARKET.get(+ (source, market), PRICE_CALIBER_BY_SOURCE.get(source, "unknown")+ )+++def mixed_caliber_warning(stamps: dict[str, tuple[str, str]]) -> str | None:+ """Build the mixed-caliber warning for a served basket, or None.++ ``stamps`` maps each served symbol to the (source, caliber) pair that+ served it. Fires only when at least two distinct comparable calibers are+ present; "unknown" and "na" entries never trigger it.+ """+ by_caliber: dict[str, list[str]] = {}+ for symbol, (_source, caliber) in stamps.items():+ if caliber in _COMPARABLE_CALIBERS:+ by_caliber.setdefault(caliber, []).append(symbol)+ if len(by_caliber) < 2:+ return None+ parts = []+ for caliber, symbols in sorted(by_caliber.items()):+ shown = ", ".join(sorted(symbols)[:4])+ if len(symbols) > 4:+ shown += f", +{len(symbols) - 4} more"+ parts.append(f"{caliber} ({shown})")+ return (+ "mixed price calibers in this run: " + "; ".join(parts) + ". "+ "Prices are not on the same scale across calibers, so cross-symbol "+ "comparisons (momentum ranks, relative performance) are biased. "+ "See the adjustment field of each symbol's provenance entry."+ )++# ---------------------------------------------------------------------------# Source-order overrides: per-market env-configurable chain priority# ---------------------------------------------------------------------------diff --git a/agent/backtest/runner.py b/agent/backtest/runner.pyindex 646bfa59a..3c6af622f 100644--- a/agent/backtest/runner.py+++ b/agent/backtest/runner.py@@ -26,6 +26,8 @@ from backtest.loaders.registry import (LOADER_REGISTRY,VALID_SOURCES,get_loader_cls_with_fallback,+ mixed_caliber_warning,+ price_caliber,resolve_loader,)from backtest.loaders.base import NoAvailableSourceError, validate_ohlc@@ -58,6 +60,9 @@ class DataFetchResult:source: strloader: Anyeffective_sources: List[str]+ # Mixed-caliber warning for the served basket (#1301), None when every+ # served symbol shares one comparable caliber (or none is measurable).+ caliber_warning: str | None = Noneclass BacktestConfigSchema(BaseModel):@@ -1261,6 +1266,8 @@ def main(run_dir: Path) -> None:loader = fetch_result.loaderconfig["codes"] = codesconfig["_run_card_effective_sources"] = fetch_result.effective_sources+ if fetch_result.caliber_warning:+ config["_run_card_caliber_warning"] = fetch_result.caliber_warninginterval = config.get("interval", "1D")if not data_map:print(json.dumps({"error": "No data fetched"}))@@ -1424,6 +1431,7 @@ def _fetch_auto(codes: List[str], config: dict, interval: str = "1D") -> dict:market_groups = _group_codes_by_market(codes)merged = {}served_by: set[str] = set()+ caliber_stamps: dict[str, tuple[str, str]] = {}start_date = config.get("start_date", "")end_date = config.get("end_date", "")@@ -1452,6 +1460,8 @@ def _fetch_auto(codes: List[str], config: dict, interval: str = "1D") -> dict:)if market_result:served_by.add(src_name)+ for code in market_result:+ caliber_stamps[code] = (src_name, price_caliber(src_name, market))missing = [code for code in market_codes if code not in market_result]# Retry only missing symbols so a partial primary response does not@@ -1472,7 +1482,10 @@ def _fetch_auto(codes: List[str], config: dict, interval: str = "1D") -> dict:if mapped:market_result.update(mapped)missing = [code for code in missing if code not in mapped]- served_by.add(str(getattr(fb_loader, "name", fb_name) or fb_name))+ fb_served_by = str(getattr(fb_loader, "name", fb_name) or fb_name)+ served_by.add(fb_served_by)+ for code in mapped:+ caliber_stamps[code] = (fb_served_by, price_caliber(fb_served_by, market))logger.info("Runtime fallback: %s -> %s for %s", src_name, fb_name, market)@@ -1484,6 +1497,7 @@ def _fetch_auto(codes: List[str], config: dict, interval: str = "1D") -> dict:merged.update(market_result)config["_actual_sources"] = sorted(served_by)+ config["_caliber_stamps"] = caliber_stampsreturn merged@@ -1504,12 +1518,14 @@ def fetch_data_map(config: dict) -> DataFetchResult:codes = list(config.get("codes") or [])interval = str(config.get("interval") or "1D")+ caliber_stamps: dict[str, tuple[str, str]] = {}if source == "auto":data_map = _fetch_auto(codes, config, interval)loader: Any = _AutoLoader(data_map)# Prefer the loaders that actually served rows; the symbol-pattern guess# is only a fallback for a stubbed/patched fetcher that recorded nothing.recorded = config.pop("_actual_sources", None)+ caliber_stamps = config.pop("_caliber_stamps", None) or {}used_sources: list[str] = [str(name) for name in recorded or [] if str(name).strip()] or sorted(_group_codes_by_source(codes))@@ -1536,6 +1552,11 @@ def fetch_data_map(config: dict) -> DataFetchResult:fields=config.get("extra_fields") or None,interval=interval,)+ for code in data_map:+ caliber_stamps[code] = (+ served_by,+ price_caliber(served_by, _detect_market(code)),+ )used_sources = [served_by] if data_map else []missing = [code for code in codes if code not in data_map]if missing:@@ -1576,6 +1597,11 @@ def fetch_data_map(config: dict) -> DataFetchResult:getattr(fallback_loader, "name", fallback_source)or fallback_source)+ for code in mapped:+ caliber_stamps[code] = (+ fb_served_by,+ price_caliber(fb_served_by, _detect_market(code)),+ )if not used_sources:source = fb_served_byloader = fallback_loader@@ -1590,12 +1616,19 @@ def fetch_data_map(config: dict) -> DataFetchResult:)data_map = _sanitize_data_map(data_map)+ caliber_stamps = {+ code: stamp for code, stamp in caliber_stamps.items() if code in data_map+ }+ caliber_warning = mixed_caliber_warning(caliber_stamps)+ if caliber_warning:+ logger.warning("%s", caliber_warning)return DataFetchResult(data_map=data_map,codes=codes,source=source,loader=loader,effective_sources=used_sources,+ caliber_warning=caliber_warning,)diff --git a/agent/mcp_server.py b/agent/mcp_server.pyindex 04ddb3fdf..9f82c3906 100644--- a/agent/mcp_server.py+++ b/agent/mcp_server.py@@ -1795,6 +1795,12 @@ def get_market_data(single shares). Each symbol's ``_provenance.volume_unit`` states the unitof the returned rows ("lots" / "shares"; null = source undeclared) — readit before interpreting or comparing volume values across symbols/sources.++ Price caliber: which source served a symbol decides what its prices mean+ (some adjust for splits and dividends, others serve raw quotes). Each+ symbol's ``_provenance.adjustment`` states the caliber ("raw" / "split" /+ "split_dividend" / "na" / "unknown") — read it before comparing price+ levels across symbols."""registry = _get_registry()return registry.execute(diff --git a/agent/src/market_data.py b/agent/src/market_data.pyindex 78a19ea80..9b6312a4b 100644--- a/agent/src/market_data.py+++ b/agent/src/market_data.py@@ -158,6 +158,7 @@ def fetch_market_data(FALLBACK_CHAINS,_NO_NETWORK_FALLBACK_SOURCES,get_source_order_override,+ price_caliber,refresh_source_order_overrides,)@@ -321,6 +322,7 @@ def fetch_market_data("fallback_used": bool(used_source and used_source != src),"currency_conversion": currency_conversion,"volume_unit": volume_units.get(market),+ "adjustment": price_caliber(used_source or src, market),}quote_currency = frame_attrs.get("quote_currency")if isinstance(quote_currency, str) and quote_currency:@@ -381,6 +383,7 @@ def fetch_market_data("fallback_used": True,"currency_conversion": "none","volume_unit": base.get("volume_unit"),+ "adjustment": base.get("adjustment", price_caliber(src, market)),"venue_fallback": True,"resolved_symbol": sibling,}diff --git a/agent/src/tools/market_data_tool.py b/agent/src/tools/market_data_tool.pyindex 6c8bf769d..d5f4ff26d 100644--- a/agent/src/tools/market_data_tool.py+++ b/agent/src/tools/market_data_tool.py@@ -57,7 +57,10 @@ class MarketDataTool(BaseTool):"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."+ "null=undeclared) before interpreting or comparing volume values. Price caliber "+ "is source-dependent too (some sources adjust for splits/dividends, others serve "+ "raw quotes); read _provenance.adjustment ('raw' / 'split' / 'split_dividend' / "+ "'na' / 'unknown') before comparing price levels across symbols.")parameters = {"type": "object",diff --git a/agent/tests/test_market_data_tool.py b/agent/tests/test_market_data_tool.pyindex 26a6e87a8..d5ed44933 100644--- a/agent/tests/test_market_data_tool.py+++ b/agent/tests/test_market_data_tool.py@@ -94,6 +94,7 @@ def test_market_data_json_can_include_actual_source_provenance():"fallback_used": True,"currency_conversion": "none","volume_unit": None,+ "adjustment": "split_dividend",}diff --git a/agent/tests/test_price_caliber.py b/agent/tests/test_price_caliber.pynew file mode 100644index 000000000..5c514ddd1--- /dev/null+++ b/agent/tests/test_price_caliber.py@@ -0,0 +1,233 @@+"""Tests for the #1301 price-caliber provenance.++Every served frame now declares what its prices mean (``adjustment`` in+``_provenance``), and a backtest whose basket mixes calibers logs a warning+instead of silently comparing raw against adjusted series.+"""++from __future__ import annotations++import pandas as pd+import pytest++from backtest import runner+from backtest.loaders.registry import (+ FALLBACK_CHAINS,+ mixed_caliber_warning,+ price_caliber,+)+from src.market_data import fetch_market_data+++def _df() -> pd.DataFrame:+ index = pd.DatetimeIndex(pd.to_datetime(["2024-01-02"]))+ return pd.DataFrame(+ {"open": [1.0], "high": [1.0], "low": [1.0], "close": [1.0], "volume": [1.0]},+ index=index,+ )+++# --------------------------------------------------------------------------+# price_caliber table+# --------------------------------------------------------------------------+++ "source,expected",+ [+ ("yahoo", "split_dividend"),+ ("yfinance", "split_dividend"),+ ("eastmoney", "split_dividend"),+ ("tencent", "split_dividend"),+ ("akshare", "split_dividend"),+ ("baostock", "split_dividend"),+ ("tushare", "split_dividend"),+ ("pykrx", "split"),+ ("sina", "raw"),+ ("tiingo", "raw"),+ ("fmp", "raw"),+ ("alphavantage", "raw"),+ ("longbridge", "raw"),+ # Neither measured nor pinned by an endpoint choice: must not guess.+ ("stooq", "unknown"),+ ("finnhub", "unknown"),+ ("local", "unknown"),+ ],+)+def test_source_calibers(source: str, expected: str) -> None:+ assert price_caliber(source, "us_equity") == expected+++def test_tushare_hk_override_is_raw() -> None:+ """Tushare publishes no HK adjustment-factor series, so only its+ A-share/fund paths are adjusted."""+ assert price_caliber("tushare", "hk_equity") == "raw"+ assert price_caliber("tushare", "a_share") == "split_dividend"+++def test_non_equity_markets_stamp_na() -> None:+ assert price_caliber("binance", "crypto") == "na"+ # The market wins over the per-source table: yfinance serving BTC has+ # nothing to adjust for.+ assert price_caliber("yfinance", "crypto") == "na"+ assert price_caliber("mt5", "forex") == "na"+++def test_every_chain_source_resolves() -> None:+ for market, chain in FALLBACK_CHAINS.items():+ for source in chain:+ assert price_caliber(source, market) in {+ "raw",+ "split",+ "split_dividend",+ "na",+ "unknown",+ }+++# --------------------------------------------------------------------------+# mixed_caliber_warning+# --------------------------------------------------------------------------+++def test_warning_fires_on_mixed_basket() -> None:+ msg = mixed_caliber_warning(+ {+ "AAPL.US": ("yahoo", "split_dividend"),+ "TSLA.US": ("sina", "raw"),+ }+ )+ assert msg is not None+ assert "AAPL.US" in msg and "TSLA.US" in msg+ assert "split_dividend" in msg and "raw" in msg+++def test_warning_silent_on_single_caliber() -> None:+ assert (+ mixed_caliber_warning(+ {+ "AAPL.US": ("yahoo", "split_dividend"),+ "MSFT.US": ("yfinance", "split_dividend"),+ }+ )+ is None+ )+++def test_warning_ignores_unknown_and_na() -> None:+ assert (+ mixed_caliber_warning(+ {+ "AAPL.US": ("yahoo", "split_dividend"),+ "XYZ.US": ("finnhub", "unknown"),+ "BTC-USDT": ("binance", "na"),+ }+ )+ is None+ )+++# --------------------------------------------------------------------------+# _provenance stamp in fetch_market_data+# --------------------------------------------------------------------------+++class _StubLoader:+ def fetch(self, codes, start, end, *, interval="1D"): # noqa: ANN001, ANN201+ return {code: _df() for code in codes}+++def test_provenance_stamps_adjustment_for_adjusted_source() -> None:+ out = fetch_market_data(+ codes=["600519.SH"],+ start_date="2024-01-01",+ end_date="2024-01-03",+ source="tencent",+ loader_resolver=lambda src: _StubLoader,+ include_provenance=True,+ )+ assert out["_provenance"]["600519.SH"]["adjustment"] == "split_dividend"+++def test_provenance_stamps_adjustment_for_raw_source() -> None:+ out = fetch_market_data(+ codes=["AAPL.US"],+ start_date="2024-01-01",+ end_date="2024-01-03",+ source="sina",+ loader_resolver=lambda src: _StubLoader,+ include_provenance=True,+ )+ assert out["_provenance"]["AAPL.US"]["adjustment"] == "raw"+++# --------------------------------------------------------------------------+# fetch_data_map: run-level mixed-caliber warning+# --------------------------------------------------------------------------+++class _YahooStub:+ name = "yahoo"++ def fetch(self, codes, start, end, fields=None, interval="1D"): # noqa: ANN001, ANN201+ return {"AAPL.US": _df()}+++class _SinaStub:+ name = "sina"++ def is_available(self) -> bool:+ return True++ def fetch(self, codes, start, end, interval="1D"): # noqa: ANN001, ANN201+ return {"TSLA.US": _df()}+++def test_fetch_data_map_warns_on_mixed_caliber_basket(+ monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture+) -> None:+ """yahoo serves AAPL (split_dividend), sina serves TSLA down the chain+ (raw): the run must say the basket mixes calibers."""+ monkeypatch.setattr(runner, "resolve_loader", lambda market: _YahooStub())+ monkeypatch.setattr(runner, "LOADER_REGISTRY", {"sina": _SinaStub})++ result = runner.fetch_data_map(+ {+ "source": "auto",+ "codes": ["AAPL.US", "TSLA.US"],+ "start_date": "2024-01-01",+ "end_date": "2024-01-03",+ "interval": "1D",+ }+ )++ assert result.caliber_warning is not None+ assert "AAPL.US" in result.caliber_warning+ assert "TSLA.US" in result.caliber_warning+ assert "mixed price calibers" in caplog.text+++def test_fetch_data_map_silent_on_single_caliber(+ monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture+) -> None:+ class _YahooBoth:+ name = "yahoo"++ def fetch(self, codes, start, end, fields=None, interval="1D"): # noqa: ANN001, ANN201+ return {code: _df() for code in codes}++ monkeypatch.setattr(runner, "resolve_loader", lambda market: _YahooBoth())+ monkeypatch.setattr(runner, "LOADER_REGISTRY", {})++ result = runner.fetch_data_map(+ {+ "source": "auto",+ "codes": ["AAPL.US", "MSFT.US"],+ "start_date": "2024-01-01",+ "end_date": "2024-01-03",+ "interval": "1D",+ }+ )++ assert result.caliber_warning is None+ assert "mixed price calibers" not in caplog.text