quantred 2.4.0__py3-none-any.whl

quantred/brokers/alpaca/broker.py

@@ -0,0 +1,415 @@
+"""Alpaca implementation of the :class:`Broker` interface.
+
+Along with :mod:`quantred.brokers.alpaca.factory`, this is the only place where
+``alpaca-py`` trading types are imported. It maps
+Alpaca SDK objects to the broker-agnostic domain types in
+:mod:`quantred.brokers.base` so the rest of the system stays vendor-neutral.
+"""
+
+import inspect
+import logging
+from typing import List, Optional
+
+from alpaca.common.exceptions import APIError, RetryException
+from alpaca.trading.client import TradingClient
+from alpaca.trading.enums import OrderClass, OrderType, QueryOrderStatus, TimeInForce
+from alpaca.trading.enums import OrderSide as AlpacaOrderSide
+from alpaca.trading.requests import (
+    GetOrdersRequest,
+    MarketOrderRequest,
+    OrderRequest,
+    StopLossRequest,
+    TakeProfitRequest,
+)
+
+from quantred.brokers.base import (
+    AccountSnapshot,
+    Broker,
+    MarketStatus,
+    OrderResult,
+    OrderSide,
+    Position,
+    TradeUpdate,
+    TradeUpdateHandler,
+)
+from quantred.brokers.errors import (
+    AuthenticationError,
+    BrokerError,
+    BrokerUnavailableError,
+    DuplicateOrderError,
+    InsufficientFundsError,
+    MarketClosedError,
+    NotTradableError,
+    OrderRejectedError,
+    RateLimitedError,
+)
+from quantred.utils.numeric import safe_float
+from quantred.utils.streaming import close_stream, run_with_reconnect
+
+logger = logging.getLogger(__name__)
+
+# Map our side enum onto Alpaca's.
+_SIDE_TO_ALPACA = {OrderSide.BUY: AlpacaOrderSide.BUY, OrderSide.SELL: AlpacaOrderSide.SELL}
+
+
+#: Substrings that identify a duplicate-client-order-id rejection. Alpaca reports it
+#: as a 422 whose message names the field; matching on the text is a heuristic, so an
+#: unrecognized phrasing degrades to a plain rejection rather than being misread as a
+#: success.
+_DUPLICATE_MARKERS = ("already exist", "must be unique", "duplicate")
+
+
+def _rejected_credentials(status: int, message: str) -> str:
+    """What a user should read when the venue refuses their keys.
+
+    The market-data gateway answers a bad key with a bare HTML page, and that page was
+    the whole of the error a verdict printed - three times - without ever saying the
+    keys were the problem. The vendor's text is kept only when it is plain text.
+    """
+    from quantred.settings import invocation, paper_trade_mode
+
+    detail = message.strip()
+    detail = f": {detail}" if detail and not detail.startswith("<") and len(detail) <= 200 else ""
+    # The section that matches the account this run is configured for: telling a live
+    # user to fetch paper keys would send them to the wrong pair.
+    section = "Paper Account" if paper_trade_mode() else "Live Account"
+    return (
+        f"Alpaca rejected these credentials (HTTP {status}{detail}). Check that the key and "
+        f"secret came from the {section} section - paper and live keys differ - "
+        f"then run `{invocation('init')}`."
+    )
+
+
+def classify_error(exc: Exception) -> BrokerError:
+    """Map a vendor exception onto the vendor-neutral hierarchy.
+
+    Defensive by construction: ``APIError`` exposes ``status_code`` and ``message`` as
+    properties that parse the underlying payload, and either can fail on a malformed
+    or non-JSON error body. A classifier that raises while classifying would replace a
+    diagnosable broker failure with an undiagnosable one.
+    """
+    if isinstance(exc, BrokerError):
+        return exc
+
+    status = None
+    message = str(exc)
+    if isinstance(exc, APIError):
+        try:
+            status = exc.status_code
+        except Exception:  # noqa: BLE001 - never fail while classifying a failure
+            status = None
+        try:
+            message = exc.message or message
+        except Exception:  # noqa: BLE001
+            pass
+    elif isinstance(exc, RetryException):
+        return RateLimitedError(message)
+    elif isinstance(exc, (ConnectionError, TimeoutError, OSError)):
+        return BrokerUnavailableError(message)
+
+    lowered = message.lower()
+    if "client_order_id" in lowered and any(m in lowered for m in _DUPLICATE_MARKERS):
+        return DuplicateOrderError(message)
+    if status in (401, 403):
+        return AuthenticationError(_rejected_credentials(status, message))
+    if status == 429:
+        return RateLimitedError(message)
+    if status is not None and status >= 500:
+        return BrokerUnavailableError(message)
+    if "insufficient" in lowered or "buying power" in lowered:
+        return InsufficientFundsError(message)
+    if "market is closed" in lowered or "outside of market hours" in lowered:
+        return MarketClosedError(message)
+    if "not tradable" in lowered or "not active" in lowered:
+        return NotTradableError(message)
+    if status is not None and 400 <= status < 500:
+        return OrderRejectedError(message)
+    return BrokerError(message)
+
+
+def _enum_value(obj, name: str) -> str:
+    """Read an SDK field that may be an enum, a bare string, or absent."""
+    raw = getattr(obj, name, "")
+    return str(getattr(raw, "value", raw) or "")
+
+
+def _timestamp(value) -> Optional[str]:
+    """An ISO timestamp from whatever shape the SDK hands over, or None."""
+    if value is None:
+        return None
+    return value.isoformat() if hasattr(value, "isoformat") else str(value)
+
+
+def _optional_float(value) -> Optional[float]:
+    """A float, or ``None`` when the venue did not report the field at all.
+
+    ``safe_float`` defaults to ``0.0``, which is right for a quantity and wrong for
+    any field whose contract says ``None`` means "not reported" - it turns a paper
+    account's silence about fees into an *observed* zero fee, which ``cost_summary``
+    then counts and reports as measured. The ledger it lands in is append-only, so
+    there is nothing behind it to correct the record from.
+    """
+    if value is None or value == "":
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def to_trade_update(data) -> TradeUpdate:
+    """Convert one Alpaca trade-update payload into the project's TradeUpdate.
+
+    Split out of the stream callback so the mapping can be tested without a socket.
+    It was previously a closure, and the field it silently failed to carry - ``side`` -
+    was therefore unreachable from any test: every fill downstream defaulted to buy,
+    and the ledger recorded every short as a long.
+
+    ``filled_qty`` is Alpaca's *cumulative* fill for the order, not this event's
+    increment, and is passed on as such.
+    """
+    order = getattr(data, "order", None)
+    return TradeUpdate(
+        event=str(getattr(data, "event", "")),
+        symbol=getattr(order, "symbol", ""),
+        order_id=str(getattr(order, "id", "")),
+        status=_enum_value(order, "status"),
+        filled_qty=safe_float(getattr(order, "filled_qty", 0)),
+        price=safe_float(getattr(data, "price", None)) if getattr(data, "price", None) else None,
+        side=_enum_value(order, "side") or None,
+        filled_avg_price=_optional_float(getattr(order, "filled_avg_price", None)),
+        filled_at=_timestamp(getattr(data, "timestamp", None))
+        or _timestamp(getattr(order, "filled_at", None)),
+        # Not ``safe_float``: a venue that reports no fee has not reported a fee of
+        # zero, and the two must stay distinguishable all the way to the ledger.
+        fee=_optional_float(getattr(data, "fee", None)),
+    )
+
+
+class AlpacaBroker(Broker):
+    """Trade and account operations backed by an Alpaca ``TradingClient``."""
+
+    def __init__(
+        self,
+        trading_client: TradingClient,
+        api_key: Optional[str] = None,
+        api_secret: Optional[str] = None,
+        paper: bool = True,
+    ):
+        self._client = trading_client
+        self._tradable_cache: dict[str, bool] = {}
+        # Credentials are only needed for the trade-update WebSocket.
+        self._api_key = api_key
+        self._api_secret = api_secret
+        self._paper = paper
+
+    # ------------------------------------------------------------------ #
+    # Account & positions
+    # ------------------------------------------------------------------ #
+    def get_account(self) -> Optional[AccountSnapshot]:
+        try:
+            account = self._client.get_account()
+            return AccountSnapshot(
+                cash=safe_float(account.cash),
+                equity=safe_float(account.equity),
+                buying_power=safe_float(account.buying_power),
+                portfolio_value=safe_float(account.portfolio_value),
+                trading_blocked=bool(account.trading_blocked),
+            )
+        except Exception as exc:
+            raise classify_error(exc) from exc
+
+    def list_positions(self) -> List[Position]:
+        # Raises rather than returning [] on failure: an empty list is a factual claim
+        # that the account holds nothing, and callers act on it — the strategy's book
+        # is rebuilt from this, and the ledger reads it as broker truth. Turning an
+        # unreachable broker into "you are flat" is how a real position stops being
+        # exitable.
+        try:
+            return [self._to_position(p) for p in self._client.get_all_positions()]
+        except Exception as exc:
+            raise classify_error(exc) from exc
+
+    def get_position(self, symbol: str) -> Optional[Position]:
+        try:
+            return self._to_position(self._client.get_open_position(symbol))
+        except Exception:  # noqa: BLE001 - "no position" is an expected 404
+            return None
+
+    def is_tradable(self, symbol: str) -> bool:
+        if symbol not in self._tradable_cache:
+            try:
+                self._tradable_cache[symbol] = bool(self._client.get_asset(symbol).tradable)
+            except Exception as exc:  # noqa: BLE001
+                logger.info("Could not determine tradability for %s: %s", symbol, exc)
+                self._tradable_cache[symbol] = False
+        return self._tradable_cache[symbol]
+
+    # ------------------------------------------------------------------ #
+    # Orders
+    # ------------------------------------------------------------------ #
+    def submit_market_order(
+        self, symbol: str, qty: float, side: OrderSide, client_order_id: Optional[str] = None
+    ) -> Optional[OrderResult]:
+        try:
+            order = self._client.submit_order(
+                MarketOrderRequest(
+                    symbol=symbol,
+                    qty=qty,
+                    side=_SIDE_TO_ALPACA[side],
+                    time_in_force=TimeInForce.GTC,
+                    client_order_id=client_order_id,
+                )
+            )
+            return self._to_order_result(order, side)
+        except Exception as exc:
+            raise classify_error(exc) from exc
+
+    def submit_bracket_order(
+        self,
+        symbol: str,
+        qty: float,
+        side: OrderSide,
+        stop_loss: float,
+        take_profit: float,
+        client_order_id: Optional[str] = None,
+    ) -> Optional[OrderResult]:
+        try:
+            order = self._client.submit_order(
+                OrderRequest(
+                    symbol=symbol,
+                    qty=qty,
+                    side=_SIDE_TO_ALPACA[side],
+                    type=OrderType.MARKET,
+                    time_in_force=TimeInForce.GTC,
+                    order_class=OrderClass.BRACKET,
+                    take_profit=TakeProfitRequest(limit_price=take_profit),
+                    stop_loss=StopLossRequest(stop_price=stop_loss),
+                    client_order_id=client_order_id,
+                )
+            )
+            return self._to_order_result(order, side)
+        except Exception as exc:
+            raise classify_error(exc) from exc
+
+    def list_open_orders(self, symbol: Optional[str] = None) -> List[OrderResult]:
+        try:
+            request = GetOrdersRequest(
+                status=QueryOrderStatus.OPEN,
+                symbols=[symbol] if symbol else None,
+            )
+            orders = self._client.get_orders(filter=request)
+            return [
+                OrderResult(
+                    id=str(o.id),
+                    symbol=o.symbol,
+                    side=OrderSide(o.side.value),
+                    qty=safe_float(o.qty),
+                    status=str(getattr(o.status, "value", o.status)),
+                    raw=o,
+                )
+                for o in orders
+            ]
+        except Exception as exc:  # noqa: BLE001
+            logger.error("Failed to list open orders: %s", exc)
+            return []
+
+    def cancel_order(self, order_id: str) -> bool:
+        try:
+            self._client.cancel_order_by_id(order_id)
+            return True
+        except Exception as exc:
+            raise classify_error(exc) from exc
+
+    def cancel_all_orders(self) -> bool:
+        try:
+            self._client.cancel_orders()
+            return True
+        except Exception as exc:
+            raise classify_error(exc) from exc
+
+    # ------------------------------------------------------------------ #
+    # Position lifecycle
+    # ------------------------------------------------------------------ #
+    def close_position(self, symbol: str) -> bool:
+        try:
+            self._client.close_position(symbol)
+            return True
+        except Exception as exc:
+            raise classify_error(exc) from exc
+
+    def close_all_positions(self, cancel_orders: bool = True) -> bool:
+        try:
+            self._client.close_all_positions(cancel_orders=cancel_orders)
+            return True
+        except Exception as exc:
+            raise classify_error(exc) from exc
+
+    # ------------------------------------------------------------------ #
+    # Market clock
+    # ------------------------------------------------------------------ #
+    def get_market_status(self) -> Optional[MarketStatus]:
+        try:
+            clock = self._client.get_clock()
+            return MarketStatus(
+                timestamp=clock.timestamp,
+                is_open=clock.is_open,
+                next_open=clock.next_open,
+                next_close=clock.next_close,
+            )
+        except Exception as exc:
+            raise classify_error(exc) from exc
+
+    # ------------------------------------------------------------------ #
+    # Trade-update streaming
+    # ------------------------------------------------------------------ #
+    def supports_trade_updates(self) -> bool:
+        return bool(self._api_key and self._api_secret)
+
+    async def stream_trade_updates(self, handler: TradeUpdateHandler) -> None:
+        from alpaca.trading.stream import TradingStream
+
+        async def on_alpaca_update(data) -> None:
+            update = to_trade_update(data)
+            result = handler(update)
+            if inspect.isawaitable(result):
+                await result
+
+        async def connect() -> None:
+            stream = TradingStream(self._api_key, self._api_secret, paper=self._paper)
+            try:
+                stream.subscribe_trade_updates(on_alpaca_update)
+                logger.info("Subscribed to trade updates")
+                await stream._run_forever()
+            finally:
+                # Never the SDK's synchronous stop() from inside the loop; it blocks
+                # the very loop that would have to run its close. See close_stream.
+                await close_stream(stream)
+
+        await run_with_reconnect("trade-updates", connect)
+
+    # ------------------------------------------------------------------ #
+    # Mapping helpers
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _to_position(pos) -> Position:
+        return Position(
+            symbol=pos.symbol,
+            qty=abs(safe_float(pos.qty)),
+            side=pos.side.value,  # "long" / "short"
+            avg_entry_price=safe_float(pos.avg_entry_price),
+            current_price=safe_float(pos.current_price),
+            market_value=safe_float(pos.market_value),
+            unrealized_pl=safe_float(pos.unrealized_pl),
+        )
+
+    @staticmethod
+    def _to_order_result(order, side: OrderSide) -> OrderResult:
+        return OrderResult(
+            id=str(order.id),
+            symbol=order.symbol,
+            side=side,
+            qty=safe_float(order.qty),
+            status=str(getattr(order.status, "value", order.status)),
+            raw=order,
+        )

quantred/brokers/alpaca/factory.py

@@ -0,0 +1,33 @@
+"""Factories that build Alpaca-backed brokers and market-data providers.
+
+Callers above the broker layer (the CLI, services, account scripts) construct
+Alpaca objects exclusively through these functions, so the ``alpaca`` SDK is
+never imported outside :mod:`quantred.brokers.alpaca`.
+"""
+
+from typing import Optional
+
+from alpaca.data.historical import StockHistoricalDataClient
+from alpaca.trading.client import TradingClient
+
+from quantred.brokers.alpaca.broker import AlpacaBroker
+from quantred.brokers.alpaca.market_data import AlpacaMarketData
+
+
+def build_market_data(api_key: str, api_secret: str, feed: Optional[str] = None) -> AlpacaMarketData:
+    """Build the historical/live market-data provider.
+
+    Constructs no trading client: a process holding only this object is
+    structurally incapable of placing orders.
+
+    ``feed`` pins both the historical and streaming halves to one Alpaca feed;
+    ``None`` leaves the SDK's defaults, which is the historical behaviour.
+    """
+    historical = StockHistoricalDataClient(api_key, api_secret)
+    return AlpacaMarketData(historical, api_key, api_secret, feed=feed)
+
+
+def build_broker(api_key: str, api_secret: str, paper: bool = True) -> AlpacaBroker:
+    """Build the trading broker (account, orders, positions, trade updates)."""
+    trading_client = TradingClient(api_key=api_key, secret_key=api_secret, paper=paper)
+    return AlpacaBroker(trading_client, api_key, api_secret, paper)

quantred/brokers/alpaca/market_data.py

@@ -0,0 +1,166 @@
+"""Alpaca implementation of the :class:`MarketDataProvider` interface.
+
+Along with :mod:`quantred.brokers.alpaca.factory`, the only place where ``alpaca-py``
+market-data types are imported. Converts
+the project's :class:`Timeframe` into Alpaca's ``TimeFrame`` and normalizes the
+returned bars into per-symbol, NY-localized OHLCV frames.
+"""
+
+import inspect
+import logging
+from datetime import datetime
+from typing import Dict, List, Optional
+
+import pandas as pd
+from alpaca.data.enums import DataFeed
+from alpaca.data.historical import StockHistoricalDataClient
+from alpaca.data.live import StockDataStream
+from alpaca.data.requests import StockBarsRequest
+from alpaca.data.timeframe import TimeFrame, TimeFrameUnit
+
+from quantred.brokers.alpaca.broker import classify_error
+from quantred.marketdata.base import BarEvent, BarHandler, MarketDataProvider
+from quantred.marketdata.timeframe import DAY, HOUR, MINUTE, WEEK, Timeframe
+from quantred.utils.streaming import close_stream, run_with_reconnect
+from quantred.utils.timeutils import localize_index_to_new_york
+
+logger = logging.getLogger(__name__)
+
+# Map our canonical timeframe units onto Alpaca's TimeFrameUnit.
+_UNIT_TO_ALPACA = {
+    MINUTE: TimeFrameUnit.Minute,
+    HOUR: TimeFrameUnit.Hour,
+    DAY: TimeFrameUnit.Day,
+    WEEK: TimeFrameUnit.Week,
+}
+
+
+class AlpacaMarketData(MarketDataProvider):
+    """Historical + live equity bars from Alpaca."""
+
+    def __init__(
+        self,
+        historical_client: StockHistoricalDataClient,
+        api_key: str,
+        api_secret: str,
+        base_reconnect_delay: float = 5.0,
+        max_reconnect_delay: float = 60.0,
+        feed: Optional[str] = None,
+    ):
+        self._historical = historical_client
+        self._api_key = api_key
+        self._api_secret = api_secret
+        # One feed for both halves when pinned. Left unset the SDK's own defaults
+        # apply, and those disagree with each other: historical resolves to the full
+        # consolidated tape while the stream defaults to a single venue. An account
+        # entitled to one and not the other then warms up on nothing and streams
+        # fine, which reads as an empty market rather than as a wrong feed.
+        self._feed = feed
+        self._base_reconnect_delay = base_reconnect_delay
+        self._max_reconnect_delay = max_reconnect_delay
+
+    def get_bars(
+        self, symbols: List[str], timeframe: Timeframe, start: datetime, end: datetime
+    ) -> Dict[str, pd.DataFrame]:
+        if not symbols:
+            return {}
+
+        request = StockBarsRequest(
+            symbol_or_symbols=list(symbols),
+            timeframe=self._to_alpaca_timeframe(timeframe),
+            start=start,
+            end=end,
+            adjustment="split",
+            **({"feed": DataFeed(self._feed)} if self._feed else {}),
+        )
+
+        try:
+            combined = self._historical.get_stock_bars(request).df
+        except Exception as exc:  # noqa: BLE001 - re-raised as a typed failure below
+            # Raised, not swallowed into an empty result. A fetch that could not happen
+            # and a window that genuinely held no bars are different facts, and
+            # returning {} for both made them the same one: an unreachable provider
+            # produced a backtest with no trades, which was journaled as an evaluated
+            # trial and then served from cache to the next identical run. Absent is not
+            # zero, and unreachable is not absent.
+            raise classify_error(exc) from exc
+
+        if combined is None or combined.empty:
+            return {}
+
+        return self._split_by_symbol(combined)
+
+    async def stream_bars(self, symbols: List[str], handler: BarHandler) -> None:
+        """Stream live bars for ``symbols``, reconnecting on failure.
+
+        Live WebSockets drop. Each attempt creates a *fresh* stream (the SDK can
+        be left in a bad state after an error), subscribes the monitored symbols,
+        and runs until it errors; on error we back off (capped exponential) and
+        reconnect. Cancellation (e.g. Ctrl-C) breaks out cleanly.
+        """
+        on_bar = self._make_bar_callback(handler)
+
+        async def connect() -> None:
+            stream = self._new_stream()
+            try:
+                for symbol in symbols:
+                    stream.subscribe_bars(on_bar, symbol)
+                logger.info("Subscribed to live bars for %d symbols: %s", len(symbols), symbols)
+                # _run_forever is the awaitable entry point (run() wraps it in
+                # asyncio.run, which we can't use inside an existing loop).
+                await stream._run_forever()
+            finally:
+                await self._safe_stop(stream)
+
+        await run_with_reconnect(
+            "market-data",
+            connect,
+            base_delay=self._base_reconnect_delay,
+            max_delay=self._max_reconnect_delay,
+        )
+
+    def _make_bar_callback(self, handler: BarHandler):
+        """Wrap a project BarHandler as an async Alpaca bar callback."""
+
+        async def _on_alpaca_bar(bar) -> None:
+            event = BarEvent(
+                symbol=bar.symbol,
+                timestamp=bar.timestamp,
+                open=bar.open,
+                high=bar.high,
+                low=bar.low,
+                close=bar.close,
+                volume=bar.volume,
+            )
+            result = handler(event)
+            if inspect.isawaitable(result):
+                await result
+
+        return _on_alpaca_bar
+
+    def _new_stream(self) -> StockDataStream:
+        """Create a fresh stream (isolated for testability)."""
+        if self._feed:
+            return StockDataStream(self._api_key, self._api_secret, feed=DataFeed(self._feed))
+        return StockDataStream(self._api_key, self._api_secret)
+
+    @staticmethod
+    async def _safe_stop(stream) -> None:
+        """Best-effort stream shutdown. See :func:`close_stream` for why not ``stop()``."""
+        await close_stream(stream)
+
+    # ------------------------------------------------------------------ #
+    # Helpers
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _to_alpaca_timeframe(timeframe: Timeframe) -> TimeFrame:
+        return TimeFrame(timeframe.amount, _UNIT_TO_ALPACA[timeframe.unit])
+
+    @staticmethod
+    def _split_by_symbol(combined: pd.DataFrame) -> Dict[str, pd.DataFrame]:
+        """Split Alpaca's (symbol, timestamp) MultiIndex frame into per-symbol frames."""
+        result: Dict[str, pd.DataFrame] = {}
+        for symbol in combined.index.get_level_values(0).unique():
+            frame = combined.xs(symbol, level=0).copy()
+            result[symbol] = localize_index_to_new_york(frame)
+        return result