quantred 2.4.0__py3-none-any.whl

quantred/execution/sizing.py

@@ -0,0 +1,114 @@
+"""Pluggable position sizing for live execution - i.e. how much to bet, which is at
+least as important as what to bet on and far easier to get catastrophically wrong.
+
+`LiveTrader` asks a :class:`PositionSizer` "how many units of this symbol should I
+buy at this price?" - it doesn't care *how* the answer is reached. Two strategies
+ship:
+
+* :class:`RiskBasedSizer` - the default; sizes each entry from the strategy's
+  risk-per-trade / stop-loss config (position-by-position).
+* :class:`PortfolioWeightSizer` - sizes to a precomputed target weight per symbol,
+  e.g. from the OR-Tools :class:`~quantred.portfolio.allocator.PortfolioAllocator`
+  (portfolio-level).
+
+This keeps sizing policy out of `LiveTrader` and lets the portfolio manager drive
+live sizing without the executor knowing anything about it.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict
+
+from quantred.brokers.base import AccountSnapshot
+from quantred.strategies.base import Strategy
+
+
+def below_min_notional(qty: float, price: float, min_notional) -> bool:
+    """Whether a rounded order is too small for the venue to be worth sending.
+
+    One definition, reached by both clocks. The backtest refused an entry under the
+    floor and the live path did not look at it at all, so a config validated with a
+    floor traded without one — the same declared book admitting different orders
+    depending on which clock was asking, which is the failure mode the two-clock
+    separation makes invisible.
+
+    A floor is an execution fact rather than a preference: an order below it is
+    refused at the venue, or its costs swamp what it can earn. Filling one in a
+    backtest validates a book that could not be traded; sending one live trades a book
+    that was never validated.
+
+    An undeclared floor bounds nothing — absent is not zero, and a book that never
+    named a minimum has no minimum rather than one of zero.
+    """
+    return bool(min_notional) and abs(qty) * price < min_notional
+
+
+class PositionSizer(ABC):
+    """Decides the (pre-rounding) size of a new position."""
+
+    @abstractmethod
+    def size(self, symbol: str, price: float, account: AccountSnapshot) -> float:
+        """Return the desired position size in units (shares)."""
+
+
+class RiskBasedSizer(PositionSizer):
+    """Size each entry from the strategy's risk/stop configuration."""
+
+    def __init__(self, strategy: Strategy):
+        self._strategy = strategy
+
+    def size(self, symbol: str, price: float, account: AccountSnapshot) -> float:
+        return self._strategy.calculate_position_size(account.buying_power, price)
+
+
+class BetaSizer(PositionSizer):
+    """Risk-based sizing scaled inversely by each symbol's beta.
+
+    Higher beta (more volatile relative to the benchmark) -> smaller position, so
+    risk is more even across names. Betas are precomputed per symbol (sizing has
+    no data access); unknown symbols fall back to ``default_beta``. The effective
+    beta is clamped to ``[min_abs_beta, max_abs_beta]`` to avoid blow-ups near
+    zero and to bound leverage for tiny betas; the sign is ignored (a strongly
+    negative beta is still volatile).
+
+    It takes the strategy's normally-sized position (which already respects
+    risk-per-trade and position limits) and divides it by the effective beta, so
+    the scaling always applies - even when a position-limit cap is the binding
+    constraint.
+    """
+
+    def __init__(
+        self,
+        strategy: Strategy,
+        betas: Dict[str, float],
+        default_beta: float = 1.0,
+        min_abs_beta: float = 0.25,
+        max_abs_beta: float = 4.0,
+    ):
+        self._strategy = strategy
+        self._betas = betas
+        self._default_beta = default_beta
+        self._min_abs_beta = min_abs_beta
+        self._max_abs_beta = max_abs_beta
+
+    def size(self, symbol: str, price: float, account: AccountSnapshot) -> float:
+        beta = self._betas.get(symbol, self._default_beta)
+        effective = min(max(abs(beta), self._min_abs_beta), self._max_abs_beta)
+        base_size = self._strategy.calculate_position_size(account.buying_power, price)
+        return base_size / effective
+
+
+class PortfolioWeightSizer(PositionSizer):
+    """Size to a target portfolio weight per symbol (weight x equity / price).
+
+    Symbols absent from the weight map get zero size, so the live universe is
+    effectively the set the allocator chose to fund.
+    """
+
+    def __init__(self, weights: Dict[str, float]):
+        self._weights = weights
+
+    def size(self, symbol: str, price: float, account: AccountSnapshot) -> float:
+        weight = self._weights.get(symbol, 0.0)
+        if weight <= 0 or price <= 0:
+            return 0.0
+        return (weight * account.equity) / price

quantred/indicators/indicators.py

@@ -0,0 +1,158 @@
+"""Technical indicators implemented with pure pandas/numpy - the squiggly lines we
+all pretend predict the future.
+
+This module is the single source of truth for indicator math in the project.
+It deliberately uses **no compiled dependencies** (no TA-Lib, no tulipy): every
+function here is plain pandas/numpy so the project installs with `pip install`
+alone and the Docker image needs no build toolchain.
+
+All functions are pure: they take Series/DataFrames in and return new
+Series/DataFrames out, leaving the inputs untouched.
+"""
+
+import pandas as pd
+
+
+def calculate_sma(data: pd.Series, period: int) -> pd.Series:
+    """Simple Moving Average."""
+    return data.rolling(window=period).mean()
+
+
+def calculate_ema(data: pd.Series, period: int) -> pd.Series:
+    """Exponential Moving Average."""
+    return data.ewm(span=period, adjust=False).mean()
+
+
+def calculate_rsi(data: pd.Series, period: int = 14) -> pd.Series:
+    """Relative Strength Index (Wilder-style smoothing via rolling mean).
+
+    Args:
+        data: Price series (typically close).
+        period: Lookback period.
+
+    Returns:
+        RSI values in the range [0, 100].
+    """
+    delta = data.diff()
+    gain = delta.where(delta > 0, 0.0).rolling(window=period).mean()
+    loss = (-delta.where(delta < 0, 0.0)).rolling(window=period).mean()
+
+    rs = gain / loss
+    return 100 - (100 / (1 + rs))
+
+
+def calculate_atr(df: pd.DataFrame, period: int = 14) -> pd.Series:
+    """Average True Range.
+
+    Args:
+        df: DataFrame with 'high', 'low', 'close' columns.
+        period: Lookback period.
+
+    Returns:
+        ATR series.
+    """
+    high_low = df["high"] - df["low"]
+    high_close = (df["high"] - df["close"].shift()).abs()
+    low_close = (df["low"] - df["close"].shift()).abs()
+
+    true_range = pd.concat([high_low, high_close, low_close], axis=1).max(axis=1)
+    return true_range.rolling(window=period).mean()
+
+
+def calculate_beta(symbol_close: pd.Series, benchmark_close: pd.Series) -> float:
+    """Beta of a symbol's returns against a benchmark's returns.
+
+    Beta = cov(symbol, benchmark) / var(benchmark), computed on aligned
+    period-over-period returns. Returns 1.0 (market-neutral) for degenerate input
+    (too few overlapping points, or a flat benchmark).
+
+    Args:
+        symbol_close: Close-price series for the symbol.
+        benchmark_close: Close-price series for the benchmark (e.g. SPY).
+
+    Returns:
+        The beta coefficient.
+    """
+    prices = pd.concat([symbol_close, benchmark_close], axis=1, keys=["symbol", "benchmark"]).dropna()
+    if len(prices) < 3:
+        return 1.0
+
+    returns = prices.pct_change().dropna()
+    benchmark_var = returns["benchmark"].var()
+    if benchmark_var == 0 or returns.empty:
+        return 1.0
+
+    covariance = returns["symbol"].cov(returns["benchmark"])
+    return float(covariance / benchmark_var)
+
+
+def calculate_residual_volatility(
+    symbol_close: pd.Series,
+    benchmark_close: pd.Series,
+    beta: float,
+    periods_per_year: float = 252.0,
+) -> float:
+    """Annualized volatility of a symbol's *residual* returns vs a benchmark.
+
+    Residual return strips out the part of the move that beta to the benchmark
+    explains: ``r_resid = r_symbol - beta * r_benchmark``. Its annualized std is the
+    ``sigma`` the alpha-scaling identity (alpha = sigma * IC * z) needs - the risk
+    of the bet that *isn't* just market exposure.
+
+    Computed on aligned period-over-period returns. Returns 0.0 for degenerate
+    input (too few overlapping points). ``periods_per_year`` annualizes to the
+    sampling frequency of the series passed in (daily bars -> 252).
+
+    Args:
+        symbol_close: Close-price series for the symbol.
+        benchmark_close: Close-price series for the benchmark (e.g. SPY).
+        beta: The symbol's beta to the benchmark (see :func:`calculate_beta`).
+        periods_per_year: Annualization factor for the bar frequency.
+
+    Returns:
+        Annualized residual volatility (a fraction, e.g. 0.20 == 20%/yr).
+    """
+    prices = pd.concat([symbol_close, benchmark_close], axis=1, keys=["symbol", "benchmark"]).dropna()
+    if len(prices) < 3:
+        return 0.0
+
+    returns = prices.pct_change().dropna()
+    if returns.empty:
+        return 0.0
+
+    residual = returns["symbol"] - beta * returns["benchmark"]
+    std = residual.std()
+    if not (std == std):  # NaN guard
+        return 0.0
+    return float(std * (periods_per_year**0.5))
+
+
+def calculate_volume_spike(
+    volume: pd.Series,
+    price: pd.Series,
+    volume_ma_period: int = 20,
+    volume_threshold: float = 2.0,
+    price_change_threshold: float = 0.02,
+) -> pd.Series:
+    """Detect volume spikes that coincide with meaningful price movement.
+
+    A spike requires both (a) volume above ``volume_threshold`` times its moving
+    average and (b) an absolute one-bar price change above
+    ``price_change_threshold`` (expressed as a fraction, e.g. 0.02 == 2%).
+
+    Args:
+        volume: Volume series.
+        price: Price series (typically close).
+        volume_ma_period: Window for the volume moving average baseline.
+        volume_threshold: Multiplier over the volume MA that defines a spike.
+        price_change_threshold: Minimum absolute fractional price change.
+
+    Returns:
+        Boolean series, True where a qualifying spike occurred.
+    """
+    volume_ma = volume.rolling(window=volume_ma_period).mean()
+    price_change = price.pct_change().abs()
+
+    spikes = (volume > volume_ma * volume_threshold) & (price_change > price_change_threshold)
+    # pct_change/rolling produce NaN at the head; treat those as "no spike".
+    return spikes.fillna(False)

quantred/marketdata/base.py

@@ -0,0 +1,62 @@
+"""Market-data provider abstraction.
+
+Splitting *data* from *trading* keeps the two concerns independent: a deployment
+can pull bars from one vendor and route orders to another. Implementations
+return plain pandas OHLCV frames so strategies and the engine never see vendor
+types.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Awaitable, Callable, Dict, List, Union
+
+import pandas as pd
+
+from quantred.marketdata.timeframe import Timeframe
+
+#: Columns every OHLCV frame returned by a provider must contain.
+OHLCV_COLUMNS = ("open", "high", "low", "close", "volume")
+
+
+@dataclass
+class BarEvent:
+    """A single bar pushed by a live stream."""
+
+    symbol: str
+    timestamp: datetime
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: float
+
+
+#: A bar handler may be sync or async; the provider awaits it if needed.
+BarHandler = Callable[[BarEvent], Union[None, Awaitable[None]]]
+
+
+class MarketDataProvider(ABC):
+    """Interface every market-data source must implement."""
+
+    @abstractmethod
+    def get_bars(
+        self,
+        symbols: List[str],
+        timeframe: Timeframe,
+        start: datetime,
+        end: datetime,
+    ) -> Dict[str, pd.DataFrame]:
+        """Fetch historical bars.
+
+        Returns a mapping of ``symbol -> OHLCV DataFrame`` indexed by a tz-aware
+        timestamp. Symbols with no data are omitted.
+        """
+
+    @abstractmethod
+    async def stream_bars(self, symbols: List[str], handler: BarHandler) -> None:
+        """Subscribe to live bars and invoke ``handler`` for each, until canceled."""
+
+    def supports_streaming(self) -> bool:
+        """Whether this provider can stream live bars. Override if not."""
+        return True

quantred/marketdata/client.py

@@ -0,0 +1,59 @@
+"""High-level market-data access - the one part of the pipeline that, mercifully,
+just returns bars and doesn't have opinions about whether you'll make money.
+
+A thin orchestration layer over a :class:`MarketDataProvider`. It owns the
+friendly timeframe-string API and the live-stream entry point, and is the object
+the engine talks to - so the engine never depends on a concrete data vendor.
+"""
+
+import logging
+from datetime import datetime
+from typing import Dict, List, Union
+
+import pandas as pd
+
+from quantred.marketdata.base import BarHandler, MarketDataProvider
+from quantred.marketdata.timeframe import Timeframe
+
+logger = logging.getLogger(__name__)
+
+TimeframeLike = Union[str, Timeframe]
+
+
+class MarketDataClient:
+    """Fetches historical bars and dispatches live bars via an injected provider."""
+
+    def __init__(self, provider: MarketDataProvider):
+        self._provider = provider
+
+    @property
+    def provider(self) -> MarketDataProvider:
+        """The underlying provider - lets a caller detect e.g. a cache wrapper
+        without reaching into a private attribute."""
+        return self._provider
+
+    def get_bars(
+        self,
+        symbols: List[str],
+        timeframe: TimeframeLike,
+        start: datetime,
+        end: datetime,
+    ) -> Dict[str, pd.DataFrame]:
+        """Return ``{symbol: OHLCV DataFrame}`` for the requested window."""
+        tf = self._coerce_timeframe(timeframe)
+        data = self._provider.get_bars(symbols, tf, start, end)
+        logger.info("Fetched bars for %d/%d symbols (%s)", len(data), len(symbols), tf)
+        return data
+
+    async def stream(self, symbols: List[str], handler: BarHandler) -> None:
+        """Stream live bars for ``symbols``, invoking ``handler`` per bar."""
+        if not self._provider.supports_streaming():
+            raise RuntimeError("The configured market-data provider does not support streaming")
+        await self._provider.stream_bars(symbols, handler)
+
+    def supports_streaming(self) -> bool:
+        return self._provider.supports_streaming()
+
+    @staticmethod
+    def _coerce_timeframe(timeframe: TimeframeLike) -> Timeframe:
+        return timeframe if isinstance(timeframe, Timeframe) else Timeframe.parse(timeframe)

quantred/marketdata/session.py

@@ -0,0 +1,112 @@
+"""A session-scoped, in-memory bar cache.
+
+A composite research command runs several analysis steps against one universe and
+one window. Each step fetches its own bars, so the same request is issued many
+times over a single run - the universe scan, the alpha panel, the covariance
+lookback, and the information sampler all want the same frames.
+
+:class:`SessionBarCache` wraps a provider and serves a repeated request from
+memory instead of re-issuing it. It is deliberately *exact*: a response is reused
+only for an identical ``(symbols, timeframe, start, end)`` request, so the frames
+a caller sees are byte-identical to the ones the underlying provider would have
+returned. It never slices a wider fetch down to a narrower window - that would
+make the wrapper's output depend on request order, which is precisely the kind of
+silent divergence a research result cannot afford.
+
+Scope is one command, not one process: there is no eviction and no persistence.
+For durable, cross-run caching see the Parquet-backed bar cache
+(:class:`~quantred.store.bars.CachedMarketData`), which this composes with rather than
+replaces - wrapping a cache-backed client keeps the cache's own behavior (gap
+fill, vintage stamping) intact underneath.
+"""
+
+import logging
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+import pandas as pd
+
+from quantred.marketdata.base import BarHandler, MarketDataProvider
+from quantred.marketdata.timeframe import Timeframe
+
+logger = logging.getLogger(__name__)
+
+#: The cache key for one fetch: the exact symbols, timeframe, and window asked for.
+_Key = Tuple[Tuple[str, ...], str, str, str]
+
+
+def _stamp(when: Any) -> str:
+    """A stable string for a window bound (``None`` included) so it can key a dict."""
+    iso = getattr(when, "isoformat", None)
+    return iso() if callable(iso) else str(when)
+
+
+class SessionBarCache(MarketDataProvider):
+    """Memoize ``get_bars`` for the lifetime of one composite command.
+
+    ``fetches`` counts requests that reached the wrapped provider; ``requests``
+    counts every call this wrapper received. The difference is the work saved,
+    and both are reported in a composite run's provenance so "one shared fetch"
+    is a measured claim rather than a promise.
+    """
+
+    def __init__(self, provider: MarketDataProvider):
+        self._provider = provider
+        self._frames: Dict[_Key, Dict[str, pd.DataFrame]] = {}
+        self.fetches = 0
+        self.requests = 0
+
+    @property
+    def provider(self) -> MarketDataProvider:
+        """The wrapped provider - so a caller can still detect what is underneath."""
+        return self._provider
+
+    def get_bars(
+        self,
+        symbols: List[str],
+        timeframe: Timeframe,
+        start: datetime,
+        end: datetime,
+    ) -> Dict[str, pd.DataFrame]:
+        """Serve ``{symbol: OHLCV}`` from memory when this exact request was already
+        made in this session, else fetch it and remember the response."""
+        self.requests += 1
+        key = (tuple(symbols), str(timeframe), _stamp(start), _stamp(end))
+        cached = self._frames.get(key)
+        if cached is None:
+            self.fetches += 1
+            cached = self._provider.get_bars(symbols, timeframe, start, end)
+            self._frames[key] = cached
+        # Copy on the way out: callers (the feature panel, the engine) mutate the
+        # frames they receive, and a cache that hands out its own objects would let
+        # one step's edits leak into the next step's inputs.
+        return {symbol: frame.copy() for symbol, frame in cached.items()}
+
+    async def stream_bars(self, symbols: List[str], handler: BarHandler) -> None:
+        """Streaming is passed straight through - there is nothing to memoize."""
+        await self._provider.stream_bars(symbols, handler)
+
+    def supports_streaming(self) -> bool:
+        return self._provider.supports_streaming()
+
+    def stats(self) -> Dict[str, int]:
+        """Request/fetch counts for a run's provenance block."""
+        return {"requests": self.requests, "fetches": self.fetches, "distinct": len(self._frames)}
+
+
+def session_client(data_client) -> Tuple[Any, Optional[SessionBarCache]]:
+    """Wrap ``data_client``'s provider in a :class:`SessionBarCache`.
+
+    Returns ``(client, cache)`` - the client to hand to every step of a composite
+    run, and the cache itself for its stats. If the client exposes no provider
+    (an unusual double or a bare stub), it is returned unchanged with ``None``
+    stats rather than failing: sharing a fetch is an optimization, never a
+    correctness requirement.
+    """
+    from quantred.marketdata.client import MarketDataClient
+
+    provider = getattr(data_client, "provider", None)
+    if provider is None:
+        return data_client, None
+    cache = SessionBarCache(provider)
+    return MarketDataClient(cache), cache

quantred/marketdata/synthetic.py

@@ -0,0 +1,74 @@
+"""Deterministic synthetic market data for the offline ``demo``.
+
+A :class:`MarketDataProvider` that fabricates bars from a seeded random walk, so
+the whole pipeline (backtest, optimize, walk-forward) runs with **no Alpaca keys
+and no network**. Unlike the test fakes, it honors the requested ``[start, end]``
+window and timeframe, so date-based machinery like walk-forward fold splitting
+works exactly as it does on real data.
+
+By construction the series has **no real edge** - it's a drift-free random walk.
+That's deliberate: the demo's punchline is watching honest, out-of-sample
+evaluation refuse to promote noise. If a strategy looks great here in-sample and
+then fails the walk-forward gates, that's the system working, not a bug.
+"""
+
+import math
+from datetime import datetime
+from typing import Dict, List
+
+import numpy as np
+import pandas as pd
+
+from quantred.marketdata.base import BarHandler, MarketDataProvider
+from quantred.marketdata.timeframe import Timeframe
+from quantred.utils.timeutils import NEW_YORK
+
+
+def _symbol_seed(symbol: str, base_seed: int) -> int:
+    """A stable per-symbol seed (independent of Python's hash randomization)."""
+    return base_seed + sum(ord(ch) for ch in symbol)
+
+
+class SyntheticMarketData(MarketDataProvider):
+    """Serves seeded random-walk OHLCV across the requested window and timeframe."""
+
+    def __init__(self, seed: int = 42, annual_drift: float = 0.0, annual_vol: float = 0.35):
+        self._seed = seed
+        self._annual_drift = annual_drift
+        self._annual_vol = annual_vol
+
+    def get_bars(
+        self, symbols: List[str], timeframe: Timeframe, start: datetime, end: datetime
+    ) -> Dict[str, pd.DataFrame]:
+        index = pd.date_range(start=start, end=end, freq=timeframe.to_pandas_offset(), tz=NEW_YORK)
+        if len(index) == 0:
+            return {}
+
+        periods_per_year = timeframe.periods_per_year()
+        sigma = self._annual_vol / math.sqrt(periods_per_year)
+        mu = self._annual_drift / periods_per_year
+
+        return {symbol: self._make_frame(symbol, index, mu, sigma) for symbol in symbols}
+
+    def _make_frame(self, symbol: str, index: pd.DatetimeIndex, mu: float, sigma: float) -> pd.DataFrame:
+        rng = np.random.default_rng(_symbol_seed(symbol, self._seed))
+        n = len(index)
+
+        close = 100.0 * np.exp(np.cumsum(rng.normal(mu, sigma, n)))
+        open_ = close * (1 + rng.normal(0, sigma / 2, n))
+        high = np.maximum(open_, close) * (1 + np.abs(rng.normal(0, sigma / 2, n)))
+        low = np.minimum(open_, close) * (1 - np.abs(rng.normal(0, sigma / 2, n)))
+
+        volume = rng.integers(100_000, 500_000, n).astype(float)
+        volume[rng.choice(n, size=max(n // 20, 1), replace=False)] *= 5  # occasional spikes
+
+        return pd.DataFrame(
+            {"open": open_, "high": high, "low": low, "close": close, "volume": volume},
+            index=index,
+        )
+
+    async def stream_bars(self, symbols: List[str], handler: BarHandler) -> None:  # pragma: no cover
+        raise NotImplementedError("SyntheticMarketData is for offline backtests, not streaming")
+
+    def supports_streaming(self) -> bool:
+        return False