Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Research-only profiles may stay in code for reproducibility and future review, b

| Profile | Name | Notes |
| --- | --- | --- |
| `tech_communication_pullback_enhancement` | Tech/Communication Pullback Enhancement | research-only; kept out of current configurable live profiles. |
| `tech_communication_pullback_enhancement` | Tech/Communication Pullback Enhancement | archived research-only; no longer a catalog/entrypoint runtime profile. |

## How this connects to execution

Expand Down
2 changes: 1 addition & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ UsEquityStrategies 是 QuantStrategyLab 的美股策略包。为 QuantStrategyLa

| Profile | 名称 | 说明 |
| --- | --- | --- |
| `tech_communication_pullback_enhancement` | Tech/Communication Pullback Enhancement | research-only,不进入当前可配置 live profile。 |
| `tech_communication_pullback_enhancement` | Tech/Communication Pullback Enhancement | 已归档 research-only,不再是 catalog/entrypoint 可运行 profile。 |

## 如何接到执行平台

Expand Down
43 changes: 32 additions & 11 deletions docs/research/income_layer_design.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
- 阅读顺序:先确认边界、输入输出和权限要求,再执行文档里的命令、CI、dry-run、发布或切换步骤。
- 风险提示:涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更,必须先在测试环境或 dry-run 验证;不要只凭示例直接修改生产。
- 英文正文保留更完整的命令、字段名和配置键;如果摘要和正文不一致,以正文中的实际命令和配置为准。
_Updated: 2026-05-26_
_Updated: 2026-06-04_

## Decision

Expand All @@ -19,25 +19,44 @@ Current defaults:

| Profile | Mode | Start | Activation band | Hard cap | Default income basket |
| --- | --- | ---: | ---: | ---: | --- |
| `tqqq_growth_income` | `log_cap` | `250000` | `20%` | `50%` | `SCHD 30% / DGRO 20% / SGOV 40% / SPYI 8% / QQQI 2%` |
| `soxl_soxx_trend_income` | `log_cap` | `250000` | `20%` | `95%` | `SCHD 25% / DGRO 15% / SGOV 55% / SPYI 4% / QQQI 1%` |
| `global_etf_rotation` | `log_loss_budget` | `500000` | `10%` | `15%` | `SCHD 40% / DGRO 25% / SGOV 30% / SPYI 5%` |
| `russell_1000_multi_factor_defensive` | `log_loss_budget` | `400000` | `10%` | `20%` | `SCHD 45% / DGRO 30% / SGOV 25%` |
| `tech_communication_pullback_enhancement` | `log_loss_budget` | `250000` | `15%` | `30%` | `SCHD 40% / DGRO 25% / SGOV 20% / SPYI 10% / QQQI 5%` |
| `mega_cap_leader_rotation_top50_balanced` | `log_loss_budget` | `300000` | `15%` | `25%` | `SCHD 45% / DGRO 30% / SGOV 20% / SPYI 5%` |
| `tqqq_growth_income` | `log_total_drawdown_budget` | `250000` | `20%` | `55%` | `SCHD 30% / DGRO 20% / SGOV 40% / SPYI 8% / QQQI 2%` |
| `soxl_soxx_trend_income` | `log_total_drawdown_budget` | `150000` | `20%` | `95%` | `SCHD 15% / DGRO 10% / SGOV 70% / SPYI 4% / QQQI 1%` |
| `global_etf_rotation` | `log_total_drawdown_budget` | `500000` | `10%` | `15%` | `SCHD 40% / DGRO 25% / SGOV 30% / SPYI 5%` |
| `russell_1000_multi_factor_defensive` | `log_total_drawdown_budget` | `400000` | `10%` | `20%` | `SCHD 45% / DGRO 30% / SGOV 25%` |
| `mega_cap_leader_rotation_top50_balanced` | `log_total_drawdown_budget` | `300000` | `15%` | `25%` | `SCHD 45% / DGRO 30% / SGOV 25%` |

`tech_communication_pullback_enhancement` is removed from runtime exposure. Its
strategy implementation and bundled config remain only as archived research, so
it has no current income-layer default.

Activation and near-cap visualization:
[`income_layer_activation_drawdown_2026-05-26.svg`](./income_layer_activation_drawdown_2026-05-26.svg).

## Design Rules

- Leveraged profiles use `log_cap`: the account-level goal is to keep combined drawdown near or inside SPY / QQQ while preserving compound growth.
- Non-leveraged profiles use `log_loss_budget`: the goal is to damp account volatility as account size grows, not to materially rewrite the core strategy.
- Defaults use `log_total_drawdown_budget`: first set a target account-level drawdown budget from account size, then reverse it into an income-layer ratio from core-strategy and income-basket stress drawdown assumptions.
- The income layer is enabled by default; set `income_layer_enabled = false` to disable it.
- Leveraged profiles start from about a `45%` small-account stress budget, then tighten by account doubling toward about `30%`, and continue toward about `25%` for larger accounts.
- Non-leveraged profiles use a softer account-level budget curve so the income layer does not rewrite the core strategy too early.
- `income_layer_start_usd` is strategy-specific. Leveraged strategies start earlier; non-leveraged strategies generally start later or use a smaller cap.
- `income_layer_activation_band_ratio` prevents threshold churn. The normal target ratio is multiplied from 0 to 1 between `start` and `start * (1 + band)`.
- `income_layer_max_ratio` is a risk-budget parameter, not a pure return-maximization parameter. Raising the cap usually reduces drawdown and long-run CAGR.
- Existing income holdings are locked with `max(current_income_layer_value, desired_income_layer_value)`, so the layer adds capital by default instead of force-selling income assets down.

## Account-Budget Parameter Design

`base_drawdown_budget` equals each strategy's estimated core stress drawdown, so the target income-layer ratio starts continuously from 0 just above `start`. The budget then tightens smoothly by `drawdown_budget_decay_per_double * log2(nav / start)`, with `min_drawdown_budget` as the large-account floor. The income ratio is reversed from:

`income_ratio = (core_stress_drawdown - account_budget) / (core_stress_drawdown - income_stress_drawdown)`

| Profile | Role | Core stress drawdown | Income stress drawdown | Account budget curve | Income cap | Rationale |
| --- | --- | ---: | ---: | --- | ---: | --- |
| `tqqq_growth_income` | Broad-market leveraged growth | `45%` | `8%` | Starts at `45%`, tightens `5%` per double, floor `25%` | `55%` | Small accounts can accept near-core volatility; around `500k` the budget tightens near `40%`, around `2M` near `30%`, while preserving compounding. |
| `soxl_soxx_trend_income` | Semiconductor leveraged trend | `45%` | `6%` | Starts at `45%`, tightens `5%` per double, floor `25%` | `95%` | SOXL has sharper path risk and a more SGOV-heavy income basket, so the cap is high enough to satisfy large-account budgets. |
| `global_etf_rotation` | Defensive ETF rotation | `30%` | `8%` | Starts at `30%`, tightens `1.5%` per double, floor `26.7%` | `15%` | The core already has canary/BIL defense; the floor matches the drawdown achievable with the 15% income cap. |
| `russell_1000_multi_factor_defensive` | Defensive multi-factor stocks | `30%` | `8%` | Starts at `30%`, tightens `1.5%` per double, floor `25.6%` | `20%` | Single-stock equity risk is higher than Global ETF, so the cap and achievable floor are slightly more defensive. |
| `mega_cap_leader_rotation_top50_balanced` | Concentrated leader rotation | `35%` | `8%` | Starts at `35%`, tightens `2%` per double, floor `28.25%` | `25%` | Top2/Top4 concentration needs a Tech-like budget curve, but the cap is lower to avoid muting strong trend capture too much. |

## Leveraged Profile Review

Research output:
Expand All @@ -51,7 +70,7 @@ Selection rules:
- TQQQ additionally uses a roughly `15%` max drawdown constraint at `1000000 USD`, matching the "at most 150k loss on a 1M account" budget.
- Among candidates that pass, rank by CAGR; if return is close, prefer the simpler path closest to the current default core.

Final selected defaults:
Defaults selected on 2026-05-26 are archived below. The 2026-06-04 defaults now use account-level `log_total_drawdown_budget`; the current-default table above is authoritative:

| Strategy | Version | CAGR | Max drawdown | SPY windows | QQQ windows | Avg income ratio | End income ratio | Decision |
| --- | --- | ---: | ---: | --- | --- | ---: | ---: | --- |
Expand All @@ -71,6 +90,8 @@ SOXL core overlay review:

Therefore the SOXL core `blend_gate_volatility_delever_*` defaults stay unchanged; only the income-layer defaults changed.

A lightweight 2026-06-04 refresh using Nasdaq real history and official yield proxies moved the SOXL income layer to the earlier, more SGOV-heavy `start=150000, max=95%, log_factor=0.50` version. In that sample it produced about `38.73%` CAGR and `-9.28%` max drawdown while still passing the SPY drawdown-window constraint.

## Core Default Review

Follow-up research on 2026-05-26/27 retested the leveraged cores after the
Expand Down Expand Up @@ -98,4 +119,4 @@ this review.
- Small-account mode does not require combined drawdown to beat the broad market. The account is still mainly in growth-compounding mode until it crosses the threshold.
- At `1000000 USD`, the income layer must pull TQQQ and SOXL combined drawdown inside the SPY / QQQ reference windows.
- TQQQ moved from `150000` to `250000` start to reduce early income drag while keeping about `-14.87%` drawdown in the `1000000 USD` calibration.
- SOXL moved from `150000 / 90% / current_soxl` to `250000 / 95% / balanced_income`; in the `1000000 USD` calibration, CAGR improved from about `32.16%` to `36.14%`, while max drawdown widened from about `-7.70%` to `-9.04%` and stayed well inside the loss budget.
- SOXL first moved from `150000 / 90% / current_soxl` to `250000 / 95% / balanced_income`; the 2026-06-04 refresh then moved it to `150000 / 95% / SGOV-heavy`, using the higher SGOV weight to offset the earlier activation's return drag.
41 changes: 30 additions & 11 deletions docs/research/income_layer_design.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
- For live trading, secrets, Cloud Run, exchange, or broker API changes, validate in test or dry-run mode first and do not change production only from examples.
- If this summary differs from the detailed Chinese body, follow the concrete commands, configuration keys, and constraints in the body.

_更新日期:2026-05-26_
_更新日期:2026-06-04_

## 结论

Expand All @@ -20,25 +20,42 @@ _更新日期:2026-05-26_

| Profile | 模式 | 起点 | 平滑带 | 硬上限 | 默认收入篮子 |
| --- | --- | ---: | ---: | ---: | --- |
| `tqqq_growth_income` | `log_cap` | `250000` | `20%` | `50%` | `SCHD 30% / DGRO 20% / SGOV 40% / SPYI 8% / QQQI 2%` |
| `soxl_soxx_trend_income` | `log_cap` | `250000` | `20%` | `95%` | `SCHD 25% / DGRO 15% / SGOV 55% / SPYI 4% / QQQI 1%` |
| `global_etf_rotation` | `log_loss_budget` | `500000` | `10%` | `15%` | `SCHD 40% / DGRO 25% / SGOV 30% / SPYI 5%` |
| `russell_1000_multi_factor_defensive` | `log_loss_budget` | `400000` | `10%` | `20%` | `SCHD 45% / DGRO 30% / SGOV 25%` |
| `tech_communication_pullback_enhancement` | `log_loss_budget` | `250000` | `15%` | `30%` | `SCHD 40% / DGRO 25% / SGOV 20% / SPYI 10% / QQQI 5%` |
| `mega_cap_leader_rotation_top50_balanced` | `log_loss_budget` | `300000` | `15%` | `25%` | `SCHD 45% / DGRO 30% / SGOV 20% / SPYI 5%` |
| `tqqq_growth_income` | `log_total_drawdown_budget` | `250000` | `20%` | `55%` | `SCHD 30% / DGRO 20% / SGOV 40% / SPYI 8% / QQQI 2%` |
| `soxl_soxx_trend_income` | `log_total_drawdown_budget` | `150000` | `20%` | `95%` | `SCHD 15% / DGRO 10% / SGOV 70% / SPYI 4% / QQQI 1%` |
| `global_etf_rotation` | `log_total_drawdown_budget` | `500000` | `10%` | `15%` | `SCHD 40% / DGRO 25% / SGOV 30% / SPYI 5%` |
| `russell_1000_multi_factor_defensive` | `log_total_drawdown_budget` | `400000` | `10%` | `20%` | `SCHD 45% / DGRO 30% / SGOV 25%` |
| `mega_cap_leader_rotation_top50_balanced` | `log_total_drawdown_budget` | `300000` | `15%` | `25%` | `SCHD 45% / DGRO 30% / SGOV 25%` |

`tech_communication_pullback_enhancement` 已从可运行暴露中移除;策略实现和 bundled config 仅作为离线研究归档保留,因此不再有当前收入层默认参数。

启动门槛、平滑带和接近上限位置的图表见
[`income_layer_activation_drawdown_2026-05-26.svg`](./income_layer_activation_drawdown_2026-05-26.svg)。

## 设计规则

- 杠杆策略使用 `log_cap`:目标是让组合层回撤接近或不超过 SPY / QQQ 对照,同时尽量保留复利。
- 非杠杆策略使用 `log_loss_budget`:目标是账户规模变大后的波动钝化,而不是显著改变策略本身。
- 默认模式统一使用 `log_total_drawdown_budget`:先按账户规模给出目标总回撤预算,再用核心策略压力回撤和收入篮子压力回撤反推出收入层比例。
- 收入层默认启用;需要关闭时设置 `income_layer_enabled = false`。
- 杠杆策略的小资金压力预算约为 `45%`,随后随账户翻倍逐步收紧到约 `30%`,更大账户继续向 `25%` 附近收敛。
- 非杠杆策略使用更温和的账户级预算曲线,避免收入层过早改写核心策略。
- `income_layer_start_usd` 必须按策略单独配置。杠杆策略更早启动,非杠杆策略更晚启动。
- `income_layer_activation_band_ratio` 用来解决门槛附近来回切换的问题。目标收入层比例在 `start` 到 `start * (1 + band)` 之间从 0 平滑放大到正常值。
- `income_layer_max_ratio` 是组合层风险预算,不是收益最大化参数。上限提高通常降低回撤,但也会降低长期 CAGR。
- 现有收入层采用 `max(current_income_layer_value, desired_income_layer_value)` 锁定已有收入资产,默认只增配,不主动减配。

## 账户级预算参数设计

`base_drawdown_budget` 默认等于该策略的核心压力回撤估计,因此刚跨过 `start` 时收入层目标比例仍从 0 连续起步;随后按 `drawdown_budget_decay_per_double * log2(nav / start)` 平滑收紧,并由 `min_drawdown_budget` 设置大账户下限。收入层比例由公式反推:

`income_ratio = (core_stress_drawdown - account_budget) / (core_stress_drawdown - income_stress_drawdown)`

| Profile | 设计角色 | 核心压力回撤 | 收入篮子压力回撤 | 账户预算曲线 | 收入层上限 | 设计理由 |
| --- | --- | ---: | ---: | --- | ---: | --- |
| `tqqq_growth_income` | 宽基杠杆增长 | `45%` | `8%` | `45%` 起,每翻倍降 `5%`,最低 `25%` | `55%` | 小资金允许接近核心波动;约 `500k` 附近预算收紧到 `40%`,约 `2M` 附近到 `30%`,但保留复利弹性。 |
| `soxl_soxx_trend_income` | 半导体杠杆趋势 | `45%` | `6%` | `45%` 起,每翻倍降 `5%`,最低 `25%` | `95%` | SOXL 路径更尖锐,收入篮子更偏 SGOV,因此允许更高收入层上限来处理大账户压力预算。 |
| `global_etf_rotation` | 防守型 ETF 轮动 | `30%` | `8%` | `30%` 起,每翻倍降 `1.5%`,最低 `26.7%` | `15%` | 核心本身已有 canary 和 BIL 防守,收入层只做大账户钝化;最低预算贴合 15% 收入层上限的可实现回撤。 |
| `russell_1000_multi_factor_defensive` | 防守型多因子股票 | `30%` | `8%` | `30%` 起,每翻倍降 `1.5%`,最低 `25.6%` | `20%` | 个股组合比 Global ETF 更分散但仍有权益风险,上限略高,最低预算贴合 20% 收入层上限。 |
| `mega_cap_leader_rotation_top50_balanced` | 高集中龙头轮动 | `35%` | `8%` | `35%` 起,每翻倍降 `2%`,最低 `28.25%` | `25%` | Top2/Top4 集中度高,预算曲线同科技增强,但上限略低,避免过度拖累强趋势。 |

## 杠杆策略实盘候选复核

研究输出:
Expand All @@ -52,7 +69,7 @@ _更新日期:2026-05-26_
- TQQQ 额外使用 `1000000 USD` 最大回撤不超过约 `15%` 的约束,匹配“100 万最多亏 15 万”的账户约束。
- 在通过约束的候选里按 CAGR 排序,若收益接近则优先保留更简单、更贴近当前生产路径的核心策略。

最终固定
2026-05-26 当时固定的候选如下;2026-06-04 已切换到账户级 `log_total_drawdown_budget` 默认,当前默认以本文开头表格为准

| Strategy | Version | CAGR | Max drawdown | SPY windows | QQQ windows | Avg income ratio | End income ratio | Decision |
| --- | --- | ---: | ---: | --- | --- | ---: | ---: | --- |
Expand All @@ -72,6 +89,8 @@ SOXL 核心 overlay 也做了窄候选复核:

因此 SOXL 本次只调整收入层,不改核心 `blend_gate_volatility_delever_*` 默认值。

2026-06-04 使用 Nasdaq 真实历史和官方收益率代理做轻量复核后,SOXL 默认收入层进一步切到更早启动、更偏 SGOV 的 `start=150000, max=95%, log_factor=0.50` 版本;样本内 CAGR 约 `38.73%`、最大回撤约 `-9.28%`,仍通过 SPY 窗口回撤约束。

## 核心默认参数复核

2026-05-26/27 在收入层默认值选定后,又对杠杆核心做了一轮小范围复核。复核刻意保持窄候选:
Expand Down Expand Up @@ -112,7 +131,7 @@ SOXL 核心 overlay 也做了窄候选复核:
- 小账户阶段不强行要求组合回撤不超过大盘。小账户的目标仍是增长层复利,收入层只在权益跨过门槛后逐步介入。
- 资金达到 `1000000 USD` 后,收入层配置必须把 TQQQ 和 SOXL 的组合层回撤压到 SPY / QQQ 窗口对照以内。
- TQQQ 从 `150000` 启动上移到 `250000`,能让小账户阶段少受收入层拖累;在 `1000000 USD` 校准下仍保持约 `-14.87%` 最大回撤。
- SOXL `150000 / 90% / current_soxl` 调整为 `250000 / 95% / balanced_income`,在 `1000000 USD` 校准下 CAGR 从约 `32.16%` 提升到 `36.14%`,最大回撤从约 `-7.70%` 扩到 `-9.04%`,仍明显低于 15% 亏损预算并通过 SPY / QQQ 回撤窗口
- SOXL 先从 `150000 / 90% / current_soxl` 调整为 `250000 / 95% / balanced_income`;2026-06-04 复核后改为 `150000 / 95% / SGOV-heavy`,用更高 SGOV 占比抵消更早启动带来的收益拖累

## 预设方向

Expand Down
Loading