quantred 2.4.0__py3-none-any.whl

quantred/brokers/base.py

@@ -0,0 +1,220 @@
+"""Broker abstraction.
+
+Everything above this layer (execution, engine, scanners, strategies, main)
+depends only on the :class:`Broker` interface and the broker-agnostic domain
+types defined here - never on a specific vendor SDK. To support a new venue,
+implement :class:`Broker` (see :mod:`quantred.brokers.alpaca.broker`) and inject it;
+nothing else changes.
+
+**Failure is typed, not erased.** Anything that moves money or reports the account's
+actual state raises a :class:`~quantred.brokers.errors.BrokerError` subclass, because
+the caller's correct response differs by cause: back off, stop and get a human, size
+down, or carry on. The methods that answer a genuine yes/no question still return one
+- :meth:`Broker.get_position` returning ``None`` means *flat*, which is an answer
+rather than a failure.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Awaitable, Callable, List, Optional, Union
+
+
+class OrderSide(str, Enum):
+    """Side of an order."""
+
+    BUY = "buy"
+    SELL = "sell"
+
+
+@dataclass
+class AccountSnapshot:
+    """A point-in-time view of the trading account."""
+
+    cash: float
+    equity: float
+    buying_power: float
+    portfolio_value: float
+    trading_blocked: bool = False
+
+
+@dataclass
+class Position:
+    """An open position, normalized across brokers.
+
+    ``side`` is ``"long"`` or ``"short"``; ``qty`` is always non-negative.
+    """
+
+    symbol: str
+    qty: float
+    side: str
+    avg_entry_price: float
+    current_price: float
+    market_value: float
+    unrealized_pl: float
+
+    @property
+    def is_long(self) -> bool:
+        return self.side == "long"
+
+
+@dataclass
+class OrderResult:
+    """The outcome of submitting an order."""
+
+    id: str
+    symbol: str
+    side: OrderSide
+    qty: float
+    status: str
+    raw: object = None  # underlying SDK object, if a caller needs broker specifics
+
+
+@dataclass
+class MarketStatus:
+    """Current market clock."""
+
+    timestamp: datetime
+    is_open: bool
+    next_open: datetime
+    next_close: datetime
+
+
+@dataclass
+class TradeUpdate:
+    """A streamed account/order event (fill, new, canceled, rejected, ...)."""
+
+    event: str
+    symbol: str
+    order_id: str
+    status: str
+    #: Cumulative filled quantity for the order, not this event's increment. Alpaca
+    #: re-reports the running total on every partial fill and again on the final fill.
+    filled_qty: float = 0.0
+    price: Optional[float] = None
+    #: "buy" / "sell". Without it a short fill is indistinguishable from a long one,
+    #: and anything defaulting the side records the whole book long.
+    side: Optional[str] = None
+    #: Average price across everything filled on this order so far. Pairs with
+    #: ``filled_qty``, which is also cumulative; ``price`` is this event's own print.
+    filled_avg_price: Optional[float] = None
+    #: When the venue reported the fill, as an ISO timestamp. Distinct from when we
+    #: recorded it — the gap between the two is latency we would otherwise attribute
+    #: to the venue.
+    filled_at: Optional[str] = None
+    #: What the venue charged, when it says. ``None`` means "not reported", which a
+    #: paper account always does, and which is not the same as zero.
+    fee: Optional[float] = None
+
+
+#: A trade-update handler may be sync or async.
+TradeUpdateHandler = Callable[[TradeUpdate], Union[None, Awaitable[None]]]
+
+
+class Broker(ABC):
+    """Interface every brokerage adapter must implement.
+
+    Kept intentionally small: account/position reads, the order types the engine
+    actually uses, and order/position lifecycle management.
+    """
+
+    # --- account & positions -------------------------------------------------
+    @abstractmethod
+    def get_account(self) -> Optional[AccountSnapshot]:
+        """Return the current account snapshot.
+
+        Raises a :class:`~quantred.brokers.errors.BrokerError` if the account cannot
+        be read.
+        """
+
+    @abstractmethod
+    def list_positions(self) -> List[Position]:
+        """Return all open positions; an empty list means the account is flat.
+
+        Raises a :class:`~quantred.brokers.errors.BrokerError` rather than returning
+        an empty list when positions cannot be read - "flat" and "unknown" are
+        different answers, and callers rebuild state from this one.
+        """
+
+    @abstractmethod
+    def get_position(self, symbol: str) -> Optional[Position]:
+        """Return the open position for ``symbol``, or None if flat."""
+
+    @abstractmethod
+    def is_tradable(self, symbol: str) -> bool:
+        """Whether ``symbol`` can currently be traded on this venue."""
+
+    # --- orders --------------------------------------------------------------
+    @abstractmethod
+    def submit_market_order(
+        self, symbol: str, qty: float, side: OrderSide, client_order_id: Optional[str] = None
+    ) -> Optional[OrderResult]:
+        """Submit a market order.
+
+        ``client_order_id``, when given, is the caller's own identity for this order.
+        A venue that has already accepted it must reject the duplicate rather than
+        place a second order - that rejection is the idempotency guarantee, and it is
+        the only one that survives the submitting process restarting.
+        """
+
+    @abstractmethod
+    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]:
+        """Submit a bracket order (entry + stop-loss + take-profit).
+
+        ``client_order_id`` carries the same meaning as in :meth:`submit_market_order`.
+        """
+
+    @abstractmethod
+    def list_open_orders(self, symbol: Optional[str] = None) -> List[OrderResult]:
+        """Return open (unfilled) orders, optionally filtered to ``symbol``."""
+
+    @abstractmethod
+    def cancel_order(self, order_id: str) -> bool:
+        """Cancel a single order. Raises a ``BrokerError`` if the venue refuses."""
+
+    @abstractmethod
+    def cancel_all_orders(self) -> bool:
+        """Cancel all open orders. Raises a ``BrokerError`` if the venue refuses."""
+
+    # --- position lifecycle --------------------------------------------------
+    @abstractmethod
+    def close_position(self, symbol: str) -> bool:
+        """Liquidate the position in ``symbol``. Raises a ``BrokerError`` on failure."""
+
+    @abstractmethod
+    def close_all_positions(self, cancel_orders: bool = True) -> bool:
+        """Liquidate all positions, optionally canceling orders first.
+
+        Raises a ``BrokerError`` on failure - a flatten that quietly did nothing is
+        the worst possible outcome for this call.
+        """
+
+    # --- market clock --------------------------------------------------------
+    @abstractmethod
+    def get_market_status(self) -> Optional[MarketStatus]:
+        """Return the current market clock.
+
+        Raises a :class:`~quantred.brokers.errors.BrokerError` if the clock cannot be
+        read, so a caller can tell "closed" apart from "could not tell".
+        """
+
+    # --- trade-update streaming (optional capability) ------------------------
+    def supports_trade_updates(self) -> bool:
+        """Whether this broker can stream account/order updates. Override if so."""
+        return False
+
+    async def stream_trade_updates(self, handler: TradeUpdateHandler) -> None:
+        """Stream account/order updates to ``handler`` until canceled.
+
+        Optional: only meaningful when :meth:`supports_trade_updates` is True.
+        """
+        raise NotImplementedError("This broker does not support trade-update streaming")

quantred/brokers/dryrun.py

@@ -0,0 +1,164 @@
+"""A broker that can answer questions and cannot trade.
+
+Observing a strategy's decision path used to mean running a paper session, and a paper
+session needed fills to observe — so the book's caps got distorted downward to force
+them. A position ceiling small enough to guarantee fills biases the book toward
+low-priced names and turns every high-price signal into an invisible non-trade, which
+means the sample you collect is not the strategy you validated. Measuring execution
+required trading a book nobody wanted to trade.
+
+This separates the two questions. **What would this contract try to do?** is answered
+here, against a stated account, with the caps exactly as configured. **What does
+execution actually cost?** is a different run at reduced capital, where the real
+contract's proportions are preserved and fills are the point.
+
+**Trading is a capability this broker does not have.** Every order method refuses, and
+that is the whole design rather than a flag consulted on the order path. A flag can be
+forgotten on one branch, read from a stale config, or inverted in a refactor; an absent
+capability cannot be any of those. It is the same guarantee the MCP server gets from
+building only a data client — the wall is structural, so it cannot be reasoned around.
+
+Reads are served from a synthetic account whose capital the caller must state. There is
+deliberately no fallback to a broker's real equity and no default account size: the
+question is what a *specified* contract would do at a *specified* capital, and inventing
+either turns the answer into a guess about a book nobody chose.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from quantred.brokers.base import AccountSnapshot, Broker, MarketStatus, OrderResult, Position
+from quantred.brokers.errors import BrokerError
+
+#: Printed wherever a dry run reports, and deliberately unmissable. A reader who mistakes
+#: this for a paper session mistakes an intention for an execution.
+BANNER = "DRY RUN — broker has no trading capability; no orders can be submitted"
+
+#: Raised by every order method. The message names the mode rather than the method,
+#: because a caller reaching one of these has misunderstood the run, not the API.
+_REFUSAL = (
+    "this is a dry run: the broker has no trading capability, so nothing can be "
+    "submitted, cancelled or closed. Use a small-real session to observe execution"
+)
+
+
+class DryRunTradingAttempted(BrokerError):
+    """Raised wherever a dry run reaches an order path.
+
+    A :class:`~quantred.brokers.errors.BrokerError` on purpose, and the choice is the
+    whole design. ``LiveTrader`` builds its :class:`OrderPlan` *before* submitting
+    precisely so that a broker refusal still records what would have been sent, and
+    returns a decline carrying that plan. So refusing here does not lose the intent —
+    it routes it through machinery the trade clock already has, and the report is
+    assembled from real declines rather than from a parallel path that would have to be
+    kept in step with the real one.
+
+    The alternative was a broker that accepts submissions and records them. That would
+    make "cannot trade" a promise about what this class does with an order rather than
+    about whether it can place one, and the guarantee this mode exists for is the
+    second.
+    """
+
+
+class DryRunBroker(Broker):
+    """Answers account and market questions; refuses every order.
+
+    ``positions`` start empty unless the caller supplies them. A dry run over an
+    existing book and a dry run from flat answer different questions - "what would this
+    do next, given what I hold" against "what would this do from a clean book" - so the
+    source is recorded rather than assumed, and nothing is adopted implicitly.
+    """
+
+    def __init__(
+        self,
+        *,
+        capital: float,
+        positions: Optional[List[Position]] = None,
+        positions_source: str = "flat",
+        tradable: Optional[Dict[str, bool]] = None,
+        market_open: bool = True,
+    ):
+        if capital is None:
+            raise ValueError(
+                "a dry run needs a stated capital: take it from the config being run or "
+                "pass one explicitly. There is no default, because the caps a run reports "
+                "are only meaningful against the capital they bound"
+            )
+        self._capital = float(capital)
+        self._positions = list(positions or [])
+        #: Where the starting book came from, carried into the report so a reader is
+        #: never left guessing whether an empty book was chosen or merely assumed.
+        self.positions_source = positions_source
+        self._tradable = dict(tradable or {})
+        self._market_open = bool(market_open)
+        #: Everything the decision path *would* have sent, in order. Named for what it
+        #: is: these are intentions, and no word here may suggest an execution.
+        self.would_submit: List[Dict[str, Any]] = []
+
+    # ------------------------------------------------------------------ #
+    # Reads — answerable without a venue
+    # ------------------------------------------------------------------ #
+    def get_account(self) -> Optional[AccountSnapshot]:
+        """The stated account, marked at the positions it was given.
+
+        ``buying_power`` is the cash the sizer may deploy, so it is capital less what
+        the supplied positions already reserve - not the capital again, which would let
+        a dry run over an existing book size as though it were flat.
+        """
+        reserved = sum(p.market_value for p in self._positions)
+        return AccountSnapshot(
+            cash=self._capital - reserved,
+            equity=self._capital,
+            buying_power=max(self._capital - reserved, 0.0),
+            portfolio_value=self._capital,
+            trading_blocked=False,
+        )
+
+    def list_positions(self) -> List[Position]:
+        return list(self._positions)
+
+    def get_position(self, symbol: str) -> Optional[Position]:
+        return next((p for p in self._positions if p.symbol == symbol), None)
+
+    def is_tradable(self, symbol: str) -> bool:
+        """Assumed tradable unless the caller said otherwise.
+
+        A dry run cannot ask a venue, and refusing every symbol would report a book that
+        skipped everything for a reason that is an artefact of the mode.
+        """
+        return self._tradable.get(symbol, True)
+
+    def list_open_orders(self, symbol: Optional[str] = None) -> List[OrderResult]:
+        """Always empty. Nothing was submitted, so nothing can be resting."""
+        return []
+
+    def get_market_status(self) -> Optional[MarketStatus]:
+        return MarketStatus(is_open=self._market_open)
+
+    def supports_trade_updates(self) -> bool:
+        """No. There are no fills to stream, and saying otherwise would have a caller
+        wait on updates that can never arrive."""
+        return False
+
+    # ------------------------------------------------------------------ #
+    # Orders — the capability this broker does not have
+    # ------------------------------------------------------------------ #
+    def submit_market_order(self, *args: Any, **kwargs: Any) -> OrderResult:
+        raise DryRunTradingAttempted(_REFUSAL)
+
+    def submit_bracket_order(self, *args: Any, **kwargs: Any) -> OrderResult:
+        raise DryRunTradingAttempted(_REFUSAL)
+
+    def cancel_order(self, order_id: str) -> bool:
+        raise DryRunTradingAttempted(_REFUSAL)
+
+    def cancel_all_orders(self) -> bool:
+        raise DryRunTradingAttempted(_REFUSAL)
+
+    def close_position(self, symbol: str) -> bool:
+        raise DryRunTradingAttempted(_REFUSAL)
+
+    def close_all_positions(self, cancel_orders: bool = True) -> bool:
+        raise DryRunTradingAttempted(_REFUSAL)
+
+    async def stream_trade_updates(self, handler: Any) -> None:
+        raise DryRunTradingAttempted(_REFUSAL)

quantred/brokers/errors.py

@@ -0,0 +1,70 @@
+"""Broker failure, typed.
+
+Every broker call used to fail the same way: ``None``, or ``False``. A rate limit, an
+expired token, insufficient buying power, a market that is closed, and an order the
+venue deliberately refused all arrived as the same absence of information, so the only
+possible response was the same one - log it and move on. That is the wrong response to
+most of them, and for a duplicate order it is actively misleading: the order *was*
+placed.
+
+The distinctions that matter are the ones a caller would act on differently:
+
+* :class:`RateLimitedError` - back off; the request was fine.
+* :class:`AuthenticationError` - nothing will work until a human fixes credentials.
+  Never transient, so never worth retrying or trading through.
+* :class:`InsufficientFundsError` - the account cannot support this size.
+* :class:`MarketClosedError` - correct request, wrong time.
+* :class:`DuplicateOrderError` - the venue already has this order. Not a failure.
+* :class:`OrderRejectedError` - the venue refused it on its own terms.
+* :class:`BrokerUnavailableError` - the venue could not be reached at all. Transient
+  by nature, and the only one where carrying on optimistically is defensible.
+
+Vendor-neutral by design: these live beside the :class:`~quantred.brokers.base.Broker`
+interface, so a caller that handles them handles every venue.
+"""
+
+
+class BrokerError(RuntimeError):
+    """Base class for every broker failure."""
+
+
+class BrokerUnavailableError(BrokerError):
+    """The venue could not be reached (network failure, timeout, 5xx)."""
+
+
+class RateLimitedError(BrokerError):
+    """The venue is throttling us. The request itself was acceptable."""
+
+
+class AuthenticationError(BrokerError):
+    """Credentials are missing, expired, or insufficient for this operation.
+
+    Distinguished from :class:`BrokerUnavailableError` because it is never transient:
+    retrying cannot fix it, and continuing to trade on the assumption that things are
+    fine is worse than stopping.
+    """
+
+
+class InsufficientFundsError(BrokerError):
+    """Buying power or position size cannot support the request."""
+
+
+class MarketClosedError(BrokerError):
+    """The venue rejected the order because the market is not open."""
+
+
+class OrderRejectedError(BrokerError):
+    """The venue refused the order on validation or compliance grounds."""
+
+
+class DuplicateOrderError(BrokerError):
+    """This client order id has already been accepted.
+
+    Raised rather than returned because it interrupts the caller's flow - but it
+    reports a *success*: the order exists at the venue. A caller must not treat it as
+    a failed submission and must not resubmit.
+    """
+
+
+class NotTradableError(BrokerError):
+    """The symbol cannot be traded on this venue right now."""