desic-okx-agent 0.2.1 → 0.3.1

package/python/desic_strategy/actions.py

@@ -0,0 +1,158 @@
+"""Strategy decisions.
+
+A decision is an *intent*, never an order. It carries no contract count: the
+host derives a legal size from its own budget and the instrument's rules, so a
+strategy cannot size a position past the risk boundary.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+NO_ACTION = "no_action"
+OPEN_LONG = "open_long"
+OPEN_SHORT = "open_short"
+CLOSE_LONG = "close_long"
+CLOSE_SHORT = "close_short"
+CANCEL_ORDER = "cancel_order"
+
+OPENING_ACTIONS = frozenset({OPEN_LONG, OPEN_SHORT})
+CLOSING_ACTIONS = frozenset({CLOSE_LONG, CLOSE_SHORT})
+ALL_ACTIONS = frozenset({NO_ACTION, *OPENING_ACTIONS, *CLOSING_ACTIONS, CANCEL_ORDER})
+
+MARKET = "market"
+LIMIT = "limit"
+
+
+class StrategyError(Exception):
+    """Raised when strategy output violates the decision contract."""
+
+
+@dataclass(frozen=True)
+class Execution:
+    order_type: str
+    limit_price: float | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        if self.order_type == MARKET:
+            return {"orderType": MARKET}
+        return {"orderType": LIMIT, "limitPrice": self.limit_price}
+
+
+@dataclass(frozen=True)
+class Protection:
+    """An optional *request* attached to an opening action, not an order."""
+
+    stop_loss_price: float | None = None
+    take_profit_price: float | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        payload: dict[str, object] = {}
+        if self.stop_loss_price is not None:
+            payload["stopLossPrice"] = self.stop_loss_price
+        if self.take_profit_price is not None:
+            payload["takeProfitPrice"] = self.take_profit_price
+        return payload
+
+
+@dataclass(frozen=True)
+class Decision:
+    action: str
+    reason: str
+    execution: Execution = field(default_factory=lambda: Execution(MARKET))
+    protection: Protection | None = None
+    order_id: str | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        payload: dict[str, object] = {"action": self.action, "reason": self.reason}
+        if self.action in OPENING_ACTIONS or self.action in CLOSING_ACTIONS:
+            payload["execution"] = self.execution.as_dict()
+        if self.protection is not None:
+            protection = self.protection.as_dict()
+            if protection:
+                payload["protection"] = protection
+        if self.order_id is not None:
+            payload["orderId"] = self.order_id
+        return payload
+
+
+def market_order() -> Execution:
+    return Execution(MARKET)
+
+
+def limit_order(limit_price: float) -> Execution:
+    price = _positive_price(limit_price, "limit_price")
+    return Execution(LIMIT, price)
+
+
+def _positive_price(value: object, label: str) -> float:
+    try:
+        price = float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError) as error:
+        raise StrategyError(f"{label} must be a number") from error
+    if price != price or price in (float("inf"), float("-inf")):
+        raise StrategyError(f"{label} must be finite")
+    if price <= 0:
+        raise StrategyError(f"{label} must be greater than zero")
+    return price
+
+
+def _reason(value: object) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise StrategyError("Every decision requires a non-empty audit reason")
+    if len(value) > 500:
+        raise StrategyError("A decision reason must be at most 500 characters")
+    return value.strip()
+
+
+def _protection(value: object) -> Protection | None:
+    """Accepts the documented mapping form: ``{"stopLossPrice": .., "takeProfitPrice": ..}``."""
+    if value is None:
+        return None
+    if not isinstance(value, dict):
+        raise StrategyError("protection must be a mapping with stopLossPrice and/or takeProfitPrice")
+    unknown = set(value) - {"stopLossPrice", "takeProfitPrice"}
+    if unknown:
+        raise StrategyError(f"Unknown protection field(s): {', '.join(sorted(unknown))}")
+    stop = value.get("stopLossPrice")
+    take = value.get("takeProfitPrice")
+    if stop is None and take is None:
+        raise StrategyError("protection requires stopLossPrice and/or takeProfitPrice")
+    return Protection(
+        stop_loss_price=None if stop is None else _positive_price(stop, "stopLossPrice"),
+        take_profit_price=None if take is None else _positive_price(take, "takeProfitPrice"),
+    )
+
+
+def _execution(value: object) -> Execution:
+    if value is None:
+        return Execution(MARKET)
+    if isinstance(value, Execution):
+        return value
+    raise StrategyError("execution must be ctx.market_order() or ctx.limit_order(price)")
+
+
+def no_action(reason: object = "no action") -> Decision:
+    return Decision(NO_ACTION, _reason(reason))
+
+
+def open_long(reason: object, protection: object = None, execution: object = None) -> Decision:
+    return Decision(OPEN_LONG, _reason(reason), _execution(execution), _protection(protection))
+
+
+def open_short(reason: object, protection: object = None, execution: object = None) -> Decision:
+    return Decision(OPEN_SHORT, _reason(reason), _execution(execution), _protection(protection))
+
+
+def close_long(reason: object, execution: object = None) -> Decision:
+    return Decision(CLOSE_LONG, _reason(reason), _execution(execution))
+
+
+def close_short(reason: object, execution: object = None) -> Decision:
+    return Decision(CLOSE_SHORT, _reason(reason), _execution(execution))
+
+
+def cancel_order(order_id: object, reason: object) -> Decision:
+    if not isinstance(order_id, str) or not order_id.strip():
+        raise StrategyError("cancel_order requires the id of a current open order")
+    return Decision(CANCEL_ORDER, _reason(reason), order_id=order_id.strip())

package/python/desic_strategy/context.py

@@ -0,0 +1,171 @@
+"""The immutable context handed to a strategy handler.
+
+Every field is read-only and bounded by ``as_of_ms``. The market view holds the
+full bar array but exposes only the visible prefix, so look-ahead is prevented
+structurally rather than by convention.
+"""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+from typing import Mapping
+
+from . import actions
+from .actions import Decision, Execution
+from .indicators import IndicatorCache, IndicatorView
+from .portfolio import PortfolioView
+from .timeframe import Bar, TimeframeAggregator, interval_ms
+
+
+class ContextError(Exception):
+    """Raised when a strategy requests data outside its contract."""
+
+
+class MarketView:
+    """Point-in-time K-line access across derived timeframes."""
+
+    __slots__ = ("_aggregates", "_instrument_id", "_minutes", "_visible")
+
+    def __init__(
+        self,
+        instrument_id: str,
+        minutes: list[Bar],
+        visible: int,
+        aggregates: Mapping[str, tuple[Bar, ...]],
+    ) -> None:
+        self._instrument_id = instrument_id
+        self._minutes = minutes
+        self._visible = visible
+        self._aggregates = aggregates
+
+    def bars(self, instrument_id: str, interval: str = "1m", lookback: int | None = None) -> tuple[Bar, ...]:
+        if instrument_id != self._instrument_id:
+            raise ContextError(
+                f"Market data is available for {self._instrument_id}, not {instrument_id}"
+            )
+        interval_ms(interval)
+        if lookback is not None and (
+            not isinstance(lookback, int) or isinstance(lookback, bool) or lookback <= 0
+        ):
+            raise ValueError("lookback must be a positive integer")
+        if interval == "1m":
+            # Sliced before the copy, not after. `_minutes` holds the whole run, so
+            # copying the visible prefix and then discarding all but the tail costs one
+            # copy of everything seen so far, on every bar — quadratic in the window
+            # length. Measured on a 260k-bar run: a strategy asking for 17 bars here
+            # took 576 us/bar, against 16 us/bar for one that never called this method.
+            stop = self._visible
+            start = 0 if lookback is None else max(0, stop - lookback)
+            return tuple(self._minutes[start:stop])
+        found = self._aggregates.get(interval)
+        if found is None:
+            raise ContextError(f"Series '{interval}' is not available in this run")
+        # Aggregates are already immutable tuples ending at the cutoff, so slicing one
+        # copies only what was asked for.
+        return found if lookback is None else found[-lookback:]
+
+
+class StrategyContext:
+    """Read-only decision context for one cutoff."""
+
+    __slots__ = (
+        "_frozen",
+        "as_of_ms",
+        "bar",
+        "indicators",
+        "instrument_id",
+        "interval",
+        "kind",
+        "market",
+        "params",
+        "portfolio",
+    )
+
+    def __init__(
+        self,
+        *,
+        kind: str,
+        as_of_ms: int,
+        instrument_id: str,
+        interval: str,
+        bar: Bar | None,
+        market: MarketView,
+        portfolio: PortfolioView,
+        params: Mapping[str, object],
+        indicators: IndicatorView,
+    ) -> None:
+        object.__setattr__(self, "kind", kind)
+        object.__setattr__(self, "as_of_ms", as_of_ms)
+        object.__setattr__(self, "instrument_id", instrument_id)
+        object.__setattr__(self, "interval", interval)
+        object.__setattr__(self, "bar", bar)
+        object.__setattr__(self, "market", market)
+        object.__setattr__(self, "portfolio", portfolio)
+        object.__setattr__(self, "params", params)
+        object.__setattr__(self, "indicators", indicators)
+        object.__setattr__(self, "_frozen", True)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        raise ContextError("The strategy context is read-only")
+
+    def __delattr__(self, name: str) -> None:
+        raise ContextError("The strategy context is read-only")
+
+    # Position lookup shortcut, matching `portfolio.position`.
+    def position(self, instrument_id: str, side: str):  # noqa: ANN201 - returns Position | None
+        return self.portfolio.position(instrument_id, side)
+
+    def market_order(self) -> Execution:
+        return actions.market_order()
+
+    def limit_order(self, limit_price: float) -> Execution:
+        return actions.limit_order(limit_price)
+
+    def no_action(self, reason: object = "no action") -> Decision:
+        return actions.no_action(reason)
+
+    def open_long(self, reason: object, protection: object = None, execution: object = None) -> Decision:
+        return actions.open_long(reason, protection, execution)
+
+    def open_short(self, reason: object, protection: object = None, execution: object = None) -> Decision:
+        return actions.open_short(reason, protection, execution)
+
+    def close_long(self, reason: object, execution: object = None) -> Decision:
+        return actions.close_long(reason, execution)
+
+    def close_short(self, reason: object, execution: object = None) -> Decision:
+        return actions.close_short(reason, execution)
+
+    def cancel_order(self, order_id: object, reason: object) -> Decision:
+        return actions.cancel_order(order_id, reason)
+
+
+def immutable_params(params: Mapping[str, object] | None) -> Mapping[str, object]:
+    return MappingProxyType(dict(params or {}))
+
+
+class SeriesSet:
+    """Maintains one aggregator per requested higher timeframe."""
+
+    __slots__ = ("_aggregators", "_cache", "_instrument_id")
+
+    def __init__(self, instrument_id: str, intervals: list[str]) -> None:
+        self._instrument_id = instrument_id
+        self._aggregators = {
+            interval: TimeframeAggregator(interval)
+            for interval in intervals
+            if interval != "1m"
+        }
+        self._cache = IndicatorCache()
+
+    @property
+    def indicators(self) -> IndicatorCache:
+        return self._cache
+
+    def push(self, bar: Bar) -> None:
+        self._cache.append(bar)
+        for aggregator in self._aggregators.values():
+            aggregator.push(bar)
+
+    def snapshot(self) -> dict[str, tuple[Bar, ...]]:
+        return {interval: agg.snapshot() for interval, agg in self._aggregators.items()}