desic-okx-agent 0.2.0 → 0.3.0

package/python/desic_strategy/runner.py

@@ -0,0 +1,574 @@
+"""Process entry point for one backtest or one source validation.
+
+Contract with the host:
+
+* stdin  - one JSON request object
+* stdout - one JSON response object
+* stderr - ``PROGRESS {...}`` lines while running, then any diagnostics
+
+The strategy module is executed with a restricted ``__builtins__`` mapping after
+static policy validation. That is dependency and mistake isolation, not an OS
+sandbox: the host still only runs source the user has chosen to trust.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from .actions import StrategyError
+from .engine import Costs, Engine, Instrument, RunConfig, Sizing
+from .indicators import IndicatorError
+from .live import LiveSession, parse_portfolio
+from .policy import validate_source
+from .report import build_report, calculate_metrics
+from .timeframe import Bar, DataContractError, ONE_MINUTE_MS, interval_ms
+
+PROTOCOL_VERSION = "desic.strategy/v1"
+
+# Builtins a numeric strategy legitimately needs. Everything absent here — file
+# and network access, dynamic import, eval, attribute probing — is unavailable.
+_SAFE_BUILTINS = {
+    "abs": abs,
+    "all": all,
+    "any": any,
+    "bool": bool,
+    "dict": dict,
+    "divmod": divmod,
+    "enumerate": enumerate,
+    "filter": filter,
+    "float": float,
+    "format": format,
+    "frozenset": frozenset,
+    "int": int,
+    "isinstance": isinstance,
+    "issubclass": issubclass,
+    "iter": iter,
+    "len": len,
+    "list": list,
+    "map": map,
+    "max": max,
+    "min": min,
+    "next": next,
+    "pow": pow,
+    "print": print,
+    "range": range,
+    "repr": repr,
+    "reversed": reversed,
+    "round": round,
+    "set": set,
+    "slice": slice,
+    "sorted": sorted,
+    "str": str,
+    "sum": sum,
+    "tuple": tuple,
+    "zip": zip,
+    "True": True,
+    "False": False,
+    "None": None,
+    "ValueError": ValueError,
+    "TypeError": TypeError,
+    "KeyError": KeyError,
+    "IndexError": IndexError,
+    "ZeroDivisionError": ZeroDivisionError,
+    "ArithmeticError": ArithmeticError,
+    "Exception": Exception,
+    "__build_class__": __build_class__,
+    "__name__": "desic_strategy_module",
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    raw = _read_request_text()
+    try:
+        request = json.loads(raw) if raw.strip() else {}
+    except json.JSONDecodeError as error:
+        _emit({"ok": False, "error": {"code": "bad_request", "message": f"Invalid JSON request: {error}"}})
+        return 2
+
+    command = str(request.get("command") or "")
+    try:
+        if command == "validate":
+            _emit(_validate(request))
+            return 0
+        if command == "backtest":
+            _emit(_backtest(request))
+            return 0
+        if command == "optimize":
+            _emit(_optimize(request))
+            return 0
+        if command == "live":
+            # Stays alive and keeps reading stdin, unlike every other command.
+            return _live(request)
+        _emit(
+            {
+                "ok": False,
+                "error": {
+                    "code": "bad_request",
+                    "message": (
+                        f"Unknown command '{command}'. Expected 'validate', 'backtest', or 'optimize'."
+                    ),
+                },
+            }
+        )
+        return 2
+    except (StrategyError, DataContractError, IndicatorError) as error:
+        _emit({"ok": False, "error": {"code": "strategy_error", "message": str(error)}})
+        return 1
+    except Exception as error:  # noqa: BLE001 - surface any failure as structured output
+        _emit({"ok": False, "error": {"code": "internal", "message": f"{type(error).__name__}: {error}"}})
+        return 1
+
+
+def _read_request_text() -> str:
+    """Reads the opening request without consuming what follows it.
+
+    The one-shot commands send a single JSON object and close stdin, so reading to
+    EOF is correct for them. ``live`` keeps the pipe open and sends further
+    messages line by line, so the first line is read on its own — reading to EOF
+    there would swallow every bar and then block forever.
+    """
+    first = sys.stdin.readline()
+    if not first.strip():
+        return first
+    try:
+        parsed = json.loads(first)
+    except json.JSONDecodeError:
+        # Not a complete object on line one: a one-shot request pretty-printed
+        # across several lines. Read the rest and let the caller parse it.
+        return first + sys.stdin.read()
+    if isinstance(parsed, dict) and parsed.get("command") == "live":
+        return first
+    return first + sys.stdin.read()
+
+
+def _validate(request: dict[str, Any]) -> dict[str, Any]:
+    source = str(request.get("source") or "")
+    violations = validate_source(source)
+    return {
+        "ok": True,
+        "protocol": PROTOCOL_VERSION,
+        "valid": not violations,
+        "violations": [item.as_dict() for item in violations],
+    }
+
+
+def _backtest(request: dict[str, Any]) -> dict[str, Any]:
+    source = str(request.get("source") or "")
+    violations = validate_source(source)
+    if violations:
+        return {
+            "ok": False,
+            "error": {
+                "code": "policy_violation",
+                "message": "Strategy source failed the static policy check",
+                "violations": [item.as_dict() for item in violations],
+            },
+        }
+
+    bars = _parse_bars(request.get("bars"))
+    config = _parse_config(request)
+    params = dict(request.get("params") or {})
+    intervals = _parse_intervals(request.get("intervals"))
+    handlers = _load_handlers(source)
+
+    total = len(bars)
+    engine = Engine(config, handlers, params)
+    result = engine.run(bars, intervals, _progress)
+    report = build_report(result, config.initial_equity_usdt)
+    return {
+        "ok": True,
+        "protocol": PROTOCOL_VERSION,
+        "barCount": total,
+        "preloadBars": config.preload_bars,
+        "report": report,
+    }
+
+
+def _live(request: dict[str, Any]) -> int:
+    """Runs one long-lived session, evaluating one bar per message.
+
+    Protocol, one JSON object per line in each direction:
+
+        → {"command":"live","source":...,"instrument":...,"params":...}
+        ← {"ok":true,"protocol":...,"handlers":[...]}
+        → {"kind":"warm","bars":[...]}          history, no decisions
+        ← {"ok":true,"kind":"warm","barCount":N}
+        → {"kind":"bar","bar":{...},"portfolio":{...}}
+        ← {"ok":true,"kind":"action","action":"open_long",...}
+        → {"command":"shutdown"}
+
+    A failure on one bar is reported and the session stays up: a single bad
+    evaluation is this minute's problem, and tearing down the process would lose
+    the warmed indicator state for every minute after it. Only a protocol
+    violation or an explicit shutdown ends the loop.
+    """
+    source = str(request.get("source") or "")
+    violations = validate_source(source)
+    if violations:
+        _emit(
+            {
+                "ok": False,
+                "error": {
+                    "code": "policy_violation",
+                    "message": "Strategy source failed the static policy check",
+                    "violations": [item.as_dict() for item in violations],
+                },
+            }
+        )
+        return 1
+
+    instrument_raw = request.get("instrument")
+    if not isinstance(instrument_raw, dict) or not str(instrument_raw.get("instId") or ""):
+        _emit({"ok": False, "error": {"code": "bad_request", "message": "instrument.instId is required"}})
+        return 2
+    instrument_id = str(instrument_raw["instId"])
+    intervals = _parse_intervals(request.get("intervals"))
+    handlers = _load_handlers(source)
+    session = LiveSession(instrument_id, handlers, dict(request.get("params") or {}), intervals)
+
+    _emit({"ok": True, "protocol": PROTOCOL_VERSION, "kind": "ready", "handlers": sorted(handlers)})
+
+    for line in sys.stdin:
+        if not line.strip():
+            continue
+        try:
+            message = json.loads(line)
+        except json.JSONDecodeError as error:
+            # A malformed frame means the stream is no longer trustworthy; a
+            # desynchronised pipe must not be interpreted as trading input.
+            _emit({"ok": False, "error": {"code": "bad_request", "message": f"Invalid JSON message: {error}"}})
+            return 2
+        if not isinstance(message, dict):
+            _emit({"ok": False, "error": {"code": "bad_request", "message": "Each message must be an object"}})
+            return 2
+
+        if message.get("command") == "shutdown":
+            _emit({"ok": True, "kind": "shutdown"})
+            return 0
+
+        kind = str(message.get("kind") or "")
+        try:
+            if kind == "warm":
+                count = session.warm(_parse_bars(message.get("bars")))
+                _emit({"ok": True, "kind": "warm", "barCount": count})
+                continue
+            if kind == "bar":
+                bars = _parse_bars([message.get("bar")])
+                portfolio = parse_portfolio(message.get("portfolio"), instrument_id)
+                decision = session.evaluate(bars[0], portfolio)
+                _emit(
+                    {
+                        "ok": True,
+                        "kind": "action",
+                        "asOfMs": bars[0].close_time_ms,
+                        "barCount": session.bar_count,
+                        **decision.as_dict(),
+                    }
+                )
+                continue
+            _emit({"ok": False, "error": {"code": "bad_request", "message": f"Unknown message kind '{kind}'"}})
+        except (StrategyError, DataContractError, IndicatorError) as error:
+            _emit({"ok": False, "kind": "error", "error": {"code": "strategy_error", "message": str(error)}})
+        except Exception as error:  # noqa: BLE001 - one bad bar must not end the session
+            _emit(
+                {
+                    "ok": False,
+                    "kind": "error",
+                    "error": {"code": "internal", "message": f"{type(error).__name__}: {error}"},
+                }
+            )
+    # stdin closed without a shutdown message: the host is gone.
+    return 0
+
+
+def _optimize(request: dict[str, Any]) -> dict[str, Any]:
+    """Evaluates many parameter sets over the same bars in one process.
+
+    The bars are parsed once and the candidates run in sequence. That is a memory
+    decision, not a speed one: transferring and parsing the payload is a small
+    share of a single candidate's cost, but spawning one process per candidate
+    would hold the same multi-megabyte array once per process.
+
+    Each candidate is measured twice — over the segment it was chosen on and over
+    a later segment it never saw. Both slices come from this one array, so the two
+    measurements cannot disagree about the underlying data.
+    """
+    source = str(request.get("source") or "")
+    violations = validate_source(source)
+    if violations:
+        return {
+            "ok": False,
+            "error": {
+                "code": "policy_violation",
+                "message": "Strategy source failed the static policy check",
+                "violations": [item.as_dict() for item in violations],
+            },
+        }
+
+    bars = _parse_bars(request.get("bars"))
+    base_config = _parse_config(request)
+    intervals = _parse_intervals(request.get("intervals"))
+    handlers = _load_handlers(source)
+    segments = _parse_segments(request.get("segments"), len(bars))
+    candidates = _parse_candidates(request.get("candidates"))
+
+    total_units = len(candidates) * len(segments)
+    done_units = 0
+    results: list[dict[str, Any]] = []
+
+    for candidate in candidates:
+        index = int(candidate["index"])
+        params = dict(candidate["params"])
+        measured: dict[str, Any] = {}
+        failure: str | None = None
+        for segment in segments:
+            slice_bars = bars[segment["fromIndex"] : segment["toIndex"] + 1]
+            config = _with_preload(base_config, segment["preloadBars"])
+            try:
+                engine = Engine(config, handlers, params)
+                result = engine.run(slice_bars, intervals, None)
+                measured[segment["name"]] = calculate_metrics(
+                    result, config.initial_equity_usdt
+                ).as_dict()
+            except (StrategyError, DataContractError, IndicatorError) as error:
+                failure = f"{segment['name']}: {error}"
+            except Exception as error:  # noqa: BLE001 - one candidate must not end the batch
+                failure = f"{segment['name']}: {type(error).__name__}: {error}"
+            done_units += 1
+            _progress(done_units, total_units)
+            if failure is not None:
+                break
+        if failure is None:
+            results.append({"index": index, "ok": True, "metrics": measured})
+        else:
+            # Recorded rather than raised: one unusable combination is a data
+            # point about that combination, not a reason to discard the others.
+            results.append({"index": index, "ok": False, "error": failure})
+
+    _progress(total_units, total_units)
+    return {
+        "ok": True,
+        "protocol": PROTOCOL_VERSION,
+        "barCount": len(bars),
+        "candidateCount": len(candidates),
+        "results": results,
+    }
+
+
+def _progress(done: int, total: int) -> None:
+    payload = {"done": done, "total": total, "pct": 0.0 if total == 0 else done / total * 100}
+    sys.stderr.write(f"PROGRESS {json.dumps(payload)}\n")
+    sys.stderr.flush()
+
+
+def _with_preload(config: RunConfig, preload_bars: int) -> RunConfig:
+    """Copies a config with a different preload length.
+
+    Each segment carries its own warm-up prefix, so the count differs per segment
+    while every other assumption stays identical between them.
+    """
+    return RunConfig(
+        instrument=config.instrument,
+        initial_equity_usdt=config.initial_equity_usdt,
+        costs=config.costs,
+        sizing=config.sizing,
+        preload_bars=preload_bars,
+        close_at_end=config.close_at_end,
+        limit_order_ttl_bars=config.limit_order_ttl_bars,
+    )
+
+
+def _parse_segments(value: Any, bar_count: int) -> list[dict[str, Any]]:
+    if not isinstance(value, list) or not value:
+        raise DataContractError("'segments' must be a non-empty array")
+    segments: list[dict[str, Any]] = []
+    for position, row in enumerate(value):
+        if not isinstance(row, dict):
+            raise DataContractError(f"segments[{position}] must be an object")
+        try:
+            name = str(row["name"])
+            from_index = int(row["fromIndex"])
+            to_index = int(row["toIndex"])
+            preload = int(row["preloadBars"])
+        except (KeyError, TypeError, ValueError) as error:
+            raise DataContractError(f"segments[{position}] is malformed: {error}") from error
+        if not 0 <= from_index <= to_index < bar_count:
+            raise DataContractError(
+                f"segments[{position}] range {from_index}..{to_index} falls outside the {bar_count} supplied bars"
+            )
+        if preload < 2:
+            raise DataContractError(f"segments[{position}].preloadBars must be at least 2")
+        # An evaluation bar has to remain after the warm-up prefix, or the segment
+        # measures nothing while still reporting a completed run.
+        if to_index - from_index + 1 <= preload:
+            raise DataContractError(
+                f"segments[{position}] holds {to_index - from_index + 1} bars, which is not more than its {preload} preloaded bars"
+            )
+        segments.append(
+            {"name": name, "fromIndex": from_index, "toIndex": to_index, "preloadBars": preload}
+        )
+    return segments
+
+
+def _parse_candidates(value: Any) -> list[dict[str, Any]]:
+    if not isinstance(value, list) or not value:
+        raise DataContractError("'candidates' must be a non-empty array")
+    candidates: list[dict[str, Any]] = []
+    seen: set[int] = set()
+    for position, row in enumerate(value):
+        if not isinstance(row, dict):
+            raise DataContractError(f"candidates[{position}] must be an object")
+        params = row.get("params")
+        if not isinstance(params, dict):
+            raise DataContractError(f"candidates[{position}].params must be an object")
+        try:
+            index = int(row["index"])
+        except (KeyError, TypeError, ValueError) as error:
+            raise DataContractError(f"candidates[{position}].index is malformed: {error}") from error
+        # Indices key the host's own rows, so a duplicate would overwrite one
+        # candidate's result with another's.
+        if index in seen:
+            raise DataContractError(f"candidates[{position}] repeats index {index}")
+        seen.add(index)
+        candidates.append({"index": index, "params": params})
+    return candidates
+
+
+def _parse_bars(value: Any) -> list[Bar]:
+    if not isinstance(value, list) or not value:
+        raise DataContractError("A backtest requires a non-empty 'bars' array")
+    bars: list[Bar] = []
+    previous_open: int | None = None
+    for index, row in enumerate(value):
+        if not isinstance(row, dict):
+            raise DataContractError(f"bars[{index}] must be an object")
+        try:
+            open_time = int(row["openTimeMs"])
+            close_time = int(row["closeTimeMs"])
+            bar = Bar(
+                open_time_ms=open_time,
+                close_time_ms=close_time,
+                open=float(row["open"]),
+                high=float(row["high"]),
+                low=float(row["low"]),
+                close=float(row["close"]),
+                volume=float(row["volume"]),
+                confirmed=True,
+            )
+        except (KeyError, TypeError, ValueError) as error:
+            raise DataContractError(f"bars[{index}] is malformed: {error}") from error
+        if close_time - open_time != ONE_MINUTE_MS:
+            raise DataContractError(f"bars[{index}] is not exactly one minute long")
+        if previous_open is not None and open_time != previous_open + ONE_MINUTE_MS:
+            raise DataContractError(
+                f"bars[{index}] breaks continuity: expected open {previous_open + ONE_MINUTE_MS}, got {open_time}"
+            )
+        previous_open = open_time
+        bars.append(bar)
+    return bars
+
+
+def _parse_intervals(value: Any) -> list[str]:
+    if value is None:
+        return ["1m"]
+    if not isinstance(value, list):
+        raise DataContractError("'intervals' must be an array of interval names")
+    intervals = ["1m"]
+    for item in value:
+        name = str(item)
+        interval_ms(name)
+        if name not in intervals:
+            intervals.append(name)
+    return intervals
+
+
+def _parse_config(request: dict[str, Any]) -> RunConfig:
+    instrument_raw = request.get("instrument")
+    if not isinstance(instrument_raw, dict):
+        raise DataContractError("'instrument' is required")
+    instrument = Instrument(
+        inst_id=str(instrument_raw.get("instId") or ""),
+        contract_value=float(instrument_raw.get("contractValue", 1)),
+        lot_size=float(instrument_raw.get("lotSize", 1)),
+        min_size=float(instrument_raw.get("minSize", 1)),
+        tick_size=float(instrument_raw.get("tickSize", 0.1)),
+        contract_multiplier=float(instrument_raw.get("contractMultiplier", 1)),
+    )
+    if not instrument.inst_id:
+        raise DataContractError("instrument.instId is required")
+    # Every specification is required to be positive. A zero or negative value
+    # would silently produce nonsense position sizes rather than failing, and a
+    # backtest reporting confident numbers off a bad contract spec is worse than
+    # one that refuses to run.
+    for field, value in (
+        ("contractValue", instrument.contract_value),
+        ("contractMultiplier", instrument.contract_multiplier),
+        ("lotSize", instrument.lot_size),
+        ("minSize", instrument.min_size),
+    ):
+        if not value > 0:
+            raise DataContractError(f"instrument.{field} must be greater than zero")
+
+    costs_raw = request.get("costs") or {}
+    sizing_raw = request.get("sizing") or {}
+    leverage = float(sizing_raw.get("leverage", 10))
+    if not 1 <= leverage <= 125:
+        raise DataContractError("sizing.leverage must be between 1 and 125")
+    safety = float(sizing_raw.get("marginSafetyMultiplier", 1))
+    if not 1 <= safety <= 20:
+        raise DataContractError("sizing.marginSafetyMultiplier must be between 1 and 20")
+
+    preload = int(request.get("preloadBars", 2))
+    if preload < 2:
+        raise DataContractError("preloadBars must be at least 2 so an action has a following open to fill at")
+    initial_equity = float(request.get("initialEquityUsdt", 10_000))
+    if initial_equity <= 0:
+        raise DataContractError("initialEquityUsdt must be greater than zero")
+
+    return RunConfig(
+        instrument=instrument,
+        initial_equity_usdt=initial_equity,
+        costs=Costs(
+            taker_fee_rate=float(costs_raw.get("takerFeeRate", 0.0005)),
+            maker_fee_rate=float(costs_raw.get("makerFeeRate", 0.0002)),
+            entry_slippage_bps=float(costs_raw.get("entrySlippageBps", 1.0)),
+            exit_slippage_bps=float(costs_raw.get("exitSlippageBps", 1.0)),
+        ),
+        sizing=Sizing(
+            leverage=leverage,
+            margin_safety_multiplier=safety,
+            entry_budget_usdt=(
+                None if sizing_raw.get("entryBudgetUsdt") is None else float(sizing_raw["entryBudgetUsdt"])
+            ),
+            entry_budget_pct=float(sizing_raw.get("entryBudgetPct", 0.20)),
+        ),
+        preload_bars=preload,
+        close_at_end=bool(request.get("closeAtEnd", True)),
+        limit_order_ttl_bars=int(request.get("limitOrderTtlBars", 60)),
+    )
+
+
+def _load_handlers(source: str) -> dict[str, object]:
+    namespace: dict[str, Any] = {"__builtins__": dict(_SAFE_BUILTINS)}
+    compiled = compile(source, "<strategy>", "exec")
+    exec(compiled, namespace)  # noqa: S102 - policy-validated strategy source
+    handlers: dict[str, object] = {}
+    for name in ("on_bar", "on_start"):
+        candidate = namespace.get(name)
+        if callable(candidate):
+            handlers[name] = candidate
+    if "on_bar" not in handlers:
+        raise StrategyError("A strategy must define on_bar(ctx)")
+    return handlers
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(payload, separators=(",", ":"), sort_keys=True))
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())