Add per-platform cash-only execution and smooth deleverage switching. (#145)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Pigbibi

.github/workflows/sync-cloud-run-env.yml

@@ -130,6 +130,7 @@ jobs:
       INCOME_LAYER_ENABLED: ${{ vars.INCOME_LAYER_ENABLED }}
       INCOME_LAYER_START_USD: ${{ vars.INCOME_LAYER_START_USD }}
       INCOME_LAYER_MAX_RATIO: ${{ vars.INCOME_LAYER_MAX_RATIO }}
+      FIRSTRADE_CASH_ONLY_EXECUTION: ${{ vars.FIRSTRADE_CASH_ONLY_EXECUTION }}
       CASH_ONLY_EXECUTION: ${{ vars.CASH_ONLY_EXECUTION }}
       DCA_MODE: ${{ vars.DCA_MODE }}
       DCA_BASE_INVESTMENT_USD: ${{ vars.DCA_BASE_INVESTMENT_USD }}

decision_mapper.py

@@ -4,7 +4,10 @@
 from dataclasses import replace
 from typing import Any
 
-from us_equity_strategies.cash_only_equity import build_portfolio_inputs_from_snapshot
+from us_equity_strategies.cash_only_equity import (
+    build_portfolio_inputs_from_snapshot,
+    resolve_weight_translation_equity,
+)
 from quant_platform_kit.strategy_contracts import (
     PositionTarget,
     StrategyContractValidationError,
@@ -307,32 +310,39 @@ def _normalize_to_value_decision(
     *,
     portfolio_inputs,
     runtime_metadata: Mapping[str, Any] | None,
+    cash_only_execution: bool = True,
 ) -> tuple[StrategyDecision, ValueTargetExecutionAnnotations | None]:
     target_mode = resolve_decision_target_mode(decision)
     no_execute = "no_execute" in set(decision.risk_flags)
     if target_mode == "value" and not no_execute:
         return decision, None
     if target_mode == "weight" and not no_execute:
-        total_equity = float(portfolio_inputs.total_equity)
-        if total_equity <= 0.0:
+        total_equity, block_execution, deleverage_mode = resolve_weight_translation_equity(
+            portfolio_inputs,
+            cash_only_execution=cash_only_execution,
+        )
+        if block_execution:
             diagnostics = {
                 **dict(runtime_metadata or {}),
                 **dict(decision.diagnostics),
                 "execution_blocked_reason": "non_positive_total_equity",
-                "portfolio_total_equity": total_equity,
+                "portfolio_total_equity": float(portfolio_inputs.total_equity),
             }
             return _build_zero_equity_no_execute_decision(
                 decision,
                 portfolio_inputs=portfolio_inputs,
                 diagnostics=diagnostics,
             ), _build_weight_translation_annotations(
                 decision,
-                total_equity=total_equity,
+                total_equity=float(portfolio_inputs.total_equity),
                 liquid_cash=float(portfolio_inputs.liquid_cash),
                 runtime_metadata=runtime_metadata,
             )
+        diagnostics = dict(decision.diagnostics)
+        if deleverage_mode:
+            diagnostics["cash_only_deleverage_mode"] = True
         translated = translate_decision_to_target_mode(
-            decision,
+            replace(decision, diagnostics=diagnostics) if deleverage_mode else decision,
             target_mode="value",
             total_equity=total_equity,
         )
@@ -416,6 +426,7 @@ def map_strategy_decision_to_plan(
         decision,
         portfolio_inputs=portfolio_inputs,
         runtime_metadata=runtime_metadata,
+        cash_only_execution=cash_only_execution,
     )
     annotations = translated_annotations or _build_annotations(
         normalized_decision,

requirements.txt

@@ -1,8 +1,8 @@
 flask
 gunicorn
 firstrade==0.0.39
-quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@bc5351d3567b2bb60416dc969062c37eedbbf65e
-us-equity-strategies @ git+https://github.com/QuantStrategyLab/UsEquityStrategies.git@5aa949df2962b70d6fdb11c33f7d150492795f16
+quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@7b6e3ce33e6563db4794fa7b865db9ec428dc478
+us-equity-strategies @ git+https://github.com/QuantStrategyLab/UsEquityStrategies.git@78172596f64c6423a1ab304e53e5d0e18a865175
 google-cloud-storage
 google-auth
 requests

runtime_config_support.py

@@ -8,6 +8,7 @@
 
 from quant_platform_kit.common.runtime_config import (
     resolve_bool_value,
+    resolve_cash_only_execution_env,
     resolve_optional_float_env,
     resolve_strategy_runtime_path_settings,
 )
@@ -165,7 +166,10 @@ def load_platform_runtime_settings(
         tg_chat_id=os.getenv("GLOBAL_TELEGRAM_CHAT_ID"),
         dry_run_only=dry_run_only,
         runtime_target_enabled=_runtime_target_enabled_env(),
-        cash_only_execution=_resolve_cash_only_execution_env(),
+        cash_only_execution=resolve_cash_only_execution_env(
+            os.environ,
+            platform_env_prefix="FIRSTRADE",
+        ),
         live_trading_enabled=resolve_bool_value(os.getenv("FIRSTRADE_ENABLE_LIVE_TRADING")),
         run_strategy_on_http=resolve_bool_value(os.getenv("FIRSTRADE_RUN_STRATEGY_ON_HTTP")),
         live_order_ack=resolve_bool_value(os.getenv("FIRSTRADE_LIVE_ORDER_ACK")),
@@ -370,11 +374,6 @@ def _runtime_target_enabled_env() -> bool:
     return True if value is None else value
 
 
-def _resolve_cash_only_execution_env(name: str = "CASH_ONLY_EXECUTION") -> bool:
-    value = _optional_bool_env(name)
-    return True if value is None else value
-
-
 def _optional_ratio_env(name: str) -> float | None:
     value = resolve_optional_float_env(os.environ, name)
     if value is None:

scripts/build_cloud_run_env_sync_plan.py

@@ -76,6 +76,7 @@ def _should_add_local_src(candidate: Path) -> bool:
     "FIRSTRADE_MAX_ORDER_NOTIONAL_USD",
     "FIRSTRADE_MIN_RESERVED_CASH_USD",
     "FIRSTRADE_RESERVED_CASH_RATIO",
+    "FIRSTRADE_CASH_ONLY_EXECUTION",
     "FIRSTRADE_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD",
     "FIRSTRADE_SMOKE_SYMBOL",
     "FIRSTRADE_FEATURE_SNAPSHOT_PATH",

tests/test_runtime_config_support.py

@@ -108,6 +108,11 @@ def test_cash_only_execution_defaults_true_and_loads_override(monkeypatch):
     assert default_settings.cash_only_execution is True
 
     monkeypatch.setenv("CASH_ONLY_EXECUTION", "false")
+    legacy_settings = load_platform_runtime_settings(project_id_resolver=lambda: "project-1")
+    assert legacy_settings.cash_only_execution is False
+
+    monkeypatch.delenv("CASH_ONLY_EXECUTION", raising=False)
+    monkeypatch.setenv("FIRSTRADE_CASH_ONLY_EXECUTION", "false")
     disabled_settings = load_platform_runtime_settings(project_id_resolver=lambda: "project-1")
     assert disabled_settings.cash_only_execution is False