desic-okx-agent 0.2.0 → 0.3.0

package/python/desic_strategy/indicators.py

@@ -0,0 +1,159 @@
+"""Rolling indicators over the confirmed one-minute series.
+
+Only ``1m`` is accepted. A higher-timeframe active bucket can still be revised
+before it confirms, which makes it unsuitable for append-only indicator state:
+the cached value would silently depend on when it was first computed.
+"""
+
+from __future__ import annotations
+
+from .timeframe import Bar
+
+_LOOKUP_LIMIT = 5_000
+
+
+class IndicatorError(Exception):
+    """Raised when an indicator is requested outside its contract."""
+
+
+class IndicatorCache:
+    """Incrementally maintained EMA and Wilder ATR series.
+
+    Values are appended once per confirmed bar and never recomputed, so a
+    context retained from an earlier bar reads its own historical value rather
+    than a later one.
+    """
+
+    __slots__ = ("_atr", "_bars", "_ema")
+
+    def __init__(self) -> None:
+        self._bars: list[Bar] = []
+        self._ema: dict[int, list[float | None]] = {}
+        self._atr: dict[int, list[float | None]] = {}
+
+    def append(self, bar: Bar) -> None:
+        self._bars.append(bar)
+        for period, series in self._ema.items():
+            series.append(self._next_ema(period, series))
+        for period, series in self._atr.items():
+            series.append(self._next_atr(period, series))
+
+    @property
+    def length(self) -> int:
+        return len(self._bars)
+
+    def ema(self, period: int, offset: int, visible: int) -> float | None:
+        series = self._ensure(self._ema, period, self._next_ema)
+        return self._read(series, offset, visible)
+
+    def atr(self, period: int, offset: int, visible: int) -> float | None:
+        series = self._ensure(self._atr, period, self._next_atr)
+        return self._read(series, offset, visible)
+
+    def _ensure(
+        self,
+        store: dict[int, list[float | None]],
+        period: int,
+        step: object,
+    ) -> list[float | None]:
+        if not isinstance(period, int) or isinstance(period, bool) or period <= 0:
+            raise IndicatorError("period must be a positive integer")
+        if period > _LOOKUP_LIMIT:
+            raise IndicatorError(f"period must be at most {_LOOKUP_LIMIT}")
+        series = store.get(period)
+        if series is None:
+            # Backfill so a first request mid-run yields the same values it
+            # would have had if it were requested from the first bar.
+            series = []
+            store[period] = series
+            compute = step  # type: ignore[assignment]
+            for index in range(len(self._bars)):
+                series.append(compute(period, series, index + 1))  # type: ignore[operator]
+        return series
+
+    def _read(self, series: list[float | None], offset: int, visible: int) -> float | None:
+        if not isinstance(offset, int) or isinstance(offset, bool) or offset < 0:
+            raise IndicatorError("offset must be a non-negative integer")
+        index = visible - 1 - offset
+        if index < 0 or index >= len(series):
+            return None
+        return series[index]
+
+    def _next_ema(
+        self,
+        period: int,
+        series: list[float | None],
+        upto: int | None = None,
+    ) -> float | None:
+        count = len(self._bars) if upto is None else upto
+        if count < period:
+            return None
+        if count == period:
+            # Seed with the simple mean of the first `period` closes.
+            return sum(self._bars[index].close for index in range(period)) / period
+        previous = series[count - 2] if count - 2 < len(series) else None
+        if previous is None:
+            return sum(self._bars[index].close for index in range(count - period, count)) / period
+        # Only the newest close is needed once seeded, keeping each bar O(1).
+        multiplier = 2.0 / (period + 1)
+        return (self._bars[count - 1].close - previous) * multiplier + previous
+
+    def _next_atr(
+        self,
+        period: int,
+        series: list[float | None],
+        upto: int | None = None,
+    ) -> float | None:
+        count = len(self._bars) if upto is None else upto
+        # True range needs a prior close, so ATR starts one bar later than EMA.
+        if count < period + 1:
+            return None
+        if count == period + 1:
+            # Seed with the mean of the first `period` true ranges.
+            return sum(self._true_range(index) for index in range(1, count)) / period
+        previous = series[count - 2] if count - 2 < len(series) else None
+        if previous is None:
+            return sum(self._true_range(index) for index in range(1, period + 1)) / period
+        # Wilder smoothing needs only the newest true range, so each bar stays
+        # O(1); recomputing the whole range list here would make a long run
+        # quadratic in bar count.
+        return (previous * (period - 1) + self._true_range(count - 1)) / period
+
+    def _true_range(self, index: int) -> float:
+        bar = self._bars[index]
+        previous_close = self._bars[index - 1].close
+        return max(
+            bar.high - bar.low,
+            abs(bar.high - previous_close),
+            abs(bar.low - previous_close),
+        )
+
+
+class IndicatorView:
+    """Strategy-facing indicator accessor bound to one cutoff."""
+
+    __slots__ = ("_cache", "_instrument_id", "_visible")
+
+    def __init__(self, cache: IndicatorCache, instrument_id: str, visible: int) -> None:
+        self._cache = cache
+        self._instrument_id = instrument_id
+        self._visible = visible
+
+    def ema(self, instrument_id: str, interval: str, period: int, offset: int = 0) -> float | None:
+        self._check(instrument_id, interval)
+        return self._cache.ema(period, offset, self._visible)
+
+    def atr(self, instrument_id: str, interval: str, period: int, offset: int = 0) -> float | None:
+        self._check(instrument_id, interval)
+        return self._cache.atr(period, offset, self._visible)
+
+    def _check(self, instrument_id: str, interval: str) -> None:
+        if instrument_id != self._instrument_id:
+            raise IndicatorError(
+                f"Indicators are available for {self._instrument_id}, not {instrument_id}"
+            )
+        if interval != "1m":
+            raise IndicatorError(
+                "Indicators accept only the confirmed '1m' series; a higher-timeframe "
+                "active bucket can still be revised before it confirms"
+            )

package/python/desic_strategy/live.py

@@ -0,0 +1,253 @@
+"""One long-lived strategy session, driven one bar at a time.
+
+The backtest ``Engine`` owns a virtual account: it matches orders, charges fees,
+and tracks a position it computed itself. None of that applies here. A live fill
+is decided by the exchange, so the position handed to strategy code is the one
+the exchange reports — read fresh before every evaluation and passed in by the
+host.
+
+That is why this is a separate driver rather than a mode of ``Engine``. Reusing
+the virtual ledger would leave two sources of truth for the same position, and the
+moment a real fill differed from the simulated one — partial fill, manual close,
+liquidation — the strategy would be deciding against a position that does not
+exist.
+
+Everything a strategy actually touches *is* shared with the backtest:
+``SeriesSet``, ``IndicatorCache``, ``MarketView``, ``StrategyContext``, the action
+constructors, and the source policy. Only the account state differs, because only
+the account state can differ.
+"""
+
+from __future__ import annotations
+
+from .actions import Decision, StrategyError
+from .context import MarketView, SeriesSet, StrategyContext, immutable_params
+from .indicators import IndicatorView
+from .portfolio import LONG, SHORT, OpenOrder, PortfolioView, Position
+from .timeframe import Bar, DataContractError
+
+# Bars retained in memory. A session runs for days, so the window is bounded; this
+# is far more than any indicator lookback needs and keeps memory flat.
+MAX_RETAINED_BARS = 20_000
+
+
+class LiveSession:
+    """Evaluates one strategy against one instrument, one confirmed bar at a time."""
+
+    __slots__ = ("_bars", "_handlers", "_instrument_id", "_intervals", "_last_cutoff", "_params", "_series", "_started")
+
+    def __init__(
+        self,
+        instrument_id: str,
+        handlers: dict[str, object],
+        params: dict[str, object],
+        intervals: list[str],
+    ) -> None:
+        self._instrument_id = instrument_id
+        self._handlers = handlers
+        self._params = immutable_params(params)
+        self._intervals = intervals
+        self._series = SeriesSet(instrument_id, intervals)
+        self._bars: list[Bar] = []
+        self._started = False
+        self._last_cutoff: int | None = None
+
+    @property
+    def bar_count(self) -> int:
+        return len(self._bars)
+
+    @property
+    def last_cutoff_ms(self) -> int | None:
+        return self._last_cutoff
+
+    def warm(self, bars: list[Bar]) -> int:
+        """Feeds history without evaluating anything.
+
+        Indicators need a warm-up prefix, and running the strategy over it would
+        emit decisions for minutes that have already passed. Same rule as the
+        backtest's preload: warm-up produces no decisions.
+        """
+        for bar in bars:
+            self._append(bar)
+        return len(self._bars)
+
+    def evaluate(self, bar: Bar, portfolio: PortfolioView) -> Decision:
+        """Appends one confirmed bar and returns the single decision for it.
+
+        ``portfolio`` is the exchange's own view, read by the host immediately
+        before this call.
+        """
+        self._append(bar)
+        context = self._context(bar, portfolio)
+
+        if not self._started:
+            self._started = True
+            start_handler = self._handlers.get("on_start")
+            if callable(start_handler):
+                decision = start_handler(context)
+                if not isinstance(decision, Decision) or decision.action != "no_action":
+                    raise StrategyError("on_start must return ctx.no_action(...)")
+
+        handler = self._handlers.get("on_bar")
+        if not callable(handler):
+            raise StrategyError("A strategy must define on_bar(ctx)")
+        decision = handler(context)
+        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"
+            )
+        self._last_cutoff = bar.close_time_ms
+        return decision
+
+    def _append(self, bar: Bar) -> None:
+        if not bar.confirmed:
+            # An unconfirmed bar can still be revised. Acting on one would mean
+            # deciding against a candle that has not finished happening.
+            raise DataContractError("A live session accepts only confirmed bars")
+        previous = self._bars[-1] if self._bars else None
+        if previous is not None:
+            if bar.open_time_ms == previous.open_time_ms:
+                raise DataContractError(f"Bar {bar.open_time_ms} was already fed to this session")
+            expected = previous.close_time_ms
+            if bar.open_time_ms != expected:
+                # A gap means the strategy would see a jump the market did not
+                # make. The host is expected to repair the window and retry rather
+                # than have this smoothed over.
+                raise DataContractError(
+                    f"Bar {bar.open_time_ms} breaks continuity: expected open {expected}"
+                )
+        self._bars.append(bar)
+        self._series.push(bar)
+        # Trimming keeps the retained window bounded. `SeriesSet` holds its own
+        # incremental indicator state, which is append-only and unaffected.
+        if len(self._bars) > MAX_RETAINED_BARS:
+            del self._bars[: len(self._bars) - MAX_RETAINED_BARS]
+
+    def _context(self, bar: Bar, portfolio: PortfolioView) -> StrategyContext:
+        # `visible` is the full retained length: every bar in a live session is
+        # confirmed and in the past, so there is no future prefix to hide.
+        return StrategyContext(
+            kind="bar",
+            as_of_ms=bar.close_time_ms,
+            instrument_id=self._instrument_id,
+            interval="1m",
+            bar=bar,
+            market=MarketView(self._instrument_id, self._bars, len(self._bars), self._series.snapshot()),
+            portfolio=portfolio,
+            params=self._params,
+            indicators=IndicatorView(self._series.indicators, self._instrument_id, len(self._bars)),
+        )
+
+
+def parse_portfolio(value: object, instrument_id: str) -> PortfolioView:
+    """Builds the strategy-visible account snapshot from the host's payload.
+
+    Fields are read by their exact documented names and every one is required.
+    Defaulting a missing balance to zero would let a protocol mismatch present
+    itself as a flat account, and a strategy would then open a position believing
+    it holds none.
+    """
+    if not isinstance(value, dict):
+        raise DataContractError("'portfolio' must be an object")
+    return PortfolioView(
+        cash_usdt=_required_float(value, "cashUsdt"),
+        equity_usdt=_required_float(value, "equityUsdt"),
+        used_margin_usdt=_required_float(value, "usedMarginUsdt"),
+        available_margin_usdt=_required_float(value, "availableMarginUsdt"),
+        positions=_parse_positions(value.get("positions"), instrument_id),
+        open_orders=_parse_open_orders(value.get("openOrders"), instrument_id),
+    )
+
+
+def _parse_positions(value: object, instrument_id: str) -> tuple[Position, ...]:
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise DataContractError("'portfolio.positions' must be an array")
+    positions: list[Position] = []
+    for index, row in enumerate(value):
+        if not isinstance(row, dict):
+            raise DataContractError(f"portfolio.positions[{index}] must be an object")
+        side = str(row.get("side") or "")
+        if side not in (LONG, SHORT):
+            raise DataContractError(f"portfolio.positions[{index}].side must be '{LONG}' or '{SHORT}'")
+        quantity = _required_float(row, "quantity", f"portfolio.positions[{index}]")
+        if quantity <= 0:
+            # The exchange reports a closed position by omitting it, so a zero
+            # quantity here means the host built the payload wrong.
+            raise DataContractError(f"portfolio.positions[{index}].quantity must be greater than zero")
+        positions.append(
+            Position(
+                instrumentId=str(row.get("instrumentId") or instrument_id),
+                side=side,
+                quantity=quantity,
+                averageEntryPrice=_required_float(row, "averageEntryPrice", f"portfolio.positions[{index}]"),
+                markPrice=_required_float(row, "markPrice", f"portfolio.positions[{index}]"),
+                contractValue=_required_float(row, "contractValue", f"portfolio.positions[{index}]"),
+                notionalUsdt=_required_float(row, "notionalUsdt", f"portfolio.positions[{index}]"),
+                usedMarginUsdt=_required_float(row, "usedMarginUsdt", f"portfolio.positions[{index}]"),
+                leverage=_required_float(row, "leverage", f"portfolio.positions[{index}]"),
+                marginSafetyMultiplier=_optional_float(row.get("marginSafetyMultiplier"), 1.0),
+                unrealizedPnlUsdt=_required_float(row, "unrealizedPnlUsdt", f"portfolio.positions[{index}]"),
+                entryFeeUsdt=_optional_float(row.get("entryFeeUsdt"), 0.0),
+                stopLossPrice=_nullable_float(row.get("stopLossPrice")),
+                takeProfitPrice=_nullable_float(row.get("takeProfitPrice")),
+                openedAtMs=int(_optional_float(row.get("openedAtMs"), 0.0)),
+                updatedAtMs=int(_optional_float(row.get("updatedAtMs"), 0.0)),
+            )
+        )
+    return tuple(positions)
+
+
+def _parse_open_orders(value: object, instrument_id: str) -> tuple[OpenOrder, ...]:
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise DataContractError("'portfolio.openOrders' must be an array")
+    orders: list[OpenOrder] = []
+    for index, row in enumerate(value):
+        if not isinstance(row, dict):
+            raise DataContractError(f"portfolio.openOrders[{index}] must be an object")
+        identifier = str(row.get("id") or "")
+        if not identifier:
+            # `cancel_order` references this id, so an order without one could be
+            # seen but never cancelled.
+            raise DataContractError(f"portfolio.openOrders[{index}].id is required")
+        orders.append(
+            OpenOrder(
+                id=identifier,
+                instrumentId=str(row.get("instrumentId") or instrument_id),
+                action=str(row.get("action") or ""),
+                quantity=_required_float(row, "quantity", f"portfolio.openOrders[{index}]"),
+                filledQuantity=_optional_float(row.get("filledQuantity"), 0.0),
+                status=str(row.get("status") or "open"),
+                price=_nullable_float(row.get("price")),
+                createdAtMs=int(_optional_float(row.get("createdAtMs"), 0.0)),
+            )
+        )
+    return tuple(orders)
+
+
+def _required_float(row: dict[str, object], key: str, label: str = "portfolio") -> float:
+    if key not in row or row[key] is None:
+        raise DataContractError(f"{label}.{key} is required")
+    return _finite(row[key], f"{label}.{key}")
+
+
+def _optional_float(value: object, fallback: float) -> float:
+    return fallback if value is None else _finite(value, "value")
+
+
+def _nullable_float(value: object) -> float | None:
+    return None if value is None else _finite(value, "value")
+
+
+def _finite(value: object, label: str) -> float:
+    try:
+        parsed = float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError) as error:
+        raise DataContractError(f"{label} must be a number") from error
+    if parsed != parsed or parsed in (float("inf"), float("-inf")):
+        raise DataContractError(f"{label} must be finite")
+    return parsed

package/python/desic_strategy/policy.py

@@ -0,0 +1,193 @@
+"""Static source policy for user-authored strategies.
+
+This runs before any strategy code is imported. It is defence in depth, not a
+security boundary: the process already receives no credentials, no exchange
+client, and no order API. Its job is to catch the mistakes and reaches that
+would otherwise fail confusingly deep inside a run.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+ALLOWED_IMPORT_ROOTS = frozenset(
+    {"collections", "dataclasses", "math", "numpy", "pandas", "statistics", "typing"}
+)
+
+# Dynamic attribute access and host reach. `getattr` is rejected on purpose:
+# probing for a field spelling hides a protocol mismatch that should fail loudly.
+FORBIDDEN_NAMES = frozenset(
+    {
+        "getattr",
+        "setattr",
+        "delattr",
+        "dir",
+        "vars",
+        "globals",
+        "locals",
+        "eval",
+        "exec",
+        "compile",
+        "__import__",
+        "open",
+        "input",
+        "help",
+        "breakpoint",
+    }
+)
+
+REQUIRED_HANDLER = "on_bar"
+OPTIONAL_HANDLERS = frozenset({"on_start"})
+MAX_SOURCE_BYTES = 256 * 1024
+
+
+@dataclass(frozen=True)
+class PolicyViolation:
+    line: int
+    code: str
+    message: str
+
+    def as_dict(self) -> dict[str, object]:
+        return {"line": self.line, "code": self.code, "message": self.message}
+
+
+def validate_source(source: str) -> list[PolicyViolation]:
+    """Returns every violation found, ordered by line, or an empty list."""
+    violations: list[PolicyViolation] = []
+    encoded = source.encode("utf-8")
+    if len(encoded) > MAX_SOURCE_BYTES:
+        return [
+            PolicyViolation(
+                1,
+                "source_too_large",
+                f"Strategy source is {len(encoded)} bytes, above the {MAX_SOURCE_BYTES} byte limit",
+            )
+        ]
+
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as error:
+        return [PolicyViolation(error.lineno or 1, "syntax_error", f"Syntax error: {error.msg}")]
+
+    violations.extend(_check_imports(tree))
+    violations.extend(_check_names(tree))
+    violations.extend(_check_handlers(tree))
+    violations.sort(key=lambda item: (item.line, item.code))
+    return violations
+
+
+def _check_imports(tree: ast.AST) -> list[PolicyViolation]:
+    found: list[PolicyViolation] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                root = alias.name.split(".")[0]
+                if root not in ALLOWED_IMPORT_ROOTS:
+                    found.append(
+                        PolicyViolation(
+                            node.lineno,
+                            "forbidden_import",
+                            f"Import of '{alias.name}' is not allowed. Allowed roots: "
+                            + ", ".join(sorted(ALLOWED_IMPORT_ROOTS)),
+                        )
+                    )
+        elif isinstance(node, ast.ImportFrom):
+            # A bare relative import has no module name; it can only reach code
+            # outside the single-module strategy contract.
+            if node.level and node.level > 0:
+                found.append(
+                    PolicyViolation(
+                        node.lineno,
+                        "forbidden_import",
+                        "Relative imports are not allowed in a strategy module",
+                    )
+                )
+                continue
+            root = (node.module or "").split(".")[0]
+            if root not in ALLOWED_IMPORT_ROOTS:
+                found.append(
+                    PolicyViolation(
+                        node.lineno,
+                        "forbidden_import",
+                        f"Import from '{node.module}' is not allowed. Allowed roots: "
+                        + ", ".join(sorted(ALLOWED_IMPORT_ROOTS)),
+                    )
+                )
+    return found
+
+
+def _check_names(tree: ast.AST) -> list[PolicyViolation]:
+    found: list[PolicyViolation] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name) and node.id in FORBIDDEN_NAMES:
+            found.append(
+                PolicyViolation(
+                    node.lineno,
+                    "forbidden_name",
+                    f"'{node.id}' is not available to a strategy. Read documented fields directly.",
+                )
+            )
+        elif isinstance(node, ast.Attribute) and node.attr.startswith("__"):
+            found.append(
+                PolicyViolation(
+                    node.lineno,
+                    "dunder_access",
+                    f"Access to '{node.attr}' is not allowed",
+                )
+            )
+        elif isinstance(node, (ast.AsyncFunctionDef, ast.Await, ast.AsyncFor, ast.AsyncWith)):
+            found.append(
+                PolicyViolation(
+                    node.lineno,
+                    "async_not_supported",
+                    "Strategy handlers must be synchronous",
+                )
+            )
+    return found
+
+
+def _check_handlers(tree: ast.Module) -> list[PolicyViolation]:
+    found: list[PolicyViolation] = []
+    handlers: dict[str, ast.FunctionDef] = {}
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef) and (
+            node.name == REQUIRED_HANDLER or node.name in OPTIONAL_HANDLERS
+        ):
+            handlers[node.name] = node
+
+    if REQUIRED_HANDLER not in handlers:
+        found.append(
+            PolicyViolation(
+                1,
+                "missing_handler",
+                f"A strategy must define '{REQUIRED_HANDLER}(ctx)'",
+            )
+        )
+
+    for name, node in handlers.items():
+        arguments = node.args
+        positional = [*arguments.posonlyargs, *arguments.args]
+        if (
+            len(positional) != 1
+            or arguments.vararg is not None
+            or arguments.kwarg is not None
+            or arguments.kwonlyargs
+        ):
+            found.append(
+                PolicyViolation(
+                    node.lineno,
+                    "handler_signature",
+                    f"'{name}' must take exactly one positional argument (ctx)",
+                )
+            )
+        for inner in ast.walk(node):
+            if isinstance(inner, (ast.Yield, ast.YieldFrom)):
+                found.append(
+                    PolicyViolation(
+                        inner.lineno,
+                        "generator_handler",
+                        f"'{name}' must return a decision, not yield",
+                    )
+                )
+    return found