Adopt canonical US equity profile keys

Author: Pigbibi

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

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

README.md

@@ -16,7 +16,7 @@ IBKR runtime for shared `us_equity` strategy profiles from `UsEquityStrategies`.
 
 - `global_etf_rotation` (`Global ETF Rotation`): quarterly ETF momentum rotation with daily canary defense
 - `russell_1000_multi_factor_defensive` (`Russell 1000 Multi-Factor`): monthly stock-selection strategy that consumes a precomputed feature snapshot
-- `tech_pullback_cash_buffer` (`QQQ Tech Enhancement`): monthly tech-heavy stock-selection branch with explicit BOXX cash buffer
+- `qqq_tech_enhancement` (`QQQ Tech Enhancement`, alias: `tech_pullback_cash_buffer`): monthly tech-heavy stock-selection branch with explicit BOXX cash buffer
 
 Current strategy implementations are sourced from `UsEquityStrategies`.
 
@@ -40,8 +40,8 @@ The mainline runtime now follows one path only:
 
 - `global_etf_rotation`
 - `russell_1000_multi_factor_defensive`
-- `semiconductor_rotation_income`
-- `tech_pullback_cash_buffer`
+- `soxl_soxx_trend_income` (alias: `semiconductor_rotation_income`)
+- `qqq_tech_enhancement` (alias: `tech_pullback_cash_buffer`)
 
 
 **IBKR profile status**
@@ -50,8 +50,8 @@ The mainline runtime now follows one path only:
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | `global_etf_rotation` | Global ETF Rotation | Yes | Yes | Yes | Yes | `us_equity` | current rollback line |
 | `russell_1000_multi_factor_defensive` | Russell 1000 Multi-Factor | Yes | Yes | No | No | `us_equity` | defensive stock baseline |
-| `semiconductor_rotation_income` | SOXL/SOXX Semiconductor Trend Income | Yes | Yes | No | No | `us_equity` | current IBKR dry-run line |
-| `tech_pullback_cash_buffer` | QQQ Tech Enhancement | Yes | Yes | No | No | `us_equity` | enabled feature-snapshot alternative |
+| `soxl_soxx_trend_income` | SOXL/SOXX Semiconductor Trend Income | Yes | Yes | No | No | `us_equity` | current IBKR dry-run line |
+| `qqq_tech_enhancement` | QQQ Tech Enhancement | Yes | Yes | No | No | `us_equity` | enabled feature-snapshot alternative |
 
 Check the current matrix locally:
 
@@ -173,7 +173,7 @@ 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`, `semiconductor_rotation_income`, `tech_pullback_cash_buffer` |
+| `STRATEGY_PROFILE` | Yes | Strategy profile selector. Supported `us_equity` values: `global_etf_rotation`, `russell_1000_multi_factor_defensive`, `soxl_soxx_trend_income`, `qqq_tech_enhancement` |
 | `ACCOUNT_GROUP` | Yes | Account-group selector. No default fallback. |
 | `IBKR_FEATURE_SNAPSHOT_PATH` | Conditionally required | Required when `STRATEGY_PROFILE=russell_1000_multi_factor_defensive`. 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. |
@@ -223,7 +223,7 @@ NOTIFY_LANG=zh
 ```
 
 ```bash
-STRATEGY_PROFILE=tech_pullback_cash_buffer
+STRATEGY_PROFILE=qqq_tech_enhancement
 ACCOUNT_GROUP=default
 IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME=ibkr-account-groups
 IBKR_FEATURE_SNAPSHOT_PATH=/var/data/tech_pullback_cash_buffer_feature_snapshot_latest.csv
@@ -352,7 +352,7 @@ gcloud run services update ibkr-quant \
 
 基于 IBKR 的全球 ETF 季度轮动策略（国际市场、商品、美股行业、美股宽基、科技和半导体），含每日金丝雀应急机制。定位上比 `TQQQ`、`SOXL` 这类高弹性科技策略更稳健，但不再把科技完全排除在外。部署在 GCP Cloud Run，连接 GCE 上的 IB Gateway。
 
-当前 `global_etf_rotation`、`russell_1000_multi_factor_defensive`、`semiconductor_rotation_income` 和 `tech_pullback_cash_buffer` 的策略实现都来自 `UsEquityStrategies`。
+当前 `global_etf_rotation`、`russell_1000_multi_factor_defensive`、`soxl_soxx_trend_income` 和 `qqq_tech_enhancement` 的策略实现都来自 `UsEquityStrategies`。
 
 完整策略说明现在放在 [`UsEquityStrategies`](https://github.com/QuantStrategyLab/UsEquityStrategies#global_etf_rotation)。下面的策略章节主要保留执行侧摘要。
 
@@ -422,7 +422,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`、`semiconductor_rotation_income`、`tech_pullback_cash_buffer` |
+| `STRATEGY_PROFILE` | 是 | 策略档位选择。当前可用的 `us_equity` 值：`global_etf_rotation`、`russell_1000_multi_factor_defensive`、`soxl_soxx_trend_income`、`qqq_tech_enhancement` |
 | `ACCOUNT_GROUP` | 是 | 账号组选择器，不再提供默认回退。 |
 | `IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME` | Cloud Run 建议必填 | 账号组配置 JSON 在 Secret Manager 里的密钥名。生产环境推荐使用。 |
 | `IB_ACCOUNT_GROUP_CONFIG_JSON` | 否 | 本地开发用的账号组配置 JSON fallback。不建议在生产 Cloud Run 直接使用。 |
@@ -448,7 +448,7 @@ IBKR 账户
 当前第一步，建议让 GitHub / Cloud Run 只维护服务级变量：
 
 ```bash
-STRATEGY_PROFILE=semiconductor_rotation_income
+STRATEGY_PROFILE=soxl_soxx_trend_income
 ACCOUNT_GROUP=default
 IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME=ibkr-account-groups
 GLOBAL_TELEGRAM_CHAT_ID=<telegram-chat-id>

decision_mapper.py

@@ -3,6 +3,8 @@
 from collections.abc import Mapping
 from typing import Any
 
+from us_equity_strategies.catalog import resolve_canonical_profile
+
 from quant_platform_kit.strategy_contracts import (
     StrategyDecision,
     build_allocation_intent,
@@ -16,7 +18,8 @@
 
 
 def _resolve_allocation_order(strategy_profile: str) -> str:
-    if strategy_profile == "semiconductor_rotation_income":
+    canonical_profile = resolve_canonical_profile(strategy_profile)
+    if canonical_profile == "soxl_soxx_trend_income":
         return "risk_income_safe"
     return "risk_safe_income"
 
@@ -116,6 +119,7 @@ def map_strategy_decision(
     runtime_metadata: Mapping[str, Any] | None = None,
 ) -> tuple[dict[str, float] | None, str, bool, str, dict[str, Any]]:
     runtime_metadata = dict(runtime_metadata or {})
+    canonical_profile = resolve_canonical_profile(strategy_profile)
     diagnostics = dict(decision.diagnostics)
     risk_flags = tuple(str(flag) for flag in decision.risk_flags)
     no_execute = bool(_NO_EXECUTE_FLAGS & set(risk_flags))
@@ -126,16 +130,16 @@ def map_strategy_decision(
         allocation_payload = build_allocation_payload(
             build_allocation_intent(
                 normalized_decision,
-                strategy_profile=strategy_profile,
-                strategy_symbols_order=_resolve_allocation_order(strategy_profile),
+                strategy_profile=canonical_profile,
+                strategy_symbols_order=_resolve_allocation_order(canonical_profile),
             )
         )
     signal_desc = _derive_signal_description(decision, runtime_metadata)
     status_desc = _derive_status_description(decision, runtime_metadata)
     is_emergency = bool(_EMERGENCY_FLAGS & set(risk_flags))
 
     metadata: dict[str, Any] = {**runtime_metadata, **diagnostics}
-    metadata.setdefault("strategy_profile", strategy_profile)
+    metadata.setdefault("strategy_profile", canonical_profile)
     metadata.setdefault("status_icon", "🐤")
     metadata.setdefault(
         "managed_symbols",

notifications/telegram.py

@@ -62,8 +62,11 @@
         "strategy_name_global_etf_rotation": "全球 ETF 轮动",
         "strategy_name_russell_1000_multi_factor_defensive": "罗素1000多因子",
         "strategy_name_tech_pullback_cash_buffer": "QQQ 科技增强",
+        "strategy_name_qqq_tech_enhancement": "QQQ 科技增强",
         "strategy_name_hybrid_growth_income": "TQQQ 增长收益",
+        "strategy_name_tqqq_growth_income": "TQQQ 增长收益",
         "strategy_name_semiconductor_rotation_income": "SOXL/SOXX 半导体趋势收益",
+        "strategy_name_soxl_soxx_trend_income": "SOXL/SOXX 半导体趋势收益",
     },
     "en": {
         "rebalance_title": "🔔 【Trade Execution Report】",
@@ -123,8 +126,11 @@
         "strategy_name_global_etf_rotation": "Global ETF Rotation",
         "strategy_name_russell_1000_multi_factor_defensive": "Russell 1000 Multi-Factor",
         "strategy_name_tech_pullback_cash_buffer": "QQQ Tech Enhancement",
+        "strategy_name_qqq_tech_enhancement": "QQQ Tech Enhancement",
         "strategy_name_hybrid_growth_income": "TQQQ Growth Income",
+        "strategy_name_tqqq_growth_income": "TQQQ Growth Income",
         "strategy_name_semiconductor_rotation_income": "SOXL/SOXX Semiconductor Trend Income",
+        "strategy_name_soxl_soxx_trend_income": "SOXL/SOXX Semiconductor Trend Income",
     },
 }
 

requirements.txt

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

strategy_registry.py

@@ -23,10 +23,10 @@
 
 IBKR_ROLLOUT_ALLOWLIST = frozenset(
     {
-        "tech_pullback_cash_buffer",
+        "qqq_tech_enhancement",
         "global_etf_rotation",
         "russell_1000_multi_factor_defensive",
-        "semiconductor_rotation_income",
+        "soxl_soxx_trend_income",
     }
 )
 

tests/test_decision_mapper.py

@@ -17,7 +17,7 @@ def test_map_strategy_decision_maps_weight_positions_and_safe_haven():
 
     target_weights, signal_desc, is_emergency, status_desc, metadata = map_strategy_decision(
         decision,
-        strategy_profile="tech_pullback_cash_buffer",
+        strategy_profile="qqq_tech_enhancement",
         runtime_metadata={"status_icon": "🧲", "dry_run_only": True},
     )
 
@@ -46,7 +46,7 @@ def test_map_strategy_decision_returns_noop_when_flagged_no_execute():
 
     target_weights, signal_desc, is_emergency, status_desc, metadata = map_strategy_decision(
         decision,
-        strategy_profile="tech_pullback_cash_buffer",
+        strategy_profile="qqq_tech_enhancement",
         runtime_metadata={
             "status_icon": "🛑",
             "snapshot_guard_decision": "fail_closed",
@@ -80,7 +80,7 @@ def test_map_strategy_decision_translates_value_targets_for_semiconductor_strate
 
     target_weights, signal_desc, is_emergency, status_desc, metadata = map_strategy_decision(
         decision,
-        strategy_profile="semiconductor_rotation_income",
+        strategy_profile="soxl_soxx_trend_income",
         runtime_metadata={
             "portfolio_total_equity": 50000.0,
             "status_icon": "🚀",

tests/test_runtime_config_support.py

@@ -149,8 +149,8 @@ def test_load_platform_runtime_settings_rejects_unknown_strategy_profile(monkeyp
 def test_platform_supported_profiles_are_filtered_by_registry():
     assert get_supported_profiles_for_platform(IBKR_PLATFORM) == frozenset(
         {
-            "semiconductor_rotation_income",
-            "tech_pullback_cash_buffer",
+            "soxl_soxx_trend_income",
+            "qqq_tech_enhancement",
             "global_etf_rotation",
             "russell_1000_multi_factor_defensive",
         }
@@ -160,8 +160,8 @@ def test_platform_supported_profiles_are_filtered_by_registry():
 def test_platform_eligible_profiles_are_exposed_by_capability_matrix():
     assert get_eligible_profiles_for_platform(IBKR_PLATFORM) == frozenset(
         {
-            "semiconductor_rotation_income",
-            "tech_pullback_cash_buffer",
+            "soxl_soxx_trend_income",
+            "qqq_tech_enhancement",
             "global_etf_rotation",
             "russell_1000_multi_factor_defensive",
         }
@@ -176,7 +176,7 @@ def test_load_platform_runtime_settings_accepts_tech_pullback_cash_buffer(monkey
 
     settings = load_platform_runtime_settings(project_id_resolver=lambda: "project-1")
 
-    assert settings.strategy_profile == "tech_pullback_cash_buffer"
+    assert settings.strategy_profile == "qqq_tech_enhancement"
     assert settings.strategy_display_name == "QQQ Tech Enhancement"
     assert settings.strategy_target_mode == "weight"
 
@@ -186,7 +186,7 @@ def test_platform_profile_matrix_marks_default_and_rollback():
     by_profile = {row["canonical_profile"]: row for row in rows}
     assert by_profile["global_etf_rotation"]["is_default"] is True
     assert by_profile["global_etf_rotation"]["is_rollback"] is True
-    assert by_profile["tech_pullback_cash_buffer"]["display_name"] == "QQQ Tech Enhancement"
+    assert by_profile["qqq_tech_enhancement"]["display_name"] == "QQQ Tech Enhancement"
 
 
 def test_platform_profile_status_matrix_matches_current_ibkr_rollout():
@@ -196,8 +196,8 @@ def test_platform_profile_status_matrix_matches_current_ibkr_rollout():
     assert set(by_profile) == {
         "global_etf_rotation",
         "russell_1000_multi_factor_defensive",
-        "semiconductor_rotation_income",
-        "tech_pullback_cash_buffer",
+        "soxl_soxx_trend_income",
+        "qqq_tech_enhancement",
     }
     assert by_profile["global_etf_rotation"] == {
         "canonical_profile": "global_etf_rotation",
@@ -209,9 +209,9 @@ def test_platform_profile_status_matrix_matches_current_ibkr_rollout():
         "is_rollback": True,
         "platform": "ibkr",
     }
-    assert by_profile["semiconductor_rotation_income"]["display_name"] == "SOXL/SOXX Semiconductor Trend Income"
-    assert by_profile["semiconductor_rotation_income"]["eligible"] is True
-    assert by_profile["semiconductor_rotation_income"]["enabled"] is True
+    assert by_profile["soxl_soxx_trend_income"]["display_name"] == "SOXL/SOXX Semiconductor Trend Income"
+    assert by_profile["soxl_soxx_trend_income"]["eligible"] is True
+    assert by_profile["soxl_soxx_trend_income"]["enabled"] is True
 
 
 def test_print_strategy_profile_status_json_matches_registry():
@@ -300,17 +300,17 @@ def test_load_platform_runtime_settings_derives_artifact_paths_from_root(monkeyp
     settings = load_platform_runtime_settings(project_id_resolver=lambda: "project-1")
 
     assert settings.strategy_artifact_root == str(tmp_path)
-    assert settings.strategy_artifact_dir == str(tmp_path / "tech_pullback_cash_buffer")
+    assert settings.strategy_artifact_dir == str(tmp_path / "qqq_tech_enhancement")
     assert settings.feature_snapshot_path == str(
-        tmp_path / "tech_pullback_cash_buffer" / "tech_pullback_cash_buffer_feature_snapshot_latest.csv"
+        tmp_path / "qqq_tech_enhancement" / "qqq_tech_enhancement_feature_snapshot_latest.csv"
     )
     assert settings.feature_snapshot_manifest_path == str(
         tmp_path
-        / "tech_pullback_cash_buffer"
-        / "tech_pullback_cash_buffer_feature_snapshot_latest.csv.manifest.json"
+        / "qqq_tech_enhancement"
+        / "qqq_tech_enhancement_feature_snapshot_latest.csv.manifest.json"
     )
     assert settings.reconciliation_output_path == str(
-        tmp_path / "tech_pullback_cash_buffer" / "reconciliation"
+        tmp_path / "qqq_tech_enhancement" / "reconciliation"
     )
     assert settings.strategy_config_path is not None
     assert settings.strategy_config_path.endswith("growth_pullback_tech_pullback_cash_buffer.json")

tests/test_snapshot_strategy_runtime.py

@@ -147,7 +147,7 @@ def test_compute_signals_loads_tech_pullback_cash_buffer_runtime(strategy_module
     result = module.compute_signals(None, {"AAPL"})
 
     assert result[0]["BOXX"] == pytest.approx(0.2)
-    assert result[4]["strategy_profile"] == "tech_pullback_cash_buffer"
+    assert result[4]["strategy_profile"] == "qqq_tech_enhancement"
     assert result[4]["strategy_config_source"] in {"env", "external_config"}
     assert result[4]["realized_stock_weight"] == pytest.approx(0.8)
     assert result[4]["snapshot_guard_decision"] == "proceed"

tests/test_strategy_loader.py

@@ -32,7 +32,7 @@ def test_load_strategy_entrypoint_for_profile_resolves_tech_pullback_cash_buffer
 
     entrypoint = load_strategy_entrypoint_for_profile("tech_pullback_cash_buffer")
 
-    assert entrypoint.manifest.profile == "tech_pullback_cash_buffer"
+    assert entrypoint.manifest.profile == "qqq_tech_enhancement"
     assert entrypoint.manifest.default_config["safe_haven"] == "BOXX"