backtestchat 0.1.0__py3-none-any.whl

backtestchat/broker/base.py

@@ -0,0 +1,247 @@
+"""Broker interface plus pure frequency/window logic and structured errors.
+
+Frequency definitions plus range-key / window-resolution logic. backtestchat is
+Binance-only crypto, and the canonical frequency names ARE the Binance interval
+strings (no asset-class or resample mapping needed).
+
+Everything here is pure (no I/O, no network). The concrete Binance client lives
+in broker/binance.py and implements the Broker ABC.
+"""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+
+# ---------------------------------------------------------------------------
+# Frequencies (Binance interval strings are canonical)
+# ---------------------------------------------------------------------------
+
+# Supported strategy/paper intervals. Internal names are identical to Binance
+# interval strings, so no resample map is needed.
+SUPPORTED_INTERVALS: tuple[str, ...] = ("15m", "1h", "4h", "1d")
+
+# Bars per year for annualization. Crypto trades 24/7/365.
+BARS_PER_YEAR: dict[str, int] = {
+    "15m": 35040,  # 365 * 24 * 4
+    "1h": 8760,    # 365 * 24
+    "4h": 2190,    # 365 * 6
+    "1d": 365,
+}
+
+# Milliseconds per bar, used for kline pagination and close-time math.
+INTERVAL_MS: dict[str, int] = {
+    "15m": 15 * 60 * 1000,
+    "1h": 60 * 60 * 1000,
+    "4h": 4 * 60 * 60 * 1000,
+    "1d": 24 * 60 * 60 * 1000,
+}
+
+DAY_MS = 24 * 60 * 60 * 1000
+
+# ---------------------------------------------------------------------------
+# Range keys (fetch-window resolution)
+# ---------------------------------------------------------------------------
+
+# Named range keys -> calendar days. Ported from v4 market_service.RANGE_DAYS
+# (month = 31, year = 12 * 31 = 372) so a named key and its generic Nm/Ny form
+# resolve identically.
+NAMED_RANGE_DAYS: dict[str, int] = {
+    "1m": 31,
+    "3m": 93,
+    "6m": 186,
+    "1y": 372,
+    "2y": 744,
+    "5y": 1830,
+}
+
+# Generic "Nd" / "Nw" / "Nm" / "Ny" units, in calendar days.
+_UNIT_DAYS = {"d": 1, "w": 7, "m": 31, "y": 372}
+_RANGE_RE = re.compile(r"^(\d+)([dwmy])$")
+
+_RANGE_HINT = (
+    "Use a named key (1m, 3m, 6m, 1y, 2y, 5y) or an Nd/Nw/Nm/Ny form "
+    "(e.g. 30d, 6w, 18m, 3y)."
+)
+
+
+# ---------------------------------------------------------------------------
+# Structured broker errors
+# ---------------------------------------------------------------------------
+
+
+class BrokerError(Exception):
+    """Network/HTTP failure or a non-200 response. Message is surfaced
+    verbatim; the tool layer wraps it into a structured error dict."""
+
+
+class UnknownSymbolError(BrokerError):
+    """Symbol is not in the exchange's tradable set."""
+
+    def __init__(self, symbol: str, suggestions: list[str]):
+        self.symbol = symbol
+        self.suggestions = suggestions
+        message = f"Unknown symbol '{symbol}'."
+        if suggestions:
+            message += f" Did you mean: {', '.join(suggestions)}?"
+        super().__init__(message)
+
+
+class UnknownIntervalError(BrokerError):
+    """Interval is outside SUPPORTED_INTERVALS."""
+
+    def __init__(self, interval: str):
+        self.interval = interval
+        self.valid_options = list(SUPPORTED_INTERVALS)
+        super().__init__(
+            f"Unsupported interval '{interval}'. "
+            f"Valid intervals: {', '.join(SUPPORTED_INTERVALS)}."
+        )
+
+
+class UnknownRangeError(BrokerError):
+    """Range key cannot be resolved to a window."""
+
+    def __init__(self, range_key: str):
+        self.range_key = range_key
+        self.valid_options = list(NAMED_RANGE_DAYS)
+        super().__init__(f"Unknown range key '{range_key}'. {_RANGE_HINT}")
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers
+# ---------------------------------------------------------------------------
+
+
+def validate_interval(interval: str) -> str:
+    """Return the interval if supported, else raise UnknownIntervalError."""
+    if interval not in INTERVAL_MS:
+        raise UnknownIntervalError(interval)
+    return interval
+
+
+def bars_per_year(interval: str) -> int:
+    """Bars per year for annualization (crypto trades 24/7/365).
+
+    Crypto only (24/7/365), so there is no asset-class branch.
+    """
+    validate_interval(interval)
+    return BARS_PER_YEAR[interval]
+
+
+def resolve_range_days(range_key: str) -> int:
+    """Resolve a range key to a positive number of calendar days.
+
+    Accepts named keys (1m/3m/6m/1y/2y/5y) or a generic Nd/Nw/Nm/Ny form.
+    Raises UnknownRangeError on anything else.
+    """
+    if range_key in NAMED_RANGE_DAYS:
+        return NAMED_RANGE_DAYS[range_key]
+
+    match = _RANGE_RE.match(range_key or "")
+    if match:
+        amount = int(match.group(1))
+        if amount > 0:
+            return amount * _UNIT_DAYS[match.group(2)]
+
+    raise UnknownRangeError(range_key)
+
+
+def ms_to_iso(ms: int) -> str:
+    """Epoch milliseconds -> ISO-8601 UTC string, e.g. 2026-07-03T14:00:00Z."""
+    dt = datetime.fromtimestamp(ms / 1000, tz=timezone.utc)
+    return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def iso_to_ms(iso: str) -> int:
+    """Inverse of ms_to_iso: ISO-8601 UTC string -> epoch milliseconds.
+
+    Accepts the canonical ...Z form this codebase produces; a trailing Z or
+    +00:00 offset is treated as UTC.
+    """
+    text = (iso or "").strip().replace("Z", "+00:00")
+    dt = datetime.fromisoformat(text)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return int(dt.timestamp() * 1000)
+
+
+def kline_to_bar(kline: list) -> dict:
+    """Convert a raw Binance kline array to the internal bar contract.
+
+    Binance kline layout: [openTime, open, high, low, close, volume,
+    closeTime, quoteAssetVolume, numTrades, ...]. ts is derived from openTime.
+    All price/volume fields are floats (Decimal-free; fine for a paper sim).
+    """
+    return {
+        "ts": ms_to_iso(int(kline[0])),
+        "open": float(kline[1]),
+        "high": float(kline[2]),
+        "low": float(kline[3]),
+        "close": float(kline[4]),
+        "volume": float(kline[5]),
+    }
+
+
+def drop_forming_klines(klines: list[list], now_ms: int) -> list[list]:
+    """Keep only closed klines (closeTime, index 6, strictly before now).
+
+    Binance returns historical closed candles plus, at the tail, the current
+    still-forming candle whose closeTime is in the future. Only closed bars may
+    enter the engine, paper runner, or charts.
+    """
+    return [k for k in klines if int(k[6]) < now_ms]
+
+
+# ---------------------------------------------------------------------------
+# Broker interface
+# ---------------------------------------------------------------------------
+
+
+class Broker(ABC):
+    """Market-data source interface. Testnet order routing would be a clean
+    adapter add here in v2, but v1 is read-only market data only."""
+
+    @abstractmethod
+    def get_bars(
+        self,
+        symbol: str,
+        interval: str,
+        range_key: str | None = None,
+        start_ms: int | None = None,
+        now_ms: int | None = None,
+    ) -> list[dict]:
+        """Return closed OHLCV bars (internal bar contract) for the window."""
+
+    @abstractmethod
+    def get_quote(self, symbol: str) -> dict:
+        """Return the latest quote for a symbol."""
+
+    @abstractmethod
+    def symbols(self) -> set[str]:
+        """Return the set of tradable symbols."""
+
+    def validate_symbol(self, symbol: str) -> str:
+        """Normalize (uppercase) and validate a symbol against symbols().
+
+        Returns the normalized symbol or raises UnknownSymbolError with
+        suggestions. Concrete brokers may override symbols() caching.
+        """
+        normalized = (symbol or "").strip().upper()
+        known = self.symbols()
+        if normalized in known:
+            return normalized
+        raise UnknownSymbolError(normalized, self._suggest(normalized, known))
+
+    @staticmethod
+    def _suggest(symbol: str, known: set[str], limit: int = 5) -> list[str]:
+        """Best-effort suggestions: symbols sharing a leading prefix."""
+        if not symbol:
+            return []
+        for width in (4, 3, 2):
+            prefix = symbol[:width]
+            matches = sorted(s for s in known if s.startswith(prefix))
+            if matches:
+                return matches[:limit]
+        return []

backtestchat/broker/binance.py

@@ -0,0 +1,290 @@
+"""Keyless Binance public-REST market-data client.
+
+A thin client (in-process TTL caches, loud errors) over the public keyless
+Binance spot API using httpx. No API key is ever sent. Endpoints used:
+
+    GET /api/v3/klines        OHLCV bars (limit 1000, paginate by startTime)
+    GET /api/v3/ticker/24hr   rolling 24h quote
+    GET /api/v3/exchangeInfo  tradable symbol set (cached 24h to a data/ file)
+
+TTL caches (per process): quote 30s, klines 60s per (symbol, interval, range).
+Network failures retry twice with a short backoff; non-200 responses and
+exhausted retries raise BrokerError with the HTTP detail surfaced verbatim.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+import httpx
+
+from backtestchat.broker.base import (
+    DAY_MS,
+    INTERVAL_MS,
+    Broker,
+    BrokerError,
+    drop_forming_klines,
+    kline_to_bar,
+    ms_to_iso,
+    resolve_range_days,
+    validate_interval,
+)
+from backtestchat.config import load_config
+
+BASE_URL = "https://api.binance.com"
+KLINES_LIMIT = 1000
+DEFAULT_RANGE_KEY = "1y"
+
+QUOTE_TTL = 30           # seconds
+KLINES_TTL = 60          # seconds
+EXCHANGE_INFO_TTL = 24 * 60 * 60  # seconds (cached to a data/ file)
+
+_HTTP_TIMEOUT = 15.0
+_RETRIES = 2
+_BACKOFF = 0.5           # seconds, multiplied by attempt number
+
+
+class BinanceBroker(Broker):
+    """Public keyless Binance spot broker."""
+
+    def __init__(
+        self,
+        data_dir: Path | None = None,
+        client: httpx.Client | None = None,
+        known_symbols: set[str] | None = None,
+    ):
+        self._data_dir = data_dir or load_config().data_dir
+        self._client = client or httpx.Client(base_url=BASE_URL, timeout=_HTTP_TIMEOUT)
+        self._owns_client = client is None
+        # In-process caches.
+        self._cache: dict = {}
+        self._symbols: set[str] | None = set(known_symbols) if known_symbols else None
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "BinanceBroker":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # -- clock (overridable for tests) ------------------------------------
+
+    @staticmethod
+    def _now_ms() -> int:
+        return int(time.time() * 1000)
+
+    # -- TTL cache ---------------------------------------------------------
+
+    def _cache_get(self, key: tuple, ttl: float):
+        entry = self._cache.get(key)
+        if not entry:
+            return None
+        stored_at, value = entry
+        if time.time() - stored_at > ttl:
+            self._cache.pop(key, None)
+            return None
+        return value
+
+    def _cache_set(self, key: tuple, value) -> None:
+        self._cache[key] = (time.time(), value)
+
+    # -- HTTP with retry ---------------------------------------------------
+
+    def _get(self, path: str, params: dict | None = None):
+        last_error: Exception | None = None
+        for attempt in range(1, _RETRIES + 1):
+            try:
+                response = self._client.get(path, params=params or {})
+            except httpx.HTTPError as error:
+                last_error = error
+                if attempt < _RETRIES:
+                    time.sleep(_BACKOFF * attempt)
+                continue
+
+            if response.status_code == 200:
+                try:
+                    return response.json()
+                except ValueError as error:
+                    raise BrokerError(
+                        f"Binance returned a non-JSON body for {path}"
+                    ) from error
+
+            # Non-200: surface verbatim, do not retry (e.g. 400 bad params).
+            raise BrokerError(
+                f"Binance {response.status_code} for {path}: "
+                f"{response.text[:300]}"
+            )
+
+        raise BrokerError(f"Binance request to {path} failed: {last_error}")
+
+    # -- symbols -----------------------------------------------------------
+
+    def symbols(self) -> set[str]:
+        if self._symbols is not None:
+            return self._symbols
+
+        cached = self._load_symbol_file()
+        if cached is not None:
+            self._symbols = cached
+            return cached
+
+        data = self._get("/api/v3/exchangeInfo")
+        symbols = {
+            entry["symbol"]
+            for entry in data.get("symbols", [])
+            if entry.get("status") == "TRADING"
+        }
+        self._symbols = symbols
+        self._write_symbol_file(symbols)
+        return symbols
+
+    def _symbol_file(self) -> Path:
+        return self._data_dir / "exchange_info.json"
+
+    def _load_symbol_file(self) -> set[str] | None:
+        path = self._symbol_file()
+        if not path.is_file():
+            return None
+        try:
+            payload = json.loads(path.read_text())
+        except (ValueError, OSError):
+            return None
+        if time.time() - payload.get("fetched_at", 0) > EXCHANGE_INFO_TTL:
+            return None
+        return set(payload.get("symbols", []))
+
+    def _write_symbol_file(self, symbols: set[str]) -> None:
+        try:
+            self._data_dir.mkdir(parents=True, exist_ok=True)
+            self._symbol_file().write_text(
+                json.dumps({"fetched_at": time.time(), "symbols": sorted(symbols)})
+            )
+        except OSError:
+            # Cache write is best-effort; a read-only data dir must not break
+            # data fetching.
+            pass
+
+    # -- bars --------------------------------------------------------------
+
+    def get_bars(
+        self,
+        symbol: str,
+        interval: str,
+        range_key: str | None = None,
+        start_ms: int | None = None,
+        now_ms: int | None = None,
+    ) -> list[dict]:
+        symbol = self.validate_symbol(symbol)
+        validate_interval(interval)
+        now = now_ms if now_ms is not None else self._now_ms()
+
+        # Explicit start (paper-run replay): never cached, window shifts.
+        if start_ms is not None:
+            return self._bars_since(symbol, interval, start_ms, now)
+
+        range_key = range_key or DEFAULT_RANGE_KEY
+        cache_key = ("bars", symbol, interval, range_key)
+        cached = self._cache_get(cache_key, KLINES_TTL)
+        if cached is not None:
+            return cached
+
+        days = resolve_range_days(range_key)
+        start = now - days * DAY_MS
+        bars = self._bars_since(symbol, interval, start, now)
+        self._cache_set(cache_key, bars)
+        return bars
+
+    def _bars_since(
+        self, symbol: str, interval: str, start_ms: int, now_ms: int
+    ) -> list[dict]:
+        raw = self._fetch_klines(symbol, interval, start_ms, now_ms)
+        closed = drop_forming_klines(raw, now_ms)
+        return [kline_to_bar(k) for k in closed]
+
+    def _fetch_klines(
+        self, symbol: str, interval: str, start_ms: int, end_ms: int
+    ) -> list[list]:
+        """Paginate /api/v3/klines by startTime until end_ms or exhaustion."""
+        step = INTERVAL_MS[interval]
+        out: list[list] = []
+        cursor = start_ms
+        while cursor < end_ms:
+            batch = self._get(
+                "/api/v3/klines",
+                params={
+                    "symbol": symbol,
+                    "interval": interval,
+                    "startTime": cursor,
+                    "limit": KLINES_LIMIT,
+                },
+            )
+            if not batch:
+                break
+            out.extend(batch)
+            if len(batch) < KLINES_LIMIT:
+                break
+            next_cursor = int(batch[-1][0]) + step
+            if next_cursor <= cursor:  # safety against non-advancing pagination
+                break
+            cursor = next_cursor
+        return out
+
+    # -- quote -------------------------------------------------------------
+
+    def get_quote(self, symbol: str) -> dict:
+        symbol = self.validate_symbol(symbol)
+        cache_key = ("quote", symbol)
+        cached = self._cache_get(cache_key, QUOTE_TTL)
+        if cached is not None:
+            return cached
+
+        data = self._get("/api/v3/ticker/24hr", params={"symbol": symbol})
+        result = {
+            "symbol": symbol,
+            "price": float(data["lastPrice"]),
+            "changePct": round(float(data["priceChangePercent"]), 4),
+            "prevClose": float(data["prevClosePrice"]),
+            "high": float(data["highPrice"]),
+            "low": float(data["lowPrice"]),
+            "volume": float(data["volume"]),
+            "asOf": ms_to_iso(int(data["closeTime"])),
+        }
+        self._cache_set(cache_key, result)
+        return result
+
+
+# ---------------------------------------------------------------------------
+# Smoke CLI: python -m backtestchat.broker.binance BTCUSDT 1h 1m
+# ---------------------------------------------------------------------------
+
+
+def _smoke(argv: list[str]) -> int:
+    if len(argv) < 2:
+        print("usage: python -m backtestchat.broker.binance SYMBOL [INTERVAL] [RANGE_KEY]")
+        return 2
+    symbol = argv[1]
+    interval = argv[2] if len(argv) > 2 else "1h"
+    range_key = argv[3] if len(argv) > 3 else "1m"
+
+    with BinanceBroker() as broker:
+        quote = broker.get_quote(symbol)
+        print(f"quote {quote['symbol']}: {quote['price']} ({quote['changePct']}% 24h)")
+        bars = broker.get_bars(symbol, interval, range_key=range_key)
+        print(f"bars {symbol} {interval} {range_key}: {len(bars)} closed bars")
+        if bars:
+            print(f"  first: {bars[0]['ts']} close={bars[0]['close']}")
+            print(f"  last:  {bars[-1]['ts']} close={bars[-1]['close']}")
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+
+    raise SystemExit(_smoke(sys.argv))