desic-okx-agent 0.2.1 → 0.3.1

package/python/desic_strategy/engine.py

@@ -0,0 +1,614 @@
+"""The backtest event loop.
+
+Execution timing is the core contract: a decision is made at a confirmed
+one-minute close and a market action fills at the *following* bar's open. A
+limit action becomes a pending order at that open and is matched against later
+bars using a deliberately conservative K-line estimate.
+
+There is no historical order-book queue here, so a fill is never a promise
+about real exchange latency, queue position, or liquidity.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .actions import (
+    CANCEL_ORDER,
+    CLOSE_LONG,
+    CLOSE_SHORT,
+    LIMIT,
+    NO_ACTION,
+    OPEN_LONG,
+    OPEN_SHORT,
+    Decision,
+    StrategyError,
+)
+from .context import MarketView, SeriesSet, StrategyContext, immutable_params
+from .indicators import IndicatorView
+from .portfolio import (
+    LONG,
+    SHORT,
+    AccountState,
+    Fill,
+    MutablePosition,
+    OpenOrder,
+    PortfolioView,
+    Position,
+    Trade,
+)
+from .timeframe import Bar
+
+# A limit order may take at most this share of a bar's volume. Assuming more
+# would let a backtest fill size the live book could not absorb.
+BAR_VOLUME_FILL_CAP = 0.10
+
+
+@dataclass(frozen=True)
+class Instrument:
+    """Contract specification, as reported by the exchange.
+
+    ``contract_value`` is base currency per contract and ``contract_multiplier``
+    scales it. Both are needed: OKX reports them separately, and folding the
+    multiplier into the value would hide a mismatch when only one changes.
+    """
+
+    inst_id: str
+    contract_value: float
+    lot_size: float
+    min_size: float
+    tick_size: float
+    contract_multiplier: float = 1.0
+
+    @property
+    def base_per_contract(self) -> float:
+        """Base-currency units one contract represents."""
+        return self.contract_value * self.contract_multiplier
+
+
+@dataclass(frozen=True)
+class Costs:
+    taker_fee_rate: float = 0.0005
+    maker_fee_rate: float = 0.0002
+    entry_slippage_bps: float = 1.0
+    exit_slippage_bps: float = 1.0
+
+
+@dataclass(frozen=True)
+class Sizing:
+    """Host-owned position sizing. A strategy cannot influence these."""
+
+    leverage: float = 10.0
+    margin_safety_multiplier: float = 1.0
+    entry_budget_usdt: float | None = None
+    entry_budget_pct: float = 0.20
+
+
+@dataclass(frozen=True)
+class RunConfig:
+    instrument: Instrument
+    initial_equity_usdt: float = 10_000.0
+    costs: Costs = field(default_factory=Costs)
+    sizing: Sizing = field(default_factory=Sizing)
+    preload_bars: int = 2
+    close_at_end: bool = True
+    limit_order_ttl_bars: int = 60
+
+
+@dataclass
+class EquityPoint:
+    time_ms: int
+    equity_usdt: float
+    realized_cash_usdt: float
+    unrealized_pnl_usdt: float
+
+
+@dataclass
+class PendingAction:
+    decision: Decision
+    submitted_at_ms: int
+
+
+@dataclass
+class RunResult:
+    status: str
+    equity_curve: list[EquityPoint]
+    fills: list[Fill]
+    trades: list[Trade]
+    actions: list[dict[str, object]]
+    evaluation_bars: int
+    exposed_bars: int
+    margin_exhausted: bool
+
+
+class Engine:
+    """Drives one strategy over one contiguous confirmed one-minute window."""
+
+    def __init__(self, config: RunConfig, handlers: dict[str, object], params: dict[str, object]) -> None:
+        self._config = config
+        self._handlers = handlers
+        self._params = immutable_params(params)
+        self._state = AccountState(cash_usdt=config.initial_equity_usdt)
+        self._sequence = 0
+        self._margin_exhausted = False
+
+    def run(
+        self,
+        bars: list[Bar],
+        intervals: list[str],
+        on_progress: object = None,
+    ) -> RunResult:
+        config = self._config
+        instrument = config.instrument
+        preload = config.preload_bars
+        if len(bars) <= preload:
+            raise StrategyError("The window must contain at least one evaluation bar after preload")
+
+        series = SeriesSet(instrument.inst_id, intervals)
+        equity_curve: list[EquityPoint] = []
+        actions_log: list[dict[str, object]] = []
+        pending: PendingAction | None = None
+        started = False
+        exposed_bars = 0
+        evaluation_bars = 0
+
+        for index, bar in enumerate(bars):
+            series.push(bar)
+            is_evaluation = index >= preload
+
+            if is_evaluation:
+                # A decision from the previous close acts at this open, before
+                # anything else can observe the resulting position.
+                if pending is not None:
+                    self._apply_at_open(pending, bar)
+                    pending = None
+                self._match_open_orders(bar)
+                self._apply_protective_exit(bar)
+                self._enforce_margin(bar)
+
+                unrealized = self._unrealized(bar.close)
+                equity_curve.append(
+                    EquityPoint(
+                        time_ms=bar.close_time_ms,
+                        equity_usdt=self._state.cash_usdt + unrealized,
+                        realized_cash_usdt=self._state.cash_usdt,
+                        unrealized_pnl_usdt=unrealized,
+                    )
+                )
+                evaluation_bars += 1
+                if self._state.position is not None:
+                    exposed_bars += 1
+
+            # The final preloaded bar closes exactly at the evaluation start, so
+            # it supplies the first decision context while staying out of every
+            # reported statistic.
+            if not (is_evaluation or index + 1 == preload):
+                continue
+
+            context = self._context(bar, index + 1, bars, series)
+            if not started:
+                started = True
+                start_handler = self._handlers.get("on_start")
+                if callable(start_handler):
+                    decision = start_handler(context)
+                    self._require_no_action(decision)
+
+            handler = self._handlers.get("on_bar")
+            if not callable(handler):
+                raise StrategyError("A strategy must define on_bar(ctx)")
+            decision = handler(context)
+            decision = self._validate(decision)
+            if decision.action != NO_ACTION:
+                actions_log.append({"asOfMs": bar.close_time_ms, **decision.as_dict()})
+                if decision.action == CANCEL_ORDER:
+                    self._cancel_order(decision.order_id)
+                else:
+                    pending = PendingAction(decision, bar.close_time_ms)
+
+            if callable(on_progress) and (index + 1) % 512 == 0:
+                on_progress(index + 1, len(bars))
+
+        last_bar = bars[-1]
+        if config.close_at_end and self._state.position is not None:
+            self._close_position(last_bar.close_time_ms, self._exit_price(last_bar.close, self._state.position.side), "end_of_run")
+            if equity_curve:
+                equity_curve[-1].equity_usdt = self._state.cash_usdt
+                equity_curve[-1].realized_cash_usdt = self._state.cash_usdt
+                equity_curve[-1].unrealized_pnl_usdt = 0.0
+                # The forced close makes the final bar flat, so it no longer
+                # counts toward exposure.
+                exposed_bars = max(0, exposed_bars - 1)
+
+        if callable(on_progress):
+            on_progress(len(bars), len(bars))
+        return RunResult(
+            status="completed",
+            equity_curve=equity_curve,
+            fills=list(self._state.fills),
+            trades=list(self._state.trades),
+            actions=actions_log,
+            evaluation_bars=evaluation_bars,
+            exposed_bars=exposed_bars,
+            margin_exhausted=self._margin_exhausted,
+        )
+
+    # ----- context construction -------------------------------------------
+
+    def _context(self, bar: Bar, visible: int, bars: list[Bar], series: SeriesSet) -> StrategyContext:
+        instrument = self._config.instrument
+        market = MarketView(instrument.inst_id, bars, visible, series.snapshot())
+        return StrategyContext(
+            kind="bar",
+            as_of_ms=bar.close_time_ms,
+            instrument_id=instrument.inst_id,
+            interval="1m",
+            bar=bar,
+            market=market,
+            portfolio=self._portfolio_view(bar.close),
+            params=self._params,
+            indicators=IndicatorView(series.indicators, instrument.inst_id, visible),
+        )
+
+    def _portfolio_view(self, mark_price: float) -> PortfolioView:
+        instrument = self._config.instrument
+        state = self._state
+        positions: tuple[Position, ...] = ()
+        if state.position is not None:
+            item = state.position
+            positions = (
+                Position(
+                    instrumentId=instrument.inst_id,
+                    side=item.side,
+                    quantity=item.quantity,
+                    averageEntryPrice=item.average_entry_price,
+                    markPrice=mark_price,
+                    contractValue=instrument.contract_value,
+                    notionalUsdt=item.notional(mark_price, instrument.base_per_contract),
+                    usedMarginUsdt=item.used_margin_usdt,
+                    leverage=item.leverage,
+                    marginSafetyMultiplier=item.margin_safety_multiplier,
+                    unrealizedPnlUsdt=item.unrealized(mark_price, instrument.base_per_contract),
+                    entryFeeUsdt=item.entry_fee_usdt,
+                    stopLossPrice=item.stop_loss_price,
+                    takeProfitPrice=item.take_profit_price,
+                    openedAtMs=item.opened_at_ms,
+                    updatedAtMs=item.updated_at_ms,
+                ),
+            )
+        equity = state.equity(mark_price, instrument.base_per_contract)
+        return PortfolioView(
+            cash_usdt=state.cash_usdt,
+            equity_usdt=equity,
+            used_margin_usdt=state.used_margin_usdt,
+            available_margin_usdt=max(0.0, equity - state.used_margin_usdt),
+            positions=positions,
+            open_orders=tuple(state.open_orders),
+            recent_fills=tuple(state.fills[-50:]),
+            trades=tuple(state.trades),
+        )
+
+    # ----- decision handling ----------------------------------------------
+
+    def _validate(self, decision: object) -> Decision:
+        if not isinstance(decision, Decision):
+            raise StrategyError(
+                "A handler must return one of ctx.no_action, ctx.open_long, ctx.open_short, "
+                "ctx.close_long, ctx.close_short, or ctx.cancel_order"
+            )
+        if decision.action == CANCEL_ORDER:
+            known = {order.id for order in self._state.open_orders}
+            if decision.order_id not in known:
+                raise StrategyError(
+                    f"cancel_order references '{decision.order_id}', which is not a current open order"
+                )
+        return decision
+
+    def _require_no_action(self, decision: object) -> None:
+        if not isinstance(decision, Decision) or decision.action != NO_ACTION:
+            raise StrategyError("on_start must return ctx.no_action(...)")
+
+    def _apply_at_open(self, pending: PendingAction, bar: Bar) -> None:
+        decision = pending.decision
+        if decision.execution.order_type == LIMIT:
+            self._register_limit_order(decision, bar)
+            return
+        if decision.action in (OPEN_LONG, OPEN_SHORT):
+            side = LONG if decision.action == OPEN_LONG else SHORT
+            self._open(side, self._entry_price(bar.open, side), bar.close_time_ms, decision, taker=True)
+        elif decision.action in (CLOSE_LONG, CLOSE_SHORT):
+            side = LONG if decision.action == CLOSE_LONG else SHORT
+            if self._state.position is not None and self._state.position.side == side:
+                self._close_position(bar.close_time_ms, self._exit_price(bar.open, side), "strategy_close")
+
+    def _register_limit_order(self, decision: Decision, bar: Bar) -> None:
+        quantity = (
+            self._entry_quantity(bar.open)
+            if decision.action in (OPEN_LONG, OPEN_SHORT)
+            else (self._state.position.quantity if self._state.position else 0.0)
+        )
+        if quantity <= 0:
+            return
+        self._sequence += 1
+        self._state.open_orders.append(
+            OpenOrder(
+                id=f"ord-{self._sequence}",
+                instrumentId=self._config.instrument.inst_id,
+                action=decision.action,
+                quantity=quantity,
+                filledQuantity=0.0,
+                status="open",
+                price=decision.execution.limit_price,
+                createdAtMs=bar.open_time_ms,
+            )
+        )
+
+    def _cancel_order(self, order_id: str | None) -> None:
+        self._state.open_orders = [order for order in self._state.open_orders if order.id != order_id]
+
+    def _match_open_orders(self, bar: Bar) -> None:
+        """Conservative K-line matching.
+
+        A buy requires the bar to trade strictly below its limit and a sell
+        strictly above, and any single bar can absorb at most
+        ``BAR_VOLUME_FILL_CAP`` of its own volume.
+        """
+        if not self._state.open_orders:
+            return
+        remaining: list[OpenOrder] = []
+        for order in self._state.open_orders:
+            price = order.price
+            if price is None:
+                remaining.append(order)
+                continue
+            buying = order.action in (OPEN_LONG, CLOSE_SHORT)
+            reached = bar.low < price if buying else bar.high > price
+            expired = bar.open_time_ms - order.createdAtMs >= self._config.limit_order_ttl_bars * 60_000
+            if not reached:
+                if not expired:
+                    remaining.append(order)
+                continue
+            capacity = bar.volume * BAR_VOLUME_FILL_CAP
+            fillable = min(order.quantity - order.filledQuantity, max(0.0, capacity))
+            fillable = self._align_lot(fillable)
+            if fillable <= 0:
+                if not expired:
+                    remaining.append(order)
+                continue
+            if order.action in (OPEN_LONG, OPEN_SHORT):
+                side = LONG if order.action == OPEN_LONG else SHORT
+                self._open_quantity(side, price, bar.close_time_ms, fillable, None, taker=False)
+            else:
+                side = LONG if order.action == CLOSE_LONG else SHORT
+                if self._state.position is not None and self._state.position.side == side:
+                    self._reduce_position(bar.close_time_ms, price, fillable, "strategy_close", taker=False)
+            filled = order.filledQuantity + fillable
+            if filled < order.quantity and not expired:
+                remaining.append(
+                    OpenOrder(
+                        id=order.id,
+                        instrumentId=order.instrumentId,
+                        action=order.action,
+                        quantity=order.quantity,
+                        filledQuantity=filled,
+                        status="partially_filled",
+                        price=order.price,
+                        createdAtMs=order.createdAtMs,
+                    )
+                )
+        self._state.open_orders = remaining
+
+    # ----- position mechanics ---------------------------------------------
+
+    def _entry_quantity(self, price: float) -> float:
+        instrument = self._config.instrument
+        sizing = self._config.sizing
+        equity = self._state.equity(price, instrument.base_per_contract)
+        budget = sizing.entry_budget_usdt or equity * sizing.entry_budget_pct
+        budget = min(budget, max(0.0, equity - self._state.used_margin_usdt))
+        if budget <= 0:
+            return 0.0
+        notional = budget * sizing.leverage / sizing.margin_safety_multiplier
+        quantity = notional / (price * instrument.base_per_contract)
+        return self._align_lot(quantity)
+
+    def _align_lot(self, quantity: float) -> float:
+        instrument = self._config.instrument
+        if instrument.lot_size <= 0:
+            return max(0.0, quantity)
+        steps = int(quantity / instrument.lot_size + 1e-9)
+        aligned = steps * instrument.lot_size
+        if aligned < instrument.min_size:
+            return 0.0
+        return aligned
+
+    def _open(self, side: str, price: float, now_ms: int, decision: Decision, taker: bool) -> None:
+        quantity = self._entry_quantity(price)
+        if quantity <= 0:
+            return
+        self._open_quantity(side, price, now_ms, quantity, decision, taker=taker)
+
+    def _open_quantity(
+        self,
+        side: str,
+        price: float,
+        now_ms: int,
+        quantity: float,
+        decision: Decision | None,
+        taker: bool,
+    ) -> None:
+        instrument = self._config.instrument
+        sizing = self._config.sizing
+        existing = self._state.position
+        if existing is not None and existing.side != side:
+            # Reversal is explicit: a strategy must close before opening the
+            # opposite side, so this is a contract violation, not a flip.
+            raise StrategyError(
+                f"Cannot open {side} while a {existing.side} position is open; close it first"
+            )
+        notional = quantity * instrument.base_per_contract * price
+        margin = notional / sizing.leverage * sizing.margin_safety_multiplier
+        fee = notional * (self._config.costs.taker_fee_rate if taker else self._config.costs.maker_fee_rate)
+        if margin > max(0.0, self._state.equity(price, instrument.base_per_contract) - self._state.used_margin_usdt):
+            return
+        self._state.cash_usdt -= fee
+        self._state.used_margin_usdt += margin
+        protection = decision.protection if decision is not None else None
+        if existing is None:
+            self._state.position = MutablePosition(
+                side=side,
+                quantity=quantity,
+                average_entry_price=price,
+                used_margin_usdt=margin,
+                leverage=sizing.leverage,
+                margin_safety_multiplier=sizing.margin_safety_multiplier,
+                entry_fee_usdt=fee,
+                stop_loss_price=protection.stop_loss_price if protection else None,
+                take_profit_price=protection.take_profit_price if protection else None,
+                opened_at_ms=now_ms,
+                updated_at_ms=now_ms,
+            )
+        else:
+            total = existing.quantity + quantity
+            existing.average_entry_price = (
+                existing.average_entry_price * existing.quantity + price * quantity
+            ) / total
+            existing.quantity = total
+            existing.used_margin_usdt += margin
+            existing.entry_fee_usdt += fee
+            existing.updated_at_ms = now_ms
+        self._record_fill(
+            action=OPEN_LONG if side == LONG else OPEN_SHORT,
+            quantity=quantity,
+            price=price,
+            fee=fee,
+            now_ms=now_ms,
+        )
+
+    def _reduce_position(
+        self,
+        now_ms: int,
+        price: float,
+        quantity: float,
+        reason: str,
+        taker: bool = True,
+    ) -> None:
+        position = self._state.position
+        if position is None:
+            return
+        instrument = self._config.instrument
+        quantity = min(quantity, position.quantity)
+        if quantity <= 0:
+            return
+        notional = quantity * instrument.base_per_contract * price
+        fee = notional * (self._config.costs.taker_fee_rate if taker else self._config.costs.maker_fee_rate)
+        delta = price - position.average_entry_price
+        if position.side == SHORT:
+            delta = -delta
+        realized = delta * quantity * instrument.base_per_contract
+        share = quantity / position.quantity
+        released = position.used_margin_usdt * share
+
+        self._state.cash_usdt += realized - fee
+        self._state.used_margin_usdt = max(0.0, self._state.used_margin_usdt - released)
+        self._record_fill(
+            action=CLOSE_LONG if position.side == LONG else CLOSE_SHORT,
+            quantity=quantity,
+            price=price,
+            fee=fee,
+            now_ms=now_ms,
+        )
+        self._sequence += 1
+        self._state.trades.append(
+            Trade(
+                id=f"trade-{self._sequence}",
+                instrumentId=instrument.inst_id,
+                side=position.side,
+                quantity=quantity,
+                entryPrice=position.average_entry_price,
+                exitPrice=price,
+                usedMarginUsdt=released,
+                leverage=position.leverage,
+                realizedPnlUsdt=realized,
+                feesUsdt=fee + position.entry_fee_usdt * share,
+                openedAtMs=position.opened_at_ms,
+                closedAtMs=now_ms,
+            )
+        )
+        position.quantity -= quantity
+        position.used_margin_usdt -= released
+        position.entry_fee_usdt *= 1 - share
+        position.updated_at_ms = now_ms
+        if position.quantity <= 1e-12:
+            self._state.position = None
+            # A full close removes attached protection automatically.
+            self._state.open_orders = [
+                order for order in self._state.open_orders if order.action in (OPEN_LONG, OPEN_SHORT)
+            ]
+
+    def _close_position(self, now_ms: int, price: float, reason: str) -> None:
+        position = self._state.position
+        if position is None:
+            return
+        self._reduce_position(now_ms, price, position.quantity, reason)
+
+    def _apply_protective_exit(self, bar: Bar) -> None:
+        position = self._state.position
+        if position is None:
+            return
+        stop = position.stop_loss_price
+        take = position.take_profit_price
+        if position.side == LONG:
+            # When both could trigger inside one bar, assume the adverse one:
+            # intrabar order is unknowable from OHLC alone.
+            if stop is not None and bar.low <= stop:
+                self._close_position(bar.close_time_ms, stop, "stop_loss")
+                return
+            if take is not None and bar.high >= take:
+                self._close_position(bar.close_time_ms, take, "take_profit")
+        else:
+            if stop is not None and bar.high >= stop:
+                self._close_position(bar.close_time_ms, stop, "stop_loss")
+                return
+            if take is not None and bar.low <= take:
+                self._close_position(bar.close_time_ms, take, "take_profit")
+
+    def _enforce_margin(self, bar: Bar) -> None:
+        position = self._state.position
+        if position is None:
+            return
+        instrument = self._config.instrument
+        adverse = bar.low if position.side == LONG else bar.high
+        equity = self._state.cash_usdt + position.unrealized(adverse, instrument.base_per_contract)
+        if equity <= 0:
+            self._margin_exhausted = True
+            self._close_position(bar.close_time_ms, adverse, "margin_exhaustion")
+
+    def _record_fill(self, action: str, quantity: float, price: float, fee: float, now_ms: int) -> None:
+        instrument = self._config.instrument
+        self._sequence += 1
+        self._state.fills.append(
+            Fill(
+                id=f"fill-{self._sequence}",
+                orderId=f"ord-{self._sequence}",
+                instrumentId=instrument.inst_id,
+                action=action,
+                quantity=quantity,
+                price=price,
+                notionalUsdt=quantity * instrument.base_per_contract * price,
+                feeUsdt=fee,
+                filledAtMs=now_ms,
+            )
+        )
+
+    def _entry_price(self, price: float, side: str) -> float:
+        slip = self._config.costs.entry_slippage_bps / 10_000
+        return price * (1 + slip) if side == LONG else price * (1 - slip)
+
+    def _exit_price(self, price: float, side: str) -> float:
+        slip = self._config.costs.exit_slippage_bps / 10_000
+        return price * (1 - slip) if side == LONG else price * (1 + slip)
+
+    def _unrealized(self, mark_price: float) -> float:
+        if self._state.position is None:
+            return 0.0
+        return self._state.position.unrealized(mark_price, self._config.instrument.base_per_contract)