Skip to content

"Vibe-Trading: Your Personal Trading Agent"

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.py
index 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_card
write_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.py
index 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.py
index 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: str
loader: Any
effective_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 = None
class BacktestConfigSchema(BaseModel):
@@ -1261,6 +1266,8 @@ def main(run_dir: Path) -> None:
loader = fetch_result.loader
config["codes"] = codes
config["_run_card_effective_sources"] = fetch_result.effective_sources
+ if fetch_result.caliber_warning:
+ config["_run_card_caliber_warning"] = fetch_result.caliber_warning
interval = 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_stamps
return 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_by
loader = 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.py
index 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 unit
of the returned rows ("lots" / "shares"; null = source undeclared) — read
it 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.py
index 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.py
index 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.py
index 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.py
new file mode 100644
index 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