desic-okx-agent 0.2.0 → 0.3.0

package/python/desic_strategy/portfolio.py

@@ -0,0 +1,152 @@
+"""Virtual account state for a backtest.
+
+Margin is a deliberately conservative research boundary, not an exchange
+liquidation model: opening reserves ``notional / leverage * safety_multiplier``
+from equity. When an adverse move exhausts that collateral the engine closes at
+the conservative available price and records ``margin_exhaustion``. It must
+never be read as an OKX liquidation estimate.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+
+LONG = "long"
+SHORT = "short"
+
+
+@dataclass(frozen=True)
+class Position:
+    instrumentId: str  # noqa: N815 - protocol field name
+    side: str
+    quantity: float
+    averageEntryPrice: float  # noqa: N815
+    markPrice: float  # noqa: N815
+    contractValue: float  # noqa: N815
+    notionalUsdt: float  # noqa: N815
+    usedMarginUsdt: float  # noqa: N815
+    leverage: float
+    marginSafetyMultiplier: float  # noqa: N815
+    unrealizedPnlUsdt: float  # noqa: N815
+    entryFeeUsdt: float  # noqa: N815
+    stopLossPrice: float | None  # noqa: N815
+    takeProfitPrice: float | None  # noqa: N815
+    openedAtMs: int  # noqa: N815
+    updatedAtMs: int  # noqa: N815
+
+
+@dataclass(frozen=True)
+class OpenOrder:
+    id: str
+    instrumentId: str  # noqa: N815
+    action: str
+    quantity: float
+    filledQuantity: float  # noqa: N815
+    status: str
+    price: float | None
+    createdAtMs: int  # noqa: N815
+
+
+@dataclass(frozen=True)
+class Fill:
+    id: str
+    orderId: str  # noqa: N815
+    instrumentId: str  # noqa: N815
+    action: str
+    quantity: float
+    price: float
+    notionalUsdt: float  # noqa: N815
+    feeUsdt: float  # noqa: N815
+    filledAtMs: int  # noqa: N815
+
+
+@dataclass(frozen=True)
+class Trade:
+    id: str
+    instrumentId: str  # noqa: N815
+    side: str
+    quantity: float
+    entryPrice: float  # noqa: N815
+    exitPrice: float  # noqa: N815
+    usedMarginUsdt: float  # noqa: N815
+    leverage: float
+    realizedPnlUsdt: float  # noqa: N815
+    feesUsdt: float  # noqa: N815
+    openedAtMs: int  # noqa: N815
+    closedAtMs: int  # noqa: N815
+
+
+@dataclass(frozen=True)
+class PortfolioView:
+    """Immutable point-in-time account snapshot handed to strategy code."""
+
+    cash_usdt: float
+    equity_usdt: float
+    used_margin_usdt: float
+    available_margin_usdt: float
+    positions: tuple[Position, ...] = ()
+    open_orders: tuple[OpenOrder, ...] = ()
+    recent_fills: tuple[Fill, ...] = ()
+    trades: tuple[Trade, ...] = ()
+
+    def position(self, instrument_id: str, side: str) -> Position | None:
+        """The open position for one side, or ``None`` when flat.
+
+        This is a method taking both arguments, never a bare ``position``
+        property; sizing and side are always explicit.
+        """
+        if side not in (LONG, SHORT):
+            raise ValueError(f"side must be '{LONG}' or '{SHORT}', received {side!r}")
+        for item in self.positions:
+            if item.instrumentId == instrument_id and item.side == side:
+                return item
+        return None
+
+    def positions_for(self, instrument_id: str) -> tuple[Position, ...]:
+        return tuple(item for item in self.positions if item.instrumentId == instrument_id)
+
+
+@dataclass
+class MutablePosition:
+    """Engine-internal position. Strategy code never sees this type."""
+
+    side: str
+    quantity: float
+    average_entry_price: float
+    used_margin_usdt: float
+    leverage: float
+    margin_safety_multiplier: float
+    entry_fee_usdt: float
+    stop_loss_price: float | None
+    take_profit_price: float | None
+    opened_at_ms: int
+    updated_at_ms: int
+
+    def notional(self, price: float, contract_value: float) -> float:
+        return self.quantity * contract_value * price
+
+    def unrealized(self, mark_price: float, contract_value: float) -> float:
+        delta = mark_price - self.average_entry_price
+        if self.side == SHORT:
+            delta = -delta
+        return delta * self.quantity * contract_value
+
+    def with_updated_time(self, now_ms: int) -> "MutablePosition":
+        return replace(self, updated_at_ms=now_ms)
+
+
+@dataclass
+class AccountState:
+    """Engine-internal ledger accumulated across a run."""
+
+    cash_usdt: float
+    position: MutablePosition | None = None
+    open_orders: list[OpenOrder] = field(default_factory=list)
+    fills: list[Fill] = field(default_factory=list)
+    trades: list[Trade] = field(default_factory=list)
+    used_margin_usdt: float = 0.0
+
+    def equity(self, mark_price: float, contract_value: float) -> float:
+        if self.position is None:
+            return self.cash_usdt
+        return self.cash_usdt + self.position.unrealized(mark_price, contract_value)

package/python/desic_strategy/report.py

@@ -0,0 +1,319 @@
+"""Backtest metrics and the serialized report."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from .engine import RunResult
+from .portfolio import LONG
+
+MINUTES_PER_YEAR = 365 * 24 * 60
+
+# Annualizing a very short window produces a meaningless figure, so it is capped
+# rather than reported verbatim.
+ANNUALIZED_RETURN_CAP_PCT = 1_000_000.0
+# Above this, `math.exp` overflows; the cap already applies well before it.
+_MAX_GROWTH_EXPONENT = 100.0
+# Annualized figures below this window length are withheld rather than shown.
+# A five-day run extrapolates to five-digit percentages that read as precision
+# but carry none, and any ratio built on them inherits that noise.
+MINIMUM_ANNUALIZATION_DAYS = 30
+
+
+@dataclass(frozen=True)
+class Metrics:
+    initial_equity_usdt: float
+    final_equity_usdt: float
+    net_profit_usdt: float
+    return_pct: float
+    max_drawdown_pct: float
+    max_drawdown_usdt: float
+    max_drawdown_at_ms: int | None
+    longest_drawdown_bars: int
+    calmar: float | None
+    annualized_return_pct: float | None
+    annualization_reliable: bool
+    sharpe: float | None
+    sortino: float | None
+    trade_count: int
+    long_trade_count: int
+    short_trade_count: int
+    win_rate_pct: float | None
+    profit_factor: float | None
+    expectancy_usdt: float | None
+    average_win_usdt: float | None
+    average_loss_usdt: float | None
+    largest_win_usdt: float | None
+    largest_loss_usdt: float | None
+    average_holding_bars: float | None
+    max_consecutive_wins: int
+    max_consecutive_losses: int
+    total_fees_usdt: float
+    fees_pct_of_gross: float | None
+    turnover_usdt: float
+    exposure_pct: float
+    evaluation_bars: int
+    evaluation_days: float
+    trades_per_day: float | None
+    margin_exhausted: bool
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "initialEquityUsdt": _round(self.initial_equity_usdt),
+            "finalEquityUsdt": _round(self.final_equity_usdt),
+            "netProfitUsdt": _round(self.net_profit_usdt),
+            "returnPct": _round(self.return_pct),
+            "maxDrawdownPct": _round(self.max_drawdown_pct),
+            "maxDrawdownUsdt": _round(self.max_drawdown_usdt),
+            "maxDrawdownAtMs": self.max_drawdown_at_ms,
+            "longestDrawdownBars": self.longest_drawdown_bars,
+            "calmar": _optional(self.calmar),
+            "annualizedReturnPct": _optional(self.annualized_return_pct),
+            "annualizationReliable": self.annualization_reliable,
+            "sharpe": _optional(self.sharpe),
+            "sortino": _optional(self.sortino),
+            "tradeCount": self.trade_count,
+            "longTradeCount": self.long_trade_count,
+            "shortTradeCount": self.short_trade_count,
+            "winRatePct": _optional(self.win_rate_pct),
+            "profitFactor": _optional(self.profit_factor),
+            "expectancyUsdt": _optional(self.expectancy_usdt),
+            "averageWinUsdt": _optional(self.average_win_usdt),
+            "averageLossUsdt": _optional(self.average_loss_usdt),
+            "largestWinUsdt": _optional(self.largest_win_usdt),
+            "largestLossUsdt": _optional(self.largest_loss_usdt),
+            "averageHoldingBars": _optional(self.average_holding_bars),
+            "maxConsecutiveWins": self.max_consecutive_wins,
+            "maxConsecutiveLosses": self.max_consecutive_losses,
+            "totalFeesUsdt": _round(self.total_fees_usdt),
+            "feesPctOfGross": _optional(self.fees_pct_of_gross),
+            "turnoverUsdt": _round(self.turnover_usdt),
+            "exposurePct": _round(self.exposure_pct),
+            "evaluationBars": self.evaluation_bars,
+            "evaluationDays": _round(self.evaluation_days),
+            "tradesPerDay": _optional(self.trades_per_day),
+            "marginExhausted": self.margin_exhausted,
+        }
+
+
+def calculate_metrics(result: RunResult, initial_equity_usdt: float) -> Metrics:
+    curve = result.equity_curve
+    final_equity = curve[-1].equity_usdt if curve else initial_equity_usdt
+    return_pct = (
+        0.0 if initial_equity_usdt <= 0 else (final_equity / initial_equity_usdt - 1) * 100
+    )
+
+    peak = initial_equity_usdt
+    max_drawdown = 0.0
+    max_drawdown_usdt = 0.0
+    max_drawdown_at: int | None = None
+    longest_drawdown = 0
+    current_drawdown = 0
+    for point in curve:
+        if point.equity_usdt >= peak:
+            peak = point.equity_usdt
+            current_drawdown = 0
+        else:
+            current_drawdown += 1
+            longest_drawdown = max(longest_drawdown, current_drawdown)
+        if peak > 0:
+            depth_pct = (peak - point.equity_usdt) / peak * 100
+            if depth_pct > max_drawdown:
+                max_drawdown = depth_pct
+                max_drawdown_usdt = peak - point.equity_usdt
+                max_drawdown_at = point.time_ms
+
+    evaluation_days = result.evaluation_bars / 1_440
+    annualized = _annualized_return(initial_equity_usdt, final_equity, result.evaluation_bars)
+    reliable = evaluation_days >= MINIMUM_ANNUALIZATION_DAYS
+    # Calmar divides an annualized figure by drawdown, so it inherits the
+    # extrapolation error. On a five-day window it reads in the tens of
+    # thousands, which looks like precision and is noise; withhold both.
+    calmar = None
+    if reliable and annualized is not None and max_drawdown > 0:
+        calmar = annualized / max_drawdown
+
+    # Trade PnL is measured net of fees. Using gross PnL here would report a
+    # profit factor above 1 for a strategy whose equity actually fell, because
+    # fees on a high-turnover run can exceed the gross edge entirely.
+    net_pnls = [trade.realizedPnlUsdt - trade.feesUsdt for trade in result.trades]
+    wins = [value for value in net_pnls if value > 0]
+    losses = [value for value in net_pnls if value < 0]
+    gross_win = sum(wins)
+    gross_loss = abs(sum(losses))
+    total_fees = sum(fill.feeUsdt for fill in result.fills)
+    gross_pnl = sum(trade.realizedPnlUsdt for trade in result.trades)
+    holding = [
+        (trade.closedAtMs - trade.openedAtMs) / 60_000
+        for trade in result.trades
+        if trade.closedAtMs > trade.openedAtMs
+    ]
+    wins_streak, losses_streak = _streaks(net_pnls)
+
+    return Metrics(
+        initial_equity_usdt=initial_equity_usdt,
+        final_equity_usdt=final_equity,
+        net_profit_usdt=final_equity - initial_equity_usdt,
+        return_pct=return_pct,
+        max_drawdown_pct=max_drawdown,
+        max_drawdown_usdt=max_drawdown_usdt,
+        max_drawdown_at_ms=max_drawdown_at,
+        longest_drawdown_bars=longest_drawdown,
+        calmar=calmar,
+        annualized_return_pct=annualized if reliable else None,
+        annualization_reliable=reliable,
+        sharpe=_sharpe(curve, downside_only=False),
+        sortino=_sharpe(curve, downside_only=True),
+        trade_count=len(result.trades),
+        long_trade_count=sum(1 for trade in result.trades if trade.side == LONG),
+        short_trade_count=sum(1 for trade in result.trades if trade.side != LONG),
+        win_rate_pct=None if not net_pnls else len(wins) / len(net_pnls) * 100,
+        profit_factor=None if gross_loss <= 0 else gross_win / gross_loss,
+        expectancy_usdt=None if not net_pnls else sum(net_pnls) / len(net_pnls),
+        average_win_usdt=None if not wins else gross_win / len(wins),
+        average_loss_usdt=None if not losses else -gross_loss / len(losses),
+        largest_win_usdt=max(wins) if wins else None,
+        largest_loss_usdt=min(losses) if losses else None,
+        average_holding_bars=None if not holding else sum(holding) / len(holding),
+        max_consecutive_wins=wins_streak,
+        max_consecutive_losses=losses_streak,
+        total_fees_usdt=total_fees,
+        # How much of the gross edge the costs consumed. Above 100% means fees
+        # alone turned a winning signal into a loss.
+        fees_pct_of_gross=None if abs(gross_pnl) <= 0 else total_fees / abs(gross_pnl) * 100,
+        turnover_usdt=sum(fill.notionalUsdt for fill in result.fills),
+        exposure_pct=0.0
+        if result.evaluation_bars == 0
+        else result.exposed_bars / result.evaluation_bars * 100,
+        evaluation_bars=result.evaluation_bars,
+        evaluation_days=evaluation_days,
+        trades_per_day=None if evaluation_days <= 0 else len(result.trades) / evaluation_days,
+        margin_exhausted=result.margin_exhausted,
+    )
+
+
+def _annualized_return(initial: float, final: float, bars: int) -> float | None:
+    years = max(1, bars) / MINUTES_PER_YEAR
+    if initial <= 0 or final <= 0 or years <= 0:
+        return None
+    # Compute in log space: a short window raises the growth ratio to a huge
+    # exponent, which overflows a float before any cap could be applied.
+    exponent = math.log(final / initial) / years
+    if exponent > _MAX_GROWTH_EXPONENT:
+        return ANNUALIZED_RETURN_CAP_PCT
+    value = (math.exp(exponent) - 1) * 100
+    return max(-100.0, min(value, ANNUALIZED_RETURN_CAP_PCT))
+
+
+def _sharpe(curve: list, downside_only: bool) -> float | None:
+    """Annualized Sharpe, or Sortino when only downside deviation counts.
+
+    Returns are per evaluation bar (one minute), so the annualization factor is
+    the square root of the number of minutes in a year.
+    """
+    if len(curve) < 3:
+        return None
+    returns: list[float] = []
+    for index in range(1, len(curve)):
+        previous = curve[index - 1].equity_usdt
+        if previous <= 0:
+            continue
+        returns.append(curve[index].equity_usdt / previous - 1)
+    if len(returns) < 2:
+        return None
+    mean = sum(returns) / len(returns)
+    sample = [value for value in returns if value < 0] if downside_only else returns
+    if len(sample) < 2:
+        return None
+    variance = sum((value - (0.0 if downside_only else mean)) ** 2 for value in sample) / (len(sample) - 1)
+    deviation = math.sqrt(variance)
+    if deviation <= 0:
+        return None
+    return mean / deviation * math.sqrt(MINUTES_PER_YEAR)
+
+
+def _streaks(values: list[float]) -> tuple[int, int]:
+    best_wins = 0
+    best_losses = 0
+    wins = 0
+    losses = 0
+    for value in values:
+        if value > 0:
+            wins += 1
+            losses = 0
+        elif value < 0:
+            losses += 1
+            wins = 0
+        else:
+            wins = 0
+            losses = 0
+        best_wins = max(best_wins, wins)
+        best_losses = max(best_losses, losses)
+    return best_wins, best_losses
+
+
+def build_report(result: RunResult, initial_equity_usdt: float) -> dict[str, object]:
+    metrics = calculate_metrics(result, initial_equity_usdt)
+    return {
+        "status": result.status,
+        "metrics": metrics.as_dict(),
+        "equity": [
+            {
+                "timeMs": point.time_ms,
+                "equityUsdt": _round(point.equity_usdt),
+                "realizedCashUsdt": _round(point.realized_cash_usdt),
+                "unrealizedPnlUsdt": _round(point.unrealized_pnl_usdt),
+            }
+            for point in result.equity_curve
+        ],
+        "trades": [
+            {
+                "id": trade.id,
+                "side": trade.side,
+                "quantity": _round(trade.quantity),
+                "entryPrice": _round(trade.entryPrice),
+                "exitPrice": _round(trade.exitPrice),
+                "realizedPnlUsdt": _round(trade.realizedPnlUsdt),
+                # Net of this trade's own fees, matching how win rate and profit
+                # factor are computed.
+                "netPnlUsdt": _round(trade.realizedPnlUsdt - trade.feesUsdt),
+                "feesUsdt": _round(trade.feesUsdt),
+                "returnPct": _round(
+                    0.0
+                    if trade.usedMarginUsdt <= 0
+                    else (trade.realizedPnlUsdt - trade.feesUsdt) / trade.usedMarginUsdt * 100
+                ),
+                "holdingBars": max(0, (trade.closedAtMs - trade.openedAtMs) // 60_000),
+                "openedAtMs": trade.openedAtMs,
+                "closedAtMs": trade.closedAtMs,
+                "isLong": trade.side == LONG,
+            }
+            for trade in result.trades
+        ],
+        "fills": [
+            {
+                "id": fill.id,
+                "action": fill.action,
+                "quantity": _round(fill.quantity),
+                "price": _round(fill.price),
+                "feeUsdt": _round(fill.feeUsdt),
+                "filledAtMs": fill.filledAtMs,
+            }
+            for fill in result.fills
+        ],
+        "actions": result.actions,
+    }
+
+
+def _round(value: float) -> float:
+    """Rounds to 10 decimals so a report hash is stable across platforms."""
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        return value
+    if math.isnan(value) or math.isinf(value):
+        return 0.0
+    return round(float(value), 10)
+
+
+def _optional(value: float | None) -> float | None:
+    return None if value is None else _round(value)