"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Local market data tool backed by the shared loader layer."""
from __future__ import annotations
import json
import re
from datetime import date
from typing import Any
from src.agent.tools import BaseTool
from src.market_data import DEFAULT_MAX_ROWS, fetch_market_data_json
from backtest.engines._market_hooks import _detect_market
from backtest.loaders.registry import VALID_SOURCES
from backtest.runner import _VALID_INTERVALS
# Canonical-case lookup. ``_VALID_INTERVALS`` mixes cases ("1m" minutes vs
# "1M" months, "1H" hours), so a plain ``.upper()`` fold is unsafe: it maps
# "1m" and "1M" onto one key, and before monthly bars existed it answered a
# monthly question with minute bars (#1480). A case-exact match wins first in
# ``_canonicalize_interval``; this fold only serves the unambiguous variants
# ("1d" -> "1D", "30M" -> "30m", "1w" -> "1W"), and a minute token whose upper
# case is itself an interval ("1m" -> "1M") is left out of it.
_INTERVAL_CANON = {
v.upper(): v for v in _VALID_INTERVALS if v.upper() == v or v.upper() not in _VALID_INTERVALS
}
# The yfinance spellings the technical-indicator tool has always documented.
_INTERVAL_CANON.update({"1WK": "1W", "1MO": "1M"})
def _canonicalize_interval(raw: str) -> str | None:
"""Resolve a user interval spelling to the canonical loader form.
A case-exact match against ``_VALID_INTERVALS`` wins first, so the minute
interval ``"1m"`` and the monthly ``"1M"`` are never conflated by the case
fold (#1480). Falls back to ``_INTERVAL_CANON`` for unambiguous case
variants (``"1d"`` -> ``"1D"``, ``"30M"`` -> ``"30m"``, ``"1wk"`` -> ``"1W"``).
Args:
raw: Interval string as supplied by the caller.
Returns:
The canonical interval token, or ``None`` when not served.
"""
token = raw.strip()
if token in _VALID_INTERVALS:
return token
return _INTERVAL_CANON.get(token.upper())
# Source allow-list derived from the shared loader registry (the same set the
# backtest tool validates against), so the MCP/agent-facing surface can never
# silently drop a loader the registry serves. Sorted for a stable schema.
_SOURCE_ENUM = sorted(VALID_SOURCES)
_ISO_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
def _error(message: str) -> str:
return json.dumps({"ok": False, "error": message}, ensure_ascii=False)
def _valid_iso_date(value: str) -> bool:
"""True only for strict ``YYYY-MM-DD`` calendar dates.
``date.fromisoformat`` alone is not enough: on Python 3.11+ it also
accepts the compact ``YYYYMMDD`` form, which loaders downstream reject
or mis-parse. Enforce the exact shape first, then the calendar.
"""
if not _ISO_DATE_RE.match(value):
return False
try:
date.fromisoformat(value)
except ValueError:
return False
return True
class MarketDataTool(BaseTool):
"""Fetch normalized OHLCV data through repository loaders."""
name = "get_market_data"
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. 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. Price caliber "
"is source-dependent too (some sources adjust for splits/dividends, others serve "
"raw quotes); read _provenance.adjustment ('raw' / 'split' / 'split_dividend' / "
"'split_dividend_additive' / 'na' / 'unknown') before comparing price levels "
"across symbols. 'split_dividend_additive' (the A-share qfq of Tencent, Eastmoney and AKShare) adjusts "
"dividends by shifting the price level rather than scaling it, so it is not on "
"the same scale as 'split_dividend'."
)
parameters = {
"type": "object",
"properties": {
"codes": {
"type": "array",
"items": {"type": "string"},
"description": (
'Symbols such as ["AAPL.US"], ["700.HK"], ["TD.TO"], '
'["PNG.V"], or ["BTC-USDT"].'
),
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format.",
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format.",
},
"source": {
"type": "string",
"enum": _SOURCE_ENUM,
"description": (
"Data source. 'auto' detects from symbol format with fallback. "
"Use 'gildata' only if the user asks for Gildata quotes; requires a token "
"and the market quotes opt-in, with no fallback in either direction. "
"Use 'longbridge' explicitly for US/HK OHLCV through the "
"Longbridge OpenAPI (requires Longbridge credentials). "
"Free, no key: yfinance/yahoo (US/HK/Canada equities; "
"Canada uses .TO/.V), okx/ccxt/binance "
"(crypto), baostock/tencent/eastmoney/sina/akshare "
"(China A-shares), futu (HK/A via local FutuOpenD), stooq "
"(global EOD), pykrx (Korea KRX daily "
"bars for <CODE>.KS / <CODE>.KQ; needs the optional pykrx "
"package, else Korea falls back to yahoo/yfinance). Key-gated "
"REST: tushare (China A-shares), finnhub/alphavantage/tiingo/fmp "
"(US/global). india_broker: "
"read-only Shoonya/Dhan bars for .NS/.BO. mt5: forex/metals "
"from a local MetaTrader 5 terminal (Windows; e.g. EUR/USD, "
"XAUUSD.FX); tickerall: the same feed hosted, no terminal, "
"any OS. local: your own CSV/Parquet/DuckDB files."
),
"default": "auto",
},
"interval": {
"type": "string",
"description": (
"Bar size: 1m/5m/15m/30m/1H/4H/1D, or 1W/1M for weekly/monthly "
"bars built from daily ones (1M is a month, 1m a minute)."
),
"default": "1D",
},
"max_rows": {
"type": "integer",
"description": "Per-symbol row cap. Use 0 only when the full series is required.",
"default": DEFAULT_MAX_ROWS,
},
},
"required": ["codes", "start_date", "end_date"],
}
repeatable = True
def execute(self, **kwargs: Any) -> str:
"""Validate inputs, then fetch and return strict JSON.
Args:
**kwargs: ``codes``, ``start_date``, ``end_date``, optional
``source``, ``interval``, ``max_rows``, and (internal,
MCP-only) ``loader_resolver`` — the resolver the MCP server
injects so its own loader-hook contract is preserved.
Returns:
Strict JSON envelope with per-symbol OHLCV panels plus
``_provenance``, or an error envelope on invalid inputs.
"""
codes = kwargs.get("codes")
if not isinstance(codes, list) or not codes:
return _error("codes must be a non-empty list of strings")
if any(not isinstance(code, str) or not code.strip() for code in codes):
return _error("every code must be a non-empty string")
codes = [code.strip() for code in codes]
start_date = kwargs.get("start_date")
end_date = kwargs.get("end_date")
if not isinstance(start_date, str) or not start_date.strip():
return _error("start_date must be a non-empty YYYY-MM-DD string")
if not isinstance(end_date, str) or not end_date.strip():
return _error("end_date must be a non-empty YYYY-MM-DD string")
start_date = start_date.strip()
end_date = end_date.strip()
if not _valid_iso_date(start_date) or not _valid_iso_date(end_date):
return _error("start_date and end_date must be valid YYYY-MM-DD dates")
if start_date > end_date:
return _error(
f"start_date ({start_date}) must not be after end_date ({end_date})"
)
source = kwargs.get("source", "auto")
if source not in _SOURCE_ENUM:
return _error(f"source must be one of {_SOURCE_ENUM}")
if source == "auto":
# Only what the market detector reads as a US equity: a Chinese
# futures code (RB0, IF2412) or a joined crypto pair (BTCUSDT) has
# the same shape and is served without any suffix.
bare_us = [
code for code in codes
if re.fullmatch(r"[A-Za-z][A-Za-z0-9.\-]*", code)
and "." not in code
and "-" not in code
and _detect_market(code) == "us_equity"
]
if bare_us:
return _error(
"US equity symbols must include the .US suffix, "
f"for example AAPL.US; received {bare_us}"
)
interval = kwargs.get("interval", "1D")
if not isinstance(interval, str):
return _error("interval must be a string like '1D', '1H', '4H', '30m'")
interval_token = interval.strip()
normalized_interval = _canonicalize_interval(interval_token)
if normalized_interval is None:
return _error(
f"interval must be one of {sorted(_VALID_INTERVALS)} (case-insensitive, "
f"except that 1m is one minute and 1M one month); got {interval!r}"
)
max_rows = kwargs.get("max_rows", DEFAULT_MAX_ROWS)
if not isinstance(max_rows, int) or isinstance(max_rows, bool):
return _error("max_rows must be a non-negative integer (0 = all rows)")
if max_rows < 0:
# P07 contract (test_get_market_data_size.py::G3ii): a negative
# cap is invalid but must never become unbounded — the loader
# layer clamps it to the default cap. Keep that observable
# behavior here so both surfaces agree.
max_rows = DEFAULT_MAX_ROWS
fetch_kwargs: dict[str, Any] = {
"codes": codes,
"start_date": start_date,
"end_date": end_date,
"source": source,
"interval": normalized_interval,
"max_rows": max_rows,
"include_provenance": True,
}
loader_resolver = kwargs.get("loader_resolver")
if loader_resolver is not None:
fetch_kwargs["loader_resolver"] = loader_resolver
return fetch_market_data_json(**fetch_kwargs)