Add IBKR cash reserve policy

Author: Pigbibi

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

@@ -31,6 +31,8 @@ jobs:
       IBKR_RECONCILIATION_OUTPUT_PATH: ${{ vars.IBKR_RECONCILIATION_OUTPUT_PATH }}
       IBKR_DRY_RUN_ONLY: ${{ vars.IBKR_DRY_RUN_ONLY }}
       IBKR_PAPER_LIQUIDATE_ONLY: ${{ vars.IBKR_PAPER_LIQUIDATE_ONLY }}
+      IBKR_MIN_RESERVED_CASH_USD: ${{ vars.IBKR_MIN_RESERVED_CASH_USD }}
+      IBKR_RESERVED_CASH_RATIO: ${{ vars.IBKR_RESERVED_CASH_RATIO }}
       IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD: ${{ vars.IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD }}
       # Strategy-owned defaults continue to come from UsEquityStrategies; this workflow only syncs platform/runtime inputs.
       EXECUTION_REPORT_GCS_URI: ${{ vars.EXECUTION_REPORT_GCS_URI }}
@@ -331,6 +333,18 @@ jobs:
             remove_env_vars+=("IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD")
           fi
 
+          if [ -n "${IBKR_MIN_RESERVED_CASH_USD:-}" ]; then
+            env_pairs+=("IBKR_MIN_RESERVED_CASH_USD=${IBKR_MIN_RESERVED_CASH_USD}")
+          else
+            remove_env_vars+=("IBKR_MIN_RESERVED_CASH_USD")
+          fi
+
+          if [ -n "${IBKR_RESERVED_CASH_RATIO:-}" ]; then
+            env_pairs+=("IBKR_RESERVED_CASH_RATIO=${IBKR_RESERVED_CASH_RATIO}")
+          else
+            remove_env_vars+=("IBKR_RESERVED_CASH_RATIO")
+          fi
+
           if [ -n "${EXECUTION_REPORT_GCS_URI:-}" ]; then
             env_pairs+=("EXECUTION_REPORT_GCS_URI=${EXECUTION_REPORT_GCS_URI}")
           else

README.md

@@ -104,6 +104,8 @@ For IBKR, keep `paper` as a single account-group entry. If you later add live ac
 | `IBKR_FEATURE_SNAPSHOT_PATH` | Conditionally required | Required for snapshot-backed profiles such as `russell_1000_multi_factor_defensive`, `tech_communication_pullback_enhancement`, and `mega_cap_leader_rotation_top50_balanced`. Path to the latest feature snapshot file (`.csv`, `.json`, `.jsonl`, `.parquet`). |
 | `IBKR_STRATEGY_PLUGIN_MOUNTS_JSON` | No | Optional IBKR-side strategy plugin mount JSON. The plugin artifact controls mode; platform config must not set `mode`. |
 | `IBKR_MIN_ORDER_NOTIONAL_USD` | No | Minimum buy notional for limit buys; defaults to `50.0`. |
+| `IBKR_MIN_RESERVED_CASH_USD` | No | Platform-level minimum cash reserve in USD. Defaults to `0`; the effective reserve is the max of this floor and the effective cash reserve ratio. |
+| `IBKR_RESERVED_CASH_RATIO` | No | Platform-level minimum cash reserve ratio in `[0,1]`. When unset, IBKR keeps the strategy/runtime `execution_cash_reserve_ratio`; when set, it can raise but not lower that strategy ratio. |
 | `IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD` | No | Safe-haven target values below this USD amount are kept as cash instead of buying BOXX/BIL. Defaults to `1000.0`. |
 | `IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME` | Yes for Cloud Run | Secret Manager secret name for account-group config JSON. Recommended production source. |
 | `IB_ACCOUNT_GROUP_CONFIG_JSON` | No | Local/dev JSON fallback for account-group config. Not recommended for production Cloud Run. |
@@ -219,7 +221,7 @@ Recommended setup:
   - `STRATEGY_PROFILE` (set explicitly to one enabled profile, such as `soxl_soxx_trend_income`)
   - `ACCOUNT_GROUP` (recommended: `paper`)
   - `IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME`
-  - Optional: `IBKR_STRATEGY_PLUGIN_MOUNTS_JSON`, `IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD`
+  - Optional: `IBKR_STRATEGY_PLUGIN_MOUNTS_JSON`, `IBKR_MIN_RESERVED_CASH_USD`, `IBKR_RESERVED_CASH_RATIO`, `IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD`
   - `GLOBAL_TELEGRAM_CHAT_ID`
   - `NOTIFY_LANG`
 - **Repository Secrets**
@@ -341,6 +343,8 @@ IBKR 账户
 | `IBKR_FEATURE_SNAPSHOT_PATH` | 条件必填 | `russell_1000_multi_factor_defensive`、`tech_communication_pullback_enhancement`、`mega_cap_leader_rotation_top50_balanced` 等快照策略需要。指向最新特征快照文件（`.csv`、`.json`、`.jsonl`、`.parquet`）。 |
 | `IBKR_STRATEGY_PLUGIN_MOUNTS_JSON` | 否 | 可选的 IBKR 侧策略插件挂载 JSON。插件 artifact 自带模式；平台配置不要设置 `mode`。 |
 | `IBKR_MIN_ORDER_NOTIONAL_USD` | 否 | 限价买入的最小名义金额；默认 `50.0`。 |
+| `IBKR_MIN_RESERVED_CASH_USD` | 否 | 平台级最低预留现金 USD。默认 `0`；实际预留取该下限和有效预留现金比例中的最大值。 |
+| `IBKR_RESERVED_CASH_RATIO` | 否 | 平台级最低预留现金比例，取值 `[0,1]`。不设置时沿用策略/运行配置里的 `execution_cash_reserve_ratio`；设置后只会抬高，不会降低策略比例。 |
 | `IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD` | 否 | `BOXX`/`BIL` 等避险标的目标金额低于该 USD 门槛时保留现金，不买入。默认 `1000.0`。 |
 | `IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME` | Cloud Run 建议必填 | 账号组配置 JSON 在 Secret Manager 里的密钥名。生产环境推荐使用。 |
 | `IB_ACCOUNT_GROUP_CONFIG_JSON` | 否 | 本地开发用的账号组配置 JSON fallback。不建议在生产 Cloud Run 直接使用。 |
@@ -422,7 +426,7 @@ IB_GATEWAY_IP_MODE=internal
   - `STRATEGY_PROFILE`（显式设置为任一已启用 profile，例如 `soxl_soxx_trend_income`）
   - `ACCOUNT_GROUP`（建议设为 `paper`）
   - `IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME`
-  - 可选：`IBKR_STRATEGY_PLUGIN_MOUNTS_JSON`、`IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD`
+  - 可选：`IBKR_STRATEGY_PLUGIN_MOUNTS_JSON`、`IBKR_MIN_RESERVED_CASH_USD`、`IBKR_RESERVED_CASH_RATIO`、`IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD`
   - `GLOBAL_TELEGRAM_CHAT_ID`
   - `NOTIFY_LANG`
 - **仓库级 Secrets**

application/execution_service.py

@@ -603,6 +603,7 @@ def execute_rebalance(
     rebalance_threshold_ratio,
     limit_buy_premium,
     sell_settle_delay_sec,
+    cash_reserve_floor_usd=0.0,
     quantity_step=1.0,
     min_order_notional=50.0,
     safe_haven_cash_substitute_threshold_usd=DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD,
@@ -664,7 +665,10 @@ def execute_rebalance(
         execution_summary["no_op_reason"] = "no_equity"
         return _finalize_result([translator("no_equity")], execution_summary, return_summary=return_summary)
 
-    reserved = equity * cash_reserve_ratio
+    reserved = max(
+        float(equity) * float(cash_reserve_ratio or 0.0),
+        max(0.0, float(cash_reserve_floor_usd or 0.0)),
+    )
     investable = equity - reserved
     target_weights, substituted_safe_haven_symbols = _apply_safe_haven_cash_substitution_to_weights(
         target_weights,

application/runtime_broker_adapters.py

@@ -36,6 +36,7 @@ class IBKRRuntimeBrokerAdapters:
     account_ids: tuple[str, ...]
     dry_run_only: bool
     cash_reserve_ratio: float
+    cash_reserve_floor_usd: float
     rebalance_threshold_ratio: float
     limit_buy_premium: float
     quantity_step: float
@@ -157,6 +158,7 @@ def execute_rebalance(
             account_ids=self.account_ids,
             dry_run_only=self.dry_run_only,
             cash_reserve_ratio=self.cash_reserve_ratio,
+            cash_reserve_floor_usd=self.cash_reserve_floor_usd,
             rebalance_threshold_ratio=self.rebalance_threshold_ratio,
             limit_buy_premium=self.limit_buy_premium,
             quantity_step=self.quantity_step,
@@ -243,6 +245,7 @@ def build_runtime_broker_adapters(
     account_ids: tuple[str, ...],
     dry_run_only: bool,
     cash_reserve_ratio: float,
+    cash_reserve_floor_usd: float,
     rebalance_threshold_ratio: float,
     limit_buy_premium: float,
     quantity_step: float,
@@ -279,6 +282,7 @@ def build_runtime_broker_adapters(
         account_ids=tuple(account_ids),
         dry_run_only=bool(dry_run_only),
         cash_reserve_ratio=float(cash_reserve_ratio),
+        cash_reserve_floor_usd=float(cash_reserve_floor_usd),
         rebalance_threshold_ratio=float(rebalance_threshold_ratio),
         limit_buy_premium=float(limit_buy_premium),
         quantity_step=float(quantity_step),

main.py

@@ -234,6 +234,7 @@ def _env_flag(name: str) -> bool:
 NOTIFY_LANG = RUNTIME_SETTINGS.notify_lang
 
 CASH_RESERVE_RATIO = STRATEGY_RUNTIME.cash_reserve_ratio
+CASH_RESERVE_FLOOR_USD = getattr(STRATEGY_RUNTIME, "cash_reserve_floor_usd", 0.0)
 REBALANCE_THRESHOLD_RATIO = 0.02
 LIMIT_BUY_PREMIUM = 1.005
 SELL_SETTLE_DELAY_SEC = 3
@@ -323,6 +324,7 @@ def build_broker_adapters():
         account_ids=tuple(ACCOUNT_IDS),
         dry_run_only=RUNTIME_SETTINGS.dry_run_only,
         cash_reserve_ratio=CASH_RESERVE_RATIO,
+        cash_reserve_floor_usd=CASH_RESERVE_FLOOR_USD,
         rebalance_threshold_ratio=REBALANCE_THRESHOLD_RATIO,
         limit_buy_premium=LIMIT_BUY_PREMIUM,
         quantity_step=RUNTIME_SETTINGS.quantity_step,

runtime_config_support.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import math
 import os
 from dataclasses import dataclass
 from pathlib import Path
@@ -24,6 +25,7 @@
 from us_equity_strategies import get_strategy_catalog
 
 DEFAULT_ACCOUNT_GROUP = "default"
+DEFAULT_RESERVED_CASH_FLOOR_USD = 0.0
 DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD = 1000.0
 
 
@@ -60,6 +62,8 @@ class PlatformRuntimeSettings:
     dry_run_only: bool
     quantity_step: float = 1.0
     min_order_notional: float = 50.0
+    reserved_cash_floor_usd: float = DEFAULT_RESERVED_CASH_FLOOR_USD
+    reserved_cash_ratio: float | None = None
     safe_haven_cash_substitute_threshold_usd: float = DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD
     account_group: str = DEFAULT_ACCOUNT_GROUP
     service_name: str | None = None
@@ -153,6 +157,11 @@ def load_platform_runtime_settings(
             "IBKR_MIN_ORDER_NOTIONAL_USD",
             default=50.0,
         ),
+        reserved_cash_floor_usd=resolve_non_negative_float_env(
+            "IBKR_MIN_RESERVED_CASH_USD",
+            default=DEFAULT_RESERVED_CASH_FLOOR_USD,
+        ),
+        reserved_cash_ratio=resolve_optional_ratio_env("IBKR_RESERVED_CASH_RATIO"),
         safe_haven_cash_substitute_threshold_usd=max(
             0.0,
             resolve_float_env(
@@ -182,6 +191,25 @@ def resolve_strategy_profile(raw_value: str | None) -> str:
     ).profile
 
 
+def resolve_non_negative_float_env(name: str, *, default: float) -> float:
+    value = resolve_float_env(os.environ, name, default=default)
+    if not math.isfinite(value):
+        raise ValueError(f"{name} must be finite, got {value}")
+    if value < 0.0:
+        raise ValueError(f"{name} must be non-negative, got {value}")
+    return float(value)
+
+
+def resolve_optional_ratio_env(name: str) -> float | None:
+    raw_value = os.getenv(name)
+    if raw_value is None or str(raw_value).strip() == "":
+        return None
+    value = resolve_non_negative_float_env(name, default=0.0)
+    if value > 1.0:
+        raise ValueError(f"{name} must be in [0,1], got {value}")
+    return value
+
+
 def resolve_account_group(raw_value: str | None) -> str:
     value = (raw_value or "").strip()
     if not value:

scripts/print_strategy_switch_env_plan.py

@@ -69,6 +69,8 @@ def build_switch_plan(profile: str) -> dict[str, object]:
     ]
     optional_env = [
         "IBKR_DRY_RUN_ONLY",
+        "IBKR_MIN_RESERVED_CASH_USD",
+        "IBKR_RESERVED_CASH_RATIO",
         "IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD",
     ]
     remove_if_present: list[str] = []

strategy_runtime.py

@@ -59,6 +59,7 @@ class LoadedStrategyRuntime:
     merged_runtime_config: Mapping[str, Any] = field(default_factory=dict)
     status_icon: str = "🐤"
     cash_reserve_ratio: float = DEFAULT_CASH_RESERVE_RATIO
+    cash_reserve_floor_usd: float = 0.0
     logger: Callable[[str], None] = print
 
     @property
@@ -631,18 +632,26 @@ def load_strategy_runtime(
 
     merged_runtime_config = dict(entrypoint.manifest.default_config)
     merged_runtime_config.update(runtime_config)
+    strategy_cash_reserve_ratio = float(
+        merged_runtime_config.get(
+            "execution_cash_reserve_ratio",
+            DEFAULT_CASH_RESERVE_RATIO,
+        )
+    )
+    platform_cash_reserve_ratio = runtime_settings.reserved_cash_ratio
+    if platform_cash_reserve_ratio is not None:
+        strategy_cash_reserve_ratio = max(
+            strategy_cash_reserve_ratio,
+            float(platform_cash_reserve_ratio),
+        )
     return LoadedStrategyRuntime(
         entrypoint=entrypoint,
         runtime_adapter=runtime_adapter,
         runtime_settings=runtime_settings,
         runtime_config=runtime_config,
         merged_runtime_config=merged_runtime_config,
         status_icon=runtime_adapter.status_icon,
-        cash_reserve_ratio=float(
-            merged_runtime_config.get(
-                "execution_cash_reserve_ratio",
-                DEFAULT_CASH_RESERVE_RATIO,
-            )
-        ),
+        cash_reserve_ratio=strategy_cash_reserve_ratio,
+        cash_reserve_floor_usd=float(runtime_settings.reserved_cash_floor_usd or 0.0),
         logger=logger,
     )

tests/test_execution_service.py

@@ -130,6 +130,41 @@ def fake_fetch_quote_snapshots(_ib, symbols):
     assert any(log.startswith("buy VOO") for log in trade_logs)
 
 
+def test_execute_rebalance_uses_reserved_cash_floor_when_higher(tmp_path):
+    class FakeIB:
+        def openTrades(self):
+            return []
+
+        def fills(self):
+            return []
+
+        def accountValues(self):
+            return [SimpleNamespace(tag="AvailableFunds", currency="USD", value="1000")]
+
+    _trade_logs, summary = execute_rebalance(
+        FakeIB(),
+        {},
+        {},
+        {"equity": 1000.0, "buying_power": 1000.0},
+        fetch_quote_snapshots=lambda _ib, _symbols: {},
+        submit_order_intent=lambda _ib, _intent: None,
+        order_intent_cls=OrderIntent,
+        translator=translate,
+        strategy_symbols=[],
+        signal_metadata=_signal_metadata({}),
+        dry_run_only=True,
+        cash_reserve_ratio=0.03,
+        cash_reserve_floor_usd=250.0,
+        rebalance_threshold_ratio=0.02,
+        limit_buy_premium=1.005,
+        sell_settle_delay_sec=0,
+        execution_lock_dir=tmp_path,
+        return_summary=True,
+    )
+
+    assert summary["cash_reserve_dollars"] == 250.0
+
+
 def test_execute_rebalance_projects_unbuyable_weight_target_to_zero(tmp_path, monkeypatch):
     class FakeIB:
         def openTrades(self):

tests/test_runtime_config_support.py

@@ -6,9 +6,12 @@
 import pytest
 
 from runtime_config_support import (
+    DEFAULT_RESERVED_CASH_FLOOR_USD,
     DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD,
     load_platform_runtime_settings,
     parse_account_group_configs,
+    resolve_non_negative_float_env,
+    resolve_optional_ratio_env,
 )
 from strategy_registry import (
     IBKR_PLATFORM,
@@ -122,6 +125,8 @@ def test_load_platform_runtime_settings_uses_minimal_group_config(monkeypatch):
     assert settings.dry_run_only is False
     assert settings.quantity_step == 1.0
     assert settings.min_order_notional == 50.0
+    assert settings.reserved_cash_floor_usd == DEFAULT_RESERVED_CASH_FLOOR_USD
+    assert settings.reserved_cash_ratio is None
     assert settings.safe_haven_cash_substitute_threshold_usd == DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD
     assert settings.account_group == "paper"
     assert settings.service_name is None
@@ -209,6 +214,48 @@ def test_load_platform_runtime_settings_uses_whole_share_quantity_step(monkeypat
     assert settings.safe_haven_cash_substitute_threshold_usd == 750.0
 
 
+def test_load_platform_runtime_settings_reads_reserved_cash_policy(monkeypatch):
+    monkeypatch.setenv("RUNTIME_TARGET_JSON", runtime_target_json(SAMPLE_STRATEGY_PROFILE))
+    monkeypatch.setenv("ACCOUNT_GROUP", "paper")
+    monkeypatch.setenv("IB_ACCOUNT_GROUP_CONFIG_JSON", MINIMAL_GROUP_JSON)
+    monkeypatch.setenv("IBKR_MIN_RESERVED_CASH_USD", "250")
+    monkeypatch.setenv("IBKR_RESERVED_CASH_RATIO", "0.025")
+
+    settings = load_platform_runtime_settings(project_id_resolver=lambda: "project-1")
+
+    assert settings.reserved_cash_floor_usd == 250.0
+    assert settings.reserved_cash_ratio == 0.025
+
+
+def test_load_platform_runtime_settings_rejects_invalid_reserved_cash_ratio(monkeypatch):
+    monkeypatch.setenv("IBKR_RESERVED_CASH_RATIO", "1.25")
+
+    with pytest.raises(ValueError, match="IBKR_RESERVED_CASH_RATIO"):
+        resolve_optional_ratio_env("IBKR_RESERVED_CASH_RATIO")
+
+
+@pytest.mark.parametrize("raw_value", ["nan", "inf", "-inf"])
+def test_load_platform_runtime_settings_rejects_non_finite_reserved_cash_floor(
+    monkeypatch,
+    raw_value,
+):
+    monkeypatch.setenv("IBKR_MIN_RESERVED_CASH_USD", raw_value)
+
+    with pytest.raises(ValueError, match="IBKR_MIN_RESERVED_CASH_USD must be finite"):
+        resolve_non_negative_float_env("IBKR_MIN_RESERVED_CASH_USD", default=0.0)
+
+
+@pytest.mark.parametrize("raw_value", ["nan", "inf", "-inf"])
+def test_load_platform_runtime_settings_rejects_non_finite_reserved_cash_ratio(
+    monkeypatch,
+    raw_value,
+):
+    monkeypatch.setenv("IBKR_RESERVED_CASH_RATIO", raw_value)
+
+    with pytest.raises(ValueError, match="IBKR_RESERVED_CASH_RATIO must be finite"):
+        resolve_optional_ratio_env("IBKR_RESERVED_CASH_RATIO")
+
+
 def test_load_platform_runtime_settings_reads_ibkr_strategy_plugin_mounts(monkeypatch):
     mount_config = '{"strategy_plugins":[{"strategy":"soxl_soxx_trend_income","plugin":"crisis_response_shadow","signal_path":"gs://bucket/latest_signal.json"}]}'
     monkeypatch.setenv("RUNTIME_TARGET_JSON", runtime_target_json("soxl_soxx_trend_income"))
@@ -431,6 +478,8 @@ def test_print_strategy_switch_env_plan_for_tqqq_growth_income():
     assert plan["requires_strategy_config_path"] is False
     assert json.loads(plan["set_env"]["RUNTIME_TARGET_JSON"])["strategy_profile"] == "tqqq_growth_income"
     assert "ACCOUNT_GROUP" in plan["keep_env"]
+    assert "IBKR_MIN_RESERVED_CASH_USD" in plan["optional_env"]
+    assert "IBKR_RESERVED_CASH_RATIO" in plan["optional_env"]
     assert "IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD" in plan["optional_env"]
     assert "IBKR_FEATURE_SNAPSHOT_PATH" in plan["remove_if_present"]