nlalpha-data 0.3.0__py3-none-any.whl

nlalpha_data/__init__.py

@@ -0,0 +1,30 @@
+"""Financial data providers, explicit loading, storage, and trading calendars."""
+
+from nlalpha_data.base import DataProvider
+from nlalpha_data.store import BaseBarStore, BarOverview
+from nlalpha_data.calendar_base import TradingCalendar, WeekendOnlyCalendar
+from nlalpha_data.calendar import CNEquityCalendar, USEquityCalendar, FuturesCalendar
+from nlalpha_data.loader import DataLoader, DataProviderRecord, LoadedBars
+from nlalpha_data.local_provider import LocalFileDataProvider
+from nlalpha_data.parquet_store import ParquetBarStore
+from nlalpha_data.sqlite_store import SQLiteBarStore
+from nlalpha_data.discovery import discover_data_providers, get_default_data_provider
+
+__all__ = [
+    "DataProvider",
+    "BaseBarStore",
+    "BarOverview",
+    "TradingCalendar",
+    "WeekendOnlyCalendar",
+    "CNEquityCalendar",
+    "USEquityCalendar",
+    "FuturesCalendar",
+    "DataLoader",
+    "DataProviderRecord",
+    "LoadedBars",
+    "LocalFileDataProvider",
+    "ParquetBarStore",
+    "SQLiteBarStore",
+    "discover_data_providers",
+    "get_default_data_provider",
+]

nlalpha_data/bars_aligner.py

@@ -0,0 +1,82 @@
+"""多品种 Bar 数据时间对齐工具。
+
+参考 vnpy_portfoliostrategy 的数据切片机制：
+- 所有品种按统一时间轴对齐
+- 缺失品种用前一根 Bar 前向填充（ffill）
+- 输出：[(datetime, {symbol: Bar})] 按时间升序排列
+
+设计约束：
+- 不修改原始 Bar 数据
+- 前向填充只在当前品种缺失当前时间点的数据时使用
+- 如果某个品种在整个回测期间都没有数据，它不会出现在任何切片中
+
+用法：
+    from nlalpha_data.bars_aligner import align_bars
+
+    data = {
+        "000300.SH": [Bar(datetime=dt1, ...), Bar(datetime=dt2, ...)],
+        "000905.SH": [Bar(datetime=dt2, ...), Bar(datetime=dt3, ...)],
+    }
+    slices = align_bars(data)
+    # slices = [(dt1, {"000300.SH": bar1}), (dt2, {"000300.SH": bar2, "000905.SH": bar3}), ...]
+"""
+
+from datetime import datetime
+
+from nlalpha.core.contracts.market import Bar
+
+
+def align_bars(bars_dict: dict[str, list[Bar]]) -> list[tuple[datetime, dict[str, Bar]]]:
+    """将多品种的 Bar 列表按时间对齐。
+
+    算法：
+    1. 收集所有品种的所有时间点，去重排序
+    2. 为每个品种建立 datetime -> Bar 的映射
+    3. 逐时间点切片：对每个时间点，取各品种在该时间或之前的最近一根 Bar（前向填充）
+    4. 返回按时间升序排列的切片列表
+
+    Args:
+        bars_dict: {symbol: [Bar, ...]}，每个品种的 Bar 列表已按时间升序排列
+
+    Returns:
+        [(datetime, {symbol: Bar})] 按时间升序排列
+    """
+    if not bars_dict:
+        return []
+
+    # 1. 收集所有时间点
+    all_times: set[datetime] = set()
+    for symbol, bars in bars_dict.items():
+        for bar in bars:
+            all_times.add(bar.datetime)
+
+    if not all_times:
+        return []
+
+    # 2. 排序时间点
+    sorted_times = sorted(all_times)
+
+    # 3. 为每个品种建立 datetime -> Bar 映射（快速查找）
+    # 同时保留排序后的 Bar 列表用于前向填充
+    bar_by_time: dict[str, dict[datetime, Bar]] = {}
+    for symbol, bars in bars_dict.items():
+        bar_by_time[symbol] = {bar.datetime: bar for bar in bars}
+
+    # 4. 逐时间切片，前向填充
+    result: list[tuple[datetime, dict[str, Bar]]] = []
+    last_bar: dict[str, Bar] = {}  # 前向填充缓存
+
+    for dt in sorted_times:
+        slice_bars: dict[str, Bar] = {}
+        for symbol in bars_dict.keys():
+            # 如果当前时间点有该品种的 Bar，更新缓存
+            if dt in bar_by_time.get(symbol, {}):
+                last_bar[symbol] = bar_by_time[symbol][dt]
+            # 如果缓存中有该品种的数据，放入当前切片
+            if symbol in last_bar:
+                slice_bars[symbol] = last_bar[symbol]
+
+        if slice_bars:
+            result.append((dt, slice_bars))
+
+    return result

nlalpha_data/base.py

@@ -0,0 +1,90 @@
+"""DataProvider 抽象接口。
+
+所有数据源（Tushare、CSV、Parquet、akshare、rqdata 等）
+都必须实现此接口，这样 family 子系统和回测运行时
+不需要关心数据来自哪里。
+"""
+
+from datetime import timedelta
+from decimal import Decimal
+import re
+
+from typing import Protocol
+from nlalpha.core.contracts.market import Bar
+from nlalpha.core.contracts.market_source import validate_request_description
+
+
+class DataProvider(Protocol):
+    """历史数据提供者接口。"""
+
+    async def load_bars(self, symbol: str, interval: str, start: str, end: str, *,
+                        price_adjustment: str | None = None) -> list[Bar]:
+        """Load bars for one symbol, interval, and inclusive date range.
+
+        price_adjustment selects "unadjusted", "forward", or "backward"; None leaves the source default.
+        Raises DataError when the source fails or the range has no data.
+        """
+        ...
+
+    async def describe_request(self, symbol: str, interval: str,
+                               price_adjustment: str | None = None) -> dict:
+        """Declare the price adjustment the selected source would return for this request.
+
+        The declaration includes evidence and must match an explicit request before loading.
+        """
+        ...
+
+    def cache_identity(self) -> dict:
+        """Declare the stable configuration that determines cached data."""
+        ...
+
+    def is_available(self) -> bool:
+        """检查当前数据源是否可用（例如 token 是否有效、网络是否通畅）。"""
+        return True
+
+
+_INTERVAL = re.compile(
+    r"\s*(\d+(?:\.\d+)?)\s*"
+    r"(ns|us|µs|ms|s|sec|secs|second|seconds|m|min|mins|minute|minutes|"
+    r"h|hr|hrs|hour|hours|d|day|days|w|week|weeks)\s*"
+)
+_UNIT_MICROSECONDS = {
+    "ns": Decimal("0.001"),
+    "us": Decimal(1),
+    "µs": Decimal(1),
+    "ms": Decimal(1_000),
+    "s": Decimal(1_000_000),
+    "sec": Decimal(1_000_000),
+    "secs": Decimal(1_000_000),
+    "second": Decimal(1_000_000),
+    "seconds": Decimal(1_000_000),
+    "m": Decimal(60_000_000),
+    "min": Decimal(60_000_000),
+    "mins": Decimal(60_000_000),
+    "minute": Decimal(60_000_000),
+    "minutes": Decimal(60_000_000),
+    "h": Decimal(3_600_000_000),
+    "hr": Decimal(3_600_000_000),
+    "hrs": Decimal(3_600_000_000),
+    "hour": Decimal(3_600_000_000),
+    "hours": Decimal(3_600_000_000),
+    "d": Decimal(86_400_000_000),
+    "day": Decimal(86_400_000_000),
+    "days": Decimal(86_400_000_000),
+    "w": Decimal(604_800_000_000),
+    "week": Decimal(604_800_000_000),
+    "weeks": Decimal(604_800_000_000),
+}
+
+
+def _interval_delta(value: object) -> timedelta:
+    """Resolve an explicit fixed interval into exact whole microseconds."""
+    if not isinstance(value, str):
+        raise ValueError("data.interval must be a positive fixed interval")
+    match = _INTERVAL.fullmatch(value)
+    if match is None:
+        raise ValueError("data.interval must be a positive fixed interval")
+    microseconds = Decimal(match.group(1)) * _UNIT_MICROSECONDS[match.group(2)]
+    if microseconds <= 0 or microseconds != microseconds.to_integral_value():
+        raise ValueError("data.interval must resolve to positive whole microseconds")
+    return timedelta(microseconds=int(microseconds))

nlalpha_data/calendar/__init__.py

@@ -0,0 +1,15 @@
+"""交易日历子包。
+
+提供各市场的交易日历实现：
+- USEquityCalendar：美股（NYSE / NASDAQ）
+- CNEquityCalendar：中国 A 股（沪深）
+- FuturesCalendar：国内期货（四大交易所）
+
+作者：kimi（2026-05-07）
+"""
+
+from .cn_equity import CNEquityCalendar
+from .futures import FuturesCalendar
+from .us_equity import USEquityCalendar
+
+__all__ = ["CNEquityCalendar", "FuturesCalendar", "USEquityCalendar"]

nlalpha_data/calendar/cn_equity.py

@@ -0,0 +1,27 @@
+"""Resolve Chinese equity sessions with an explicitly selected exchange calendar."""
+
+from datetime import date, datetime
+from nlalpha.core.errors import DataError
+from nlalpha_data.calendar_base import TradingCalendar, exchange_calendar, session_bounds
+
+
+class CNEquityCalendar(TradingCalendar):
+    """Provide exact XSHG or XBSE sessions for domestic equities."""
+
+    market = "CN_EQUITY"
+    timezone = "Asia/Shanghai"
+
+    def __init__(self, calendar_id: str = "XSHG"):
+        if not isinstance(calendar_id, str) or calendar_id not in {"XSHG", "XBSE"}:
+            raise DataError("CNEquityCalendar supports only XSHG and XBSE.", details={"time_contract": True})
+        self.calendar_id = calendar_id
+        self._ec = exchange_calendar(calendar_id)
+
+    def is_trading_day(self, d: date) -> bool:
+        """Check the declared exchange's actual session label."""
+        from pandas import Timestamp
+        return self._ec.is_session(Timestamp(d))
+
+    def session_bounds(self, d: date) -> tuple[datetime, datetime]:
+        """Return the declared exchange's UTC open and close."""
+        return session_bounds(self.calendar_id, d)

nlalpha_data/calendar/futures.py

@@ -0,0 +1,54 @@
+"""期货交易日历。
+
+国内期货市场交易日历：
+- 上期所 (SHFE)
+- 大商所 (DCE)
+- 郑商所 (CZCE)
+- 中金所 (CFFEX)
+
+特点：
+- 周六、周日休市
+- 法定节假日休市（与 A 股基本一致）
+- 无盘前盘后（与美股不同）
+
+依赖：
+- 优先使用 exchange-calendars（如果已安装）
+- 未安装时退化为 WeekendOnlyCalendar（仅排除周末）
+
+作者：kimi（2026-05-06）
+"""
+
+from datetime import date
+
+from nlalpha_data.calendar_base import WeekendOnlyCalendar
+
+
+class FuturesCalendar(WeekendOnlyCalendar):
+    """国内期货交易日历。
+
+    覆盖四大期货交易所的公共交易日历。
+    各交易所个别差异（如品种特定交割日）不在此处理，由 Broker 层负责。
+    """
+
+    market = "CN_FUTURES"
+    timezone = "Asia/Shanghai"
+
+    def __init__(self):
+        self._ec = None
+        try:
+            import exchange_calendars as ec
+            # 中金所日历最接近国内期货整体日历
+            self._ec = ec.get_calendar("XSHG")  # 上交所（A股日历 ≈ 期货日历）
+        except ImportError:
+            pass
+
+        # 不再自建节假日表，完全依赖 exchange-calendars
+        # 若 exchange-calendars 未安装，fallback 到 WeekendOnlyCalendar（仅排除周末）
+        super().__init__()
+
+    def is_trading_day(self, d: date) -> bool:
+        if self._ec is not None:
+            from pandas import Timestamp
+            ts = Timestamp(d)
+            return self._ec.is_session(ts)
+        return super().is_trading_day(d)

nlalpha_data/calendar/us_equity.py

@@ -0,0 +1,24 @@
+"""Resolve United States equity sessions including DST and shortened days."""
+
+from datetime import date, datetime
+from nlalpha_data.calendar_base import TradingCalendar, exchange_calendar, session_bounds
+
+
+class USEquityCalendar(TradingCalendar):
+    """Provide exact XNYS session labels and endpoints."""
+
+    market = "US_EQUITY"
+    timezone = "America/New_York"
+    calendar_id = "XNYS"
+
+    def __init__(self):
+        self._ec = exchange_calendar(self.calendar_id)
+
+    def is_trading_day(self, d: date) -> bool:
+        """Check whether NYSE has a session with this local date label."""
+        from pandas import Timestamp
+        return self._ec.is_session(Timestamp(d))
+
+    def session_bounds(self, d: date) -> tuple[datetime, datetime]:
+        """Return NYSE's actual UTC open and close."""
+        return session_bounds(self.calendar_id, d)

nlalpha_data/calendar_base.py

@@ -0,0 +1,201 @@
+"""交易日历抽象。
+
+T3.1（2026-05-06）新增：支撑多市场回测的交易日历基础设施。
+
+职责：
+- 判断某日是否为交易日
+- 计算下一个/前 N 个交易日
+- 计算结算日（T+0 / T+1 / T+2）
+
+设计原则：
+- 最小接口，不依赖外部库（exchange-calendars 为可选增强）
+- 默认实现仅判断周末，各市场子类可覆盖节假日
+- 所有日期操作使用 datetime.date，不含时区
+
+作者：kimi（2026-05-06）
+"""
+
+from abc import ABC, abstractmethod
+from datetime import date, datetime, timedelta
+from functools import lru_cache
+
+from nlalpha.core.contracts.time import normalize_utc
+from nlalpha.core.errors import DataError
+
+
+class TradingCalendar(ABC):
+    """交易日历抽象基类。
+
+    用法：
+        cal = USEquityCalendar()
+        cal.is_trading_day(date(2024, 1, 1))  # False (New Year's Day)
+        cal.add_trading_days(date(2024, 1, 1), 2)  # date(2024, 1, 3)
+        cal.settlement_date(date(2024, 1, 2), rule="t+2")  # date(2024, 1, 4)
+    """
+
+    @property
+    @abstractmethod
+    def market(self) -> str:
+        """市场标识，如 "US_EQUITY", "CN_EQUITY", "FUTURES"。"""
+        ...
+
+    @property
+    @abstractmethod
+    def timezone(self) -> str:
+        """市场时区，如 "America/New_York", "Asia/Shanghai"。"""
+        ...
+
+    # ------------------------------------------------------------------
+    # 核心查询
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def is_trading_day(self, d: date) -> bool:
+        """判断某日是否为交易日。"""
+        ...
+
+    def session_bounds(self, d: date) -> tuple[datetime, datetime]:
+        """Resolve a labeled session into its authoritative UTC endpoints."""
+        raise DataError(
+            f"Calendar {self.market!r} has no authoritative session bounds; configure a symbol-specific session calendar.",
+            details={"time_contract": True},
+        )
+
+    def next_trading_day(self, d: date) -> date:
+        """返回 d 的下一个交易日（若 d 本身是交易日，则返回 d 的下一个交易日）。"""
+        nxt = d + timedelta(days=1)
+        while not self.is_trading_day(nxt):
+            nxt += timedelta(days=1)
+        return nxt
+
+    def prev_trading_day(self, d: date) -> date:
+        """返回 d 的上一个交易日。"""
+        prev = d - timedelta(days=1)
+        while not self.is_trading_day(prev):
+            prev -= timedelta(days=1)
+        return prev
+
+    def add_trading_days(self, d: date, n: int) -> date:
+        """从 d 起加减 n 个交易日。
+
+        n 为正：向后数；n 为负：向前数；n 为 0：返回 d 本身（不检查是否为交易日）。
+        """
+        result = d
+        step = 1 if n >= 0 else -1
+        count = 0
+        while count < abs(n):
+            result += timedelta(days=step)
+            if self.is_trading_day(result):
+                count += 1
+        return result
+
+    # ------------------------------------------------------------------
+    # 结算日计算
+    # ------------------------------------------------------------------
+
+    def settlement_date(self, trade_date: date, rule: str = "t+1") -> date:
+        """根据交收规则计算结算日。
+
+        Args:
+            trade_date: 交易日
+            rule: "t+0" / "t+1" / "t+2" / "t+3"
+
+        Returns:
+            结算日（考虑节假日，只算交易日）
+        """
+        days = self._parse_settlement_rule(rule)
+        return self.add_trading_days(trade_date, days)
+
+    @staticmethod
+    def _parse_settlement_rule(rule: str) -> int:
+        """解析结算规则字符串为交易日数。"""
+        mapping = {
+            "t+0": 0,
+            "t+1": 1,
+            "t+2": 2,
+            "t+3": 3,
+        }
+        return mapping.get(rule.lower(), 1)
+
+    # ------------------------------------------------------------------
+    # 交易日计数
+    # ------------------------------------------------------------------
+
+    def trading_days_between(self, start: date, end: date) -> int:
+        """计算 [start, end] 区间内的交易日数量（含两端）。"""
+        if start > end:
+            return 0
+        count = 0
+        current = start
+        while current <= end:
+            if self.is_trading_day(current):
+                count += 1
+            current += timedelta(days=1)
+        return count
+
+
+class WeekendOnlyCalendar(TradingCalendar):
+    """仅判断周末的简化日历（无节假日）。
+
+    作为默认 fallback：当 exchange-calendars 未安装时，
+    各市场子类可继承此类并只覆盖节假日列表。
+    """
+
+    market: str = "generic"
+    timezone: str = "UTC"
+
+    def __init__(self, holidays: set[date] | None = None):
+        self._holidays = holidays or set()
+
+    def is_trading_day(self, d: date) -> bool:
+        """周六、周日和节假日为非交易日。"""
+        if d.weekday() >= 5:  # 5=Saturday, 6=Sunday
+            return False
+        if d in self._holidays:
+            return False
+        return True
+
+    def add_holiday(self, d: date) -> None:
+        """动态添加节假日（用于测试或自定义）。"""
+        self._holidays.add(d)
+
+
+def exchange_calendar(calendar_id: str):
+    """Resolve an explicitly named exchange calendar without substitution."""
+    if not isinstance(calendar_id, str) or not calendar_id or calendar_id != calendar_id.strip():
+        raise DataError("A nonempty exchange calendar_id is required.", details={"time_contract": True})
+    return _exchange_calendar(calendar_id)
+
+
+@lru_cache(maxsize=64)
+def _exchange_calendar(calendar_id: str):
+    """Cache validated exchange-calendar identifiers."""
+    import exchange_calendars as ec
+    if calendar_id not in ec.get_calendar_names():
+        raise DataError(f"Unknown exchange calendar_id: {calendar_id!r}.", details={"time_contract": True})
+    try:
+        return ec.get_calendar(calendar_id)
+    except Exception as exc:
+        raise DataError(f"Cannot resolve calendar {calendar_id!r}: {exc}", details={"time_contract": True}) from exc
+
+
+def session_bounds(calendar_id: str, session_date: date) -> tuple[datetime, datetime]:
+    """Return actual session endpoints including holidays and shortened sessions."""
+    from pandas import Timestamp
+    calendar = exchange_calendar(calendar_id)
+    try:
+        label = Timestamp(session_date)
+        if not calendar.is_session(label):
+            raise ValueError("date is not a trading session")
+        source_zone = str(calendar.tz)
+        begin_local = calendar.session_open(label).tz_convert(calendar.tz).tz_localize(None)
+        finish_local = calendar.session_close(label).tz_convert(calendar.tz).tz_localize(None)
+        begin = normalize_utc(begin_local, source_timezone=source_zone)
+        finish = normalize_utc(finish_local, source_timezone=source_zone)
+        if not begin < finish:
+            raise ValueError("session open must precede close")
+        return begin, finish
+    except Exception as exc:
+        if isinstance(exc, DataError):
+            raise
+        raise DataError(f"Cannot resolve {calendar_id} session {session_date}: {exc}", details={"time_contract": True}) from exc

nlalpha_data/calendar_tools.py

@@ -0,0 +1,133 @@
+"""交易日历工具 —— 直接暴露 exchange_calendars 原生能力。
+
+系统不维护任何节假日表，不自建推断逻辑。
+Agent 自行选择交易所、自行计算交易日、自行评估数据质量。
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date
+
+from nlalpha.core.result_contract import failure_response
+
+logger = logging.getLogger("nlalpha-data.calendar")
+
+# 日历 ID 别名归一：exchange_calendars 4.13 已移除 XSHE（深交所），A 股沪深统一休市，映射到 XSHG
+_CALENDAR_ALIASES = {
+    "XSHE": "XSHG",
+}
+
+
+def _normalize_calendar_id(calendar_id: str) -> str:
+    """Normalize legacy calendar IDs to IDs present in the installed version."""
+    return _CALENDAR_ALIASES.get(calendar_id, calendar_id)
+
+
+def _get_ec_calendar(calendar_id: str):
+    """Get an exchange_calendars calendar by ID."""
+    import exchange_calendars as ec
+    return ec.get_calendar(_normalize_calendar_id(calendar_id))
+
+
+def list_trading_calendars() -> list[dict]:
+    """List all available trading calendars from exchange_calendars.
+
+    列出 exchange_calendars 支持的所有交易所日历。
+
+    Returns:
+        List of {"id": str, "name": str}.
+    """
+    import exchange_calendars as ec
+
+    names = ec.get_calendar_names()
+    result = []
+    for cid in sorted(names):
+        try:
+            cal = ec.get_calendar(cid)
+            result.append({
+                "id": cid,
+                "name": getattr(cal, "name", cid),
+                "timezone": str(getattr(cal, "tz", "")),
+            })
+        except Exception as e:
+            logger.debug("skip calendar | id=%s | error=%s", cid, e)
+    return result
+
+
+def get_trading_days(calendar_id: str, start: str, end: str) -> dict:
+    """Get the number of trading days between start and end for a given calendar.
+
+    返回指定交易所日历在区间内的交易日数量。
+
+    Args:
+        calendar_id: Exchange calendar ID, e.g. "XSHG" (上交所), "XNYS" (纽交所)
+        start: Start date "YYYY-MM-DD"
+        end: End date "YYYY-MM-DD"
+
+    Returns:
+        {"calendar_id": str, "start": str, "end": str, "trading_days": int}
+    """
+    try:
+        cal = _get_ec_calendar(calendar_id)
+        sessions = cal.sessions_in_range(start, end)
+        trading_days = len(sessions)
+        return {
+            "calendar_id": calendar_id,
+            "start": start,
+            "end": end,
+            "trading_days": trading_days,
+        }
+    except Exception as e:
+        logger.warning("get_trading_days failed | %s %s~%s | error=%s", calendar_id, start, end, e)
+        return {
+            **failure_response(e),
+            "calendar_id": calendar_id,
+            "start": start,
+            "end": end,
+        }
+
+
+def is_trading_day(calendar_id: str, date_str: str) -> dict:
+    """Check whether a specific date is a trading day on the given calendar.
+
+    判断指定日期是否为给定交易所的交易日。
+
+    Args:
+        calendar_id: Exchange calendar ID, e.g. "XSHG"
+        date_str: Date "YYYY-MM-DD"
+
+    Returns:
+        {"calendar_id": str, "date": str, "is_trading_day": bool}
+    """
+    try:
+        cal = _get_ec_calendar(calendar_id)
+        from pandas import Timestamp
+        ts = Timestamp(date_str)
+        is_session = cal.is_session(ts)
+        return {
+            "calendar_id": calendar_id,
+            "date": date_str,
+            "is_trading_day": bool(is_session),
+        }
+    except Exception as e:
+        logger.warning("is_trading_day failed | %s %s | error=%s", calendar_id, date_str, e)
+        return {
+            **failure_response(e),
+            "calendar_id": calendar_id,
+            "date": date_str,
+        }
+
+
+def confess() -> dict:
+    """Describe how to discover and interpret the available exchange calendars."""
+    guide = """# Trading calendar guide
+
+`list_trading_calendars()` discovers calendar IDs from the installed `exchange_calendars` library. Call it first and use an ID returned by that call; the available catalog can vary with the installed library version. `get_trading_days(calendar_id, start, end)` returns the number of sessions in the requested date range, and `is_trading_day(calendar_id, date)` checks one date. Preserve any returned error as unavailable calendar evidence.
+
+This module normalizes the legacy ID `XSHE` to `XSHG` for calendar lookup. That single compatibility alias does not establish that every market calendar is identical or that `XSHG` is appropriate for another instrument.
+
+Trading-session counts are not observed-bar counts or missing-bar counts. Do not calculate missing sessions as `trading_days - bar_count`: duplicate bars, intraday intervals, partial sessions, or different bar coverage can make that subtraction wrong. For an exact missing-session result, compare observed per-day session dates with the sessions and applicable schedule for the requested instrument. If those observations or a suitable calendar/session definition are unavailable, report the exact missing count as unknown.
+
+Do not assume a calendar for futures or another instrument class. Use only a calendar explicitly supported by the current source contract or the instrument's verified session schedule; an unverified calendar leaves the result unknown."""
+    return {"guide": guide}