Enable mega cap dynamic top20 profile

Author: Pigbibi

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

@@ -57,12 +57,16 @@ jobs:
             NOTIFY_LANG
           )
 
-          if [ "${STRATEGY_PROFILE:-}" = "russell_1000_multi_factor_defensive" ] || [ "${STRATEGY_PROFILE:-}" = "tech_communication_pullback_enhancement" ] || [ "${STRATEGY_PROFILE:-}" = "qqq_tech_enhancement" ]; then
+          if [ "${STRATEGY_PROFILE:-}" = "russell_1000_multi_factor_defensive" ] || [ "${STRATEGY_PROFILE:-}" = "tech_communication_pullback_enhancement" ] || [ "${STRATEGY_PROFILE:-}" = "qqq_tech_enhancement" ] || [ "${STRATEGY_PROFILE:-}" = "mega_cap_leader_rotation_dynamic_top20" ]; then
             required_vars+=(IBKR_FEATURE_SNAPSHOT_PATH)
           fi
 
+          if [ "${STRATEGY_PROFILE:-}" = "tech_communication_pullback_enhancement" ] || [ "${STRATEGY_PROFILE:-}" = "qqq_tech_enhancement" ] || [ "${STRATEGY_PROFILE:-}" = "mega_cap_leader_rotation_dynamic_top20" ]; then
+            required_vars+=(IBKR_FEATURE_SNAPSHOT_MANIFEST_PATH)
+          fi
+
           if [ "${STRATEGY_PROFILE:-}" = "tech_communication_pullback_enhancement" ] || [ "${STRATEGY_PROFILE:-}" = "qqq_tech_enhancement" ]; then
-            required_vars+=(IBKR_FEATURE_SNAPSHOT_MANIFEST_PATH IBKR_STRATEGY_CONFIG_PATH IBKR_RECONCILIATION_OUTPUT_PATH)
+            required_vars+=(IBKR_STRATEGY_CONFIG_PATH IBKR_RECONCILIATION_OUTPUT_PATH)
           fi
 
           missing_vars=()

README.md

@@ -39,6 +39,7 @@ The mainline runtime now follows one path only:
 - `tqqq_growth_income`
 - `soxl_soxx_trend_income`
 - `tech_communication_pullback_enhancement`
+- `mega_cap_leader_rotation_dynamic_top20`
 
 
 **IBKR profile status**
@@ -50,6 +51,7 @@ The mainline runtime now follows one path only:
 | `tqqq_growth_income` | TQQQ Growth Income | Yes | Yes | No | No | `us_equity` | enabled value-mode alternative |
 | `soxl_soxx_trend_income` | SOXL/SOXX Semiconductor Trend Income | Yes | Yes | No | No | `us_equity` | current IBKR live line |
 | `tech_communication_pullback_enhancement` | Tech/Communication Pullback Enhancement | Yes | Yes | No | No | `us_equity` | enabled feature-snapshot alternative |
+| `mega_cap_leader_rotation_dynamic_top20` | Mega Cap Leader Rotation Dynamic Top20 | Yes | Yes | No | No | `us_equity` | enabled concentrated leader rotation |
 
 Check the current matrix locally:
 
@@ -94,9 +96,9 @@ The selected `ACCOUNT_GROUP` is now the runtime identity. Keep broker-specific i
 |----------|----------|-------------|
 | `IB_GATEWAY_ZONE` | Optional fallback | GCE zone (for example `us-central1-a`). Recommended to keep in the selected account-group entry; this env var is only a transition fallback. |
 | `IB_GATEWAY_IP_MODE` | Optional fallback | `internal` (default) or `external`. Recommended to keep in the selected account-group entry; this env var is only a transition fallback. |
-| `STRATEGY_PROFILE` | Yes | Strategy profile selector. Supported `us_equity` values: `global_etf_rotation`, `russell_1000_multi_factor_defensive`, `tqqq_growth_income`, `soxl_soxx_trend_income`, `tech_communication_pullback_enhancement` |
+| `STRATEGY_PROFILE` | Yes | Strategy profile selector. Supported `us_equity` values: `global_etf_rotation`, `russell_1000_multi_factor_defensive`, `tqqq_growth_income`, `soxl_soxx_trend_income`, `tech_communication_pullback_enhancement`, `mega_cap_leader_rotation_dynamic_top20` |
 | `ACCOUNT_GROUP` | Yes | Account-group selector. No default fallback. |
-| `IBKR_FEATURE_SNAPSHOT_PATH` | Conditionally required | Required for snapshot-backed profiles such as `russell_1000_multi_factor_defensive` and `tech_communication_pullback_enhancement`. Path to the latest feature snapshot file (`.csv`, `.json`, `.jsonl`, `.parquet`). |
+| `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_dynamic_top20`. Path to the latest feature snapshot file (`.csv`, `.json`, `.jsonl`, `.parquet`). |
 | `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. |
 | `TELEGRAM_TOKEN` | Yes | Telegram bot token. For Cloud Run, prefer a Secret Manager reference instead of a literal env var. |
@@ -155,6 +157,16 @@ GLOBAL_TELEGRAM_CHAT_ID=<telegram-chat-id>
 NOTIFY_LANG=zh
 ```
 
+```bash
+STRATEGY_PROFILE=mega_cap_leader_rotation_dynamic_top20
+ACCOUNT_GROUP=default
+IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME=ibkr-account-groups
+IBKR_FEATURE_SNAPSHOT_PATH=/var/data/mega_cap_leader_rotation_dynamic_top20_feature_snapshot_latest.csv
+IBKR_FEATURE_SNAPSHOT_MANIFEST_PATH=/var/manifests/mega_cap_leader_rotation_dynamic_top20_feature_snapshot_latest.csv.manifest.json
+GLOBAL_TELEGRAM_CHAT_ID=<telegram-chat-id>
+NOTIFY_LANG=zh
+```
+
 This shared-config mode is only for the **IBKR pair** (`InteractiveBrokersPlatform` + `IBKRGatewayManager`). It is not meant to become a global secret bundle for unrelated quant repos. Across multiple quant projects, the only broadly reusable runtime settings are usually `GLOBAL_TELEGRAM_CHAT_ID` and `NOTIFY_LANG`.
 
 Recommended account-group config payload:
@@ -274,7 +286,7 @@ gcloud run services update ibkr-quant \
 
 IBKR runtime 负责把共享的 `us_equity` 策略档位部署到 GCP Cloud Run，并连接 GCE 上的 IB Gateway 执行。策略逻辑、策略频率、标的池、参数和研究/回测说明都放在 `UsEquityStrategies`；这个仓库只维护 IBKR 运行时、账号组、Gateway 连接、下单和通知。
 
-当前 `global_etf_rotation`、`russell_1000_multi_factor_defensive`、`tqqq_growth_income`、`soxl_soxx_trend_income` 和 `tech_communication_pullback_enhancement` 的策略实现都来自 `UsEquityStrategies`。
+当前 `global_etf_rotation`、`russell_1000_multi_factor_defensive`、`tqqq_growth_income`、`soxl_soxx_trend_income`、`tech_communication_pullback_enhancement` 和 `mega_cap_leader_rotation_dynamic_top20` 的策略实现都来自 `UsEquityStrategies`。
 
 完整策略说明现在放在 [`UsEquityStrategies`](https://github.com/QuantStrategyLab/UsEquityStrategies)。这个 README 只保留 IBKR 运行时、profile 启用状态、部署和凭据说明。
 
@@ -315,7 +327,7 @@ IBKR 账户
 |------|------|------|
 | `IB_GATEWAY_ZONE` | 可选过渡项 | GCE zone（如 `us-central1-a`）。推荐直接放进选中的账号组配置里；这里只保留过渡 fallback。 |
 | `IB_GATEWAY_IP_MODE` | 可选过渡项 | `internal`（默认）或 `external`。推荐直接放进选中的账号组配置里；这里只保留过渡 fallback。 |
-| `STRATEGY_PROFILE` | 是 | 策略档位选择。当前可用的 `us_equity` 值：`global_etf_rotation`、`russell_1000_multi_factor_defensive`、`tqqq_growth_income`、`soxl_soxx_trend_income`、`tech_communication_pullback_enhancement` |
+| `STRATEGY_PROFILE` | 是 | 策略档位选择。当前可用的 `us_equity` 值：`global_etf_rotation`、`russell_1000_multi_factor_defensive`、`tqqq_growth_income`、`soxl_soxx_trend_income`、`tech_communication_pullback_enhancement`、`mega_cap_leader_rotation_dynamic_top20` |
 | `ACCOUNT_GROUP` | 是 | 账号组选择器，不再提供默认回退。 |
 | `IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME` | Cloud Run 建议必填 | 账号组配置 JSON 在 Secret Manager 里的密钥名。生产环境推荐使用。 |
 | `IB_ACCOUNT_GROUP_CONFIG_JSON` | 否 | 本地开发用的账号组配置 JSON fallback。不建议在生产 Cloud Run 直接使用。 |

configs/paper_mega_cap_leader_rotation_dynamic_top20.env.example

@@ -0,0 +1,8 @@
+# IBKR paper runtime switch: mega_cap_leader_rotation_dynamic_top20
+STRATEGY_PROFILE=mega_cap_leader_rotation_dynamic_top20
+ACCOUNT_GROUP=default
+IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME=ibkr-account-groups
+IBKR_FEATURE_SNAPSHOT_PATH=/var/data/mega_cap_leader_rotation_dynamic_top20_feature_snapshot_latest.csv
+IBKR_FEATURE_SNAPSHOT_MANIFEST_PATH=/var/manifests/mega_cap_leader_rotation_dynamic_top20_feature_snapshot_latest.csv.manifest.json
+GLOBAL_TELEGRAM_CHAT_ID=<telegram-chat-id>
+NOTIFY_LANG=zh

requirements.txt

@@ -1,7 +1,7 @@
 flask
 gunicorn
 quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@v0.7.15
-us-equity-strategies @ git+https://github.com/QuantStrategyLab/UsEquityStrategies.git@v0.7.21
+us-equity-strategies @ git+https://github.com/QuantStrategyLab/UsEquityStrategies.git@v0.7.22
 pandas
 numpy
 requests

strategy_registry.py

@@ -26,6 +26,7 @@
         "tech_communication_pullback_enhancement",
         "qqq_tech_enhancement",
         "global_etf_rotation",
+        "mega_cap_leader_rotation_dynamic_top20",
         "russell_1000_multi_factor_defensive",
         "soxl_soxx_trend_income",
         "tqqq_growth_income",

tests/test_runtime_config_support.py

@@ -154,6 +154,7 @@ def test_platform_supported_profiles_are_filtered_by_registry():
             "tqqq_growth_income",
             "tech_communication_pullback_enhancement",
             "global_etf_rotation",
+            "mega_cap_leader_rotation_dynamic_top20",
             "russell_1000_multi_factor_defensive",
         }
     )
@@ -166,6 +167,7 @@ def test_platform_eligible_profiles_are_exposed_by_capability_matrix():
             "tqqq_growth_income",
             "tech_communication_pullback_enhancement",
             "global_etf_rotation",
+            "mega_cap_leader_rotation_dynamic_top20",
             "russell_1000_multi_factor_defensive",
         }
     )
@@ -184,6 +186,23 @@ def test_load_platform_runtime_settings_accepts_tech_communication_pullback_enha
     assert settings.strategy_target_mode == "weight"
 
 
+def test_load_platform_runtime_settings_accepts_mega_cap_leader_rotation_dynamic_top20(monkeypatch):
+    monkeypatch.setenv("STRATEGY_PROFILE", "mega_cap_leader_rotation_dynamic_top20")
+    monkeypatch.setenv("ACCOUNT_GROUP", "default")
+    monkeypatch.setenv("IB_ACCOUNT_GROUP_CONFIG_JSON", MINIMAL_GROUP_JSON)
+    monkeypatch.setenv("IBKR_FEATURE_SNAPSHOT_PATH", "/tmp/mega.csv")
+    monkeypatch.setenv("IBKR_FEATURE_SNAPSHOT_MANIFEST_PATH", "/tmp/mega.csv.manifest.json")
+
+    settings = load_platform_runtime_settings(project_id_resolver=lambda: "project-1")
+
+    assert settings.strategy_profile == "mega_cap_leader_rotation_dynamic_top20"
+    assert settings.strategy_display_name == "Mega Cap Leader Rotation Dynamic Top20"
+    assert settings.strategy_target_mode == "weight"
+    assert settings.feature_snapshot_path == "/tmp/mega.csv"
+    assert settings.feature_snapshot_manifest_path == "/tmp/mega.csv.manifest.json"
+    assert settings.strategy_config_path is None
+
+
 def test_load_platform_runtime_settings_accepts_tqqq_growth_income(monkeypatch):
     monkeypatch.setenv("STRATEGY_PROFILE", "tqqq_growth_income")
     monkeypatch.setenv("ACCOUNT_GROUP", "default")
@@ -224,6 +243,7 @@ def test_platform_profile_status_matrix_matches_current_ibkr_rollout():
         "soxl_soxx_trend_income",
         "tqqq_growth_income",
         "tech_communication_pullback_enhancement",
+        "mega_cap_leader_rotation_dynamic_top20",
     }
     assert by_profile["global_etf_rotation"] == {
         "canonical_profile": "global_etf_rotation",
@@ -277,6 +297,10 @@ def test_print_strategy_profile_status_json_matches_registry():
     assert by_profile["tech_communication_pullback_enhancement"]["input_mode"] == "feature_snapshot"
     assert by_profile["tech_communication_pullback_enhancement"]["requires_snapshot_artifacts"] is True
     assert by_profile["tech_communication_pullback_enhancement"]["requires_strategy_config_path"] is True
+    assert by_profile["mega_cap_leader_rotation_dynamic_top20"]["profile_group"] == "snapshot_backed"
+    assert by_profile["mega_cap_leader_rotation_dynamic_top20"]["input_mode"] == "feature_snapshot"
+    assert by_profile["mega_cap_leader_rotation_dynamic_top20"]["requires_snapshot_artifacts"] is True
+    assert by_profile["mega_cap_leader_rotation_dynamic_top20"]["requires_strategy_config_path"] is False
     assert by_profile["russell_1000_multi_factor_defensive"]["requires_strategy_config_path"] is False
 
 
@@ -320,6 +344,26 @@ def test_print_strategy_switch_env_plan_for_tqqq_growth_income():
     assert "IBKR_FEATURE_SNAPSHOT_PATH" in plan["remove_if_present"]
 
 
+def test_print_strategy_switch_env_plan_for_mega_cap_feature_snapshot_profile():
+    result = subprocess.run(
+        [sys.executable, str(SWITCH_PLAN_SCRIPT_PATH), "--profile", "mega_cap_leader_rotation_dynamic_top20", "--json"],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+    plan = json.loads(result.stdout)
+    assert plan["canonical_profile"] == "mega_cap_leader_rotation_dynamic_top20"
+    assert plan["profile_group"] == "snapshot_backed"
+    assert plan["input_mode"] == "feature_snapshot"
+    assert plan["requires_snapshot_artifacts"] is True
+    assert plan["requires_strategy_config_path"] is False
+    assert plan["set_env"]["IBKR_FEATURE_SNAPSHOT_PATH"] == "<required>"
+    assert plan["set_env"]["IBKR_FEATURE_SNAPSHOT_MANIFEST_PATH"] == "<required>"
+    assert "IBKR_STRATEGY_CONFIG_PATH" in plan["remove_if_present"]
+    assert "IBKR_RECONCILIATION_OUTPUT_PATH" in plan["remove_if_present"]
+
+
 def test_print_strategy_switch_env_plan_for_feature_snapshot_profile():
     result = subprocess.run(
         [sys.executable, str(SWITCH_PLAN_SCRIPT_PATH), "--profile", "tech_communication_pullback_enhancement", "--json"],

tests/test_strategy_loader.py

@@ -53,6 +53,23 @@ def test_load_strategy_entrypoint_for_profile_resolves_tqqq_growth_income(monkey
     assert entrypoint.manifest.default_config["benchmark_symbol"] == "QQQ"
 
 
+def test_load_strategy_entrypoint_for_profile_resolves_mega_cap_dynamic_top20(monkeypatch):
+    try:
+        import pandas  # noqa: F401
+    except ModuleNotFoundError:
+        return
+
+    market_calendars_module = types.ModuleType("pandas_market_calendars")
+    market_calendars_module.get_calendar = lambda name: None
+    monkeypatch.setitem(sys.modules, "pandas_market_calendars", market_calendars_module)
+
+    entrypoint = load_strategy_entrypoint_for_profile("mega_cap_leader_rotation_dynamic_top20")
+
+    assert entrypoint.manifest.profile == "mega_cap_leader_rotation_dynamic_top20"
+    assert entrypoint.manifest.required_inputs == frozenset({"feature_snapshot"})
+    assert entrypoint.manifest.default_config["holdings_count"] == 4
+
+
 def test_load_strategy_entrypoint_for_profile_rejects_legacy_cash_buffer_profile(monkeypatch):
     try:
         import pandas  # noqa: F401
@@ -85,6 +102,24 @@ def test_load_strategy_runtime_adapter_for_profile_resolves_tech_communication_p
     assert adapter.snapshot_contract_version == "tech_communication_pullback_enhancement.feature_snapshot.v1"
 
 
+def test_load_strategy_runtime_adapter_for_profile_resolves_mega_cap_dynamic_top20(monkeypatch):
+    try:
+        import pandas  # noqa: F401
+    except ModuleNotFoundError:
+        return
+
+    market_calendars_module = types.ModuleType("pandas_market_calendars")
+    market_calendars_module.get_calendar = lambda name: None
+    monkeypatch.setitem(sys.modules, "pandas_market_calendars", market_calendars_module)
+
+    adapter = load_strategy_runtime_adapter_for_profile("mega_cap_leader_rotation_dynamic_top20")
+
+    assert adapter.status_icon == "👑"
+    assert adapter.available_inputs == frozenset({"feature_snapshot"})
+    assert adapter.require_snapshot_manifest is True
+    assert adapter.snapshot_contract_version == "mega_cap_leader_rotation_dynamic_top20.feature_snapshot.v1"
+
+
 def test_load_strategy_runtime_adapter_for_profile_resolves_global_etf_rotation_inputs(monkeypatch):
     market_calendars_module = types.ModuleType("pandas_market_calendars")
     market_calendars_module.get_calendar = lambda name: None

tests/test_sync_cloud_run_env_workflow.sh

@@ -43,7 +43,8 @@ grep -Fq 'STRATEGY_PROFILE=${STRATEGY_PROFILE}' "$workflow_file"
 grep -Fq 'ACCOUNT_GROUP=${ACCOUNT_GROUP}' "$workflow_file"
 grep -Fq 'IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME=${IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME}' "$workflow_file"
 grep -Fq 'required_vars+=(IBKR_FEATURE_SNAPSHOT_PATH)' "$workflow_file"
-grep -Fq 'required_vars+=(IBKR_FEATURE_SNAPSHOT_MANIFEST_PATH IBKR_STRATEGY_CONFIG_PATH IBKR_RECONCILIATION_OUTPUT_PATH)' "$workflow_file"
+grep -Fq 'required_vars+=(IBKR_FEATURE_SNAPSHOT_MANIFEST_PATH)' "$workflow_file"
+grep -Fq 'required_vars+=(IBKR_STRATEGY_CONFIG_PATH IBKR_RECONCILIATION_OUTPUT_PATH)' "$workflow_file"
 grep -Fq 'env_pairs+=("IBKR_FEATURE_SNAPSHOT_PATH=${IBKR_FEATURE_SNAPSHOT_PATH}")' "$workflow_file"
 grep -Fq 'env_pairs+=("IBKR_FEATURE_SNAPSHOT_MANIFEST_PATH=${IBKR_FEATURE_SNAPSHOT_MANIFEST_PATH}")' "$workflow_file"
 grep -Fq 'env_pairs+=("IBKR_STRATEGY_CONFIG_PATH=${IBKR_STRATEGY_CONFIG_PATH}")' "$workflow_file"