Mark theme momentum as medium horizon context

Author: Pigbibi

README.md

@@ -97,6 +97,18 @@ rename such as `LongHorizonResearchSignals` can be considered, but that should
 be a separate migration because GitHub repo links, cross-repo checkout paths,
 and documentation references would all need updates.
 
+
+## Horizon Boundary
+
+This repository does not directly produce short-term buy/sell recommendations.
+The horizon split is:
+
+- Short term (`1-10 trading days`): handled by event evidence from `PoliticalEventTrackingResearch` plus deterministic Advisor rules. AI can explain context but should not decide short-term recommendations.
+- Medium term (`2-12 weeks`): represented by `theme_momentum_snapshot.json` as `medium_horizon_theme_context`, including theme momentum, breadth, and strong members inside each theme.
+- Long term (`1-3 years`): represented by `latest_signal.json` and `signal_history/*.json` as AI shadow context.
+
+`QuantAdvisorResearch` remains the only layer that combines these inputs into final short/medium/long recommendations.
+
 ## GitHub Configuration
 
 The model API keys are centralized in `CodexAuditBridge`; do not add
@@ -246,7 +258,8 @@ saved artifacts rather than regenerating historical AI judgments.
 ## Scheduled Theme Momentum Refresh
 
 `.github/workflows/theme_momentum_snapshot.yml` runs weekly before the advisor
-publication workflow. It builds `data/output/theme_momentum_snapshot.json` and,
+publication workflow. It builds `data/output/theme_momentum_snapshot.json` as
+`medium_horizon_theme_context` for the `2-12 weeks` horizon and,
 on scheduled runs, commits the changed snapshot back to the repository so
 `QuantAdvisorResearch` can consume a point-in-time artifact. Manual runs can pass
 `prices_path` to use an audited local CSV instead of Yahoo chart downloads.
@@ -275,7 +288,7 @@ If `--prices` is omitted, the script downloads Yahoo chart data.  Partial symbol
 failures are recorded in `data_quality.missing_price_symbols` by default;
 `--strict-downloads` turns those into hard failures.
 
-The snapshot records fixed 12-1m, 6-1m, and 3m momentum windows, breadth, risk
+The snapshot records `artifact_type=medium_horizon_theme_context`, horizon metadata, fixed 12-1m, 6-1m, and 3m momentum windows, breadth, risk
 penalties, top symbols per theme, source metadata, and a policy block that keeps
 the artifact research-only. `data_quality.coverage` now records configured
 symbol count, priced symbol count, price coverage ratio, and symbols with

README.zh-CN.md

@@ -75,6 +75,17 @@ data/output/signal_history/2026-05-28.json
 
 如果后续主题动量层明显扩展成更通用的研究信号仓，可以单独评估改名，例如 `LongHorizonResearchSignals`。这需要迁移 GitHub 仓库链接、跨仓 checkout 路径和文档引用，不建议和本次数据质量增强混在一起做。
 
+
+## 短中长线边界
+
+本仓库不直接输出短线买卖推荐。周期分工保持如下：
+
+- 短线（1-10 个交易日）：由 `PoliticalEventTrackingResearch` 的事件和 `QuantAdvisorResearch` 的确定性规则处理；AI 只可作为解释背景，不直接决定短线。
+- 中线（2-12 周）：由本仓库的 `theme_momentum_snapshot.json` 提供 `medium_horizon_theme_context`，包括主题动量、主题广度和主题内强势标的。
+- 长线（1-3 年）：由本仓库的 `latest_signal.json` / `signal_history/*.json` 提供 AI shadow context。
+
+最终短线、中线、长线推荐统一由 `QuantAdvisorResearch` 合成，本仓库仍不下单、不配仓、不输出账户级建议。
+
 ## GitHub 配置
 
 模型 API key 集中在 `CodexAuditBridge`；不要把 `OPENAI_API_KEY` 或 `ANTHROPIC_API_KEY` 放到本仓库。
@@ -199,7 +210,7 @@ config/symbol_theme_exposure.csv
 
 ## 主题动量定时刷新
 
-`.github/workflows/theme_momentum_snapshot.yml` 每周在 Advisor 发布前运行，生成 `data/output/theme_momentum_snapshot.json`。定时运行时如果快照有变化，会提交回仓库，供 `QuantAdvisorResearch` 读取点时 artifact。手工运行可以传 `prices_path`，使用可审计的本地价格 CSV，而不是临时下载。
+`.github/workflows/theme_momentum_snapshot.yml` 每周在 Advisor 发布前运行，生成 `data/output/theme_momentum_snapshot.json`。该 artifact 明确标记为 `medium_horizon_theme_context`，对应中线 2-12 周主题上下文。定时运行时如果快照有变化，会提交回仓库，供 `QuantAdvisorResearch` 读取点时 artifact。手工运行可以传 `prices_path`，使用可审计的本地价格 CSV，而不是临时下载。
 
 Yahoo chart 下载仍然只是临时 fallback。使用本地价格 CSV 时，快照会记录来源和文件 hash。随机免费代理 IP 池不应进入稳定链路，因为它会增加 replay、数据质量和合规复核难度。
 
@@ -222,6 +233,8 @@ python scripts/build_theme_momentum_snapshot.py \
 
 - `theme_ranks`：主题排名、动量分、breadth、风险惩罚和主题内 top symbols
 - `methodology`：固定窗口和权重，便于后续 walk-forward replay
+- `artifact_type`：`medium_horizon_theme_context`，表示中线主题上下文，不是短线 AI 推荐
+- `horizon` / `horizon_window`：`medium` / `2-12 weeks`
 - `policy`：明确这是研究排序，不允许下单或仓位分配
 - `data_quality.coverage`：配置标的数、已有价格标的数、价格覆盖率和价格历史不足标的
 

docs/architecture.md

@@ -117,6 +117,10 @@ This is the anti-overfit boundary:
 3. Replay only saved artifacts; never regenerate old model judgments.
 4. Treat theme bias as context, not as execution or allocation.
 
+## Horizon Boundary
+
+This repository should not directly produce short-term recommendations. Short-term (`1-10 trading days`) catalyst handling belongs to `PoliticalEventTrackingResearch` plus deterministic Advisor rules. `theme_momentum_snapshot.json` is explicitly a medium-horizon (`2-12 weeks`) theme context artifact, while `latest_signal.json` and `signal_history/*.json` remain long-horizon (`1-3 years`) AI shadow context. `QuantAdvisorResearch` is the final composition layer for short/medium/long recommendation buckets.
+
 ## Theme Momentum Snapshot
 
 A cross-sector theme ranking is produced separately from the static taxonomy.
@@ -134,10 +138,10 @@ Output path convention:
 data/output/theme_momentum_snapshot.json
 ```
 
-The artifact is point-in-time research context.  It ranks themes and highlights
-strong members inside a theme, but it does not encode orders, target weights, or
-execution policy.  Future replay must consume saved snapshots rather than
-recomputing old theme ranks with revised constituents or revised weights.
+The artifact is point-in-time medium-horizon research context.  It ranks themes and highlights
+strong members inside a theme, but it does not encode short-term recommendations,
+orders, target weights, or execution policy.  Future replay must consume saved
+snapshots rather than recomputing old theme ranks with revised constituents or revised weights.
 
 ## Repository Name Decision
 

scripts/build_theme_momentum_snapshot.py

@@ -104,6 +104,9 @@ def main() -> int:
             {
                 "output": str(output_path),
                 "as_of": snapshot["as_of"],
+                "artifact_type": snapshot.get("artifact_type", ""),
+                "horizon": snapshot.get("horizon", ""),
+                "horizon_window": snapshot.get("horizon_window", ""),
                 "ranked_theme_count": snapshot["summary"]["ranked_theme_count"],
                 "priced_symbol_count": snapshot["summary"]["priced_symbol_count"],
                 "top_theme_ids": snapshot["summary"]["top_theme_ids"],

src/ai_long_horizon_signal_pipelines/theme_momentum.py

@@ -21,6 +21,10 @@
 DRAWDOWN_PENALTY_WEIGHT = 0.25
 BREADTH_BONUS_WEIGHT = 0.10
 DEFAULT_TOP_SYMBOLS = 5
+THEME_MOMENTUM_ARTIFACT_TYPE = "medium_horizon_theme_context"
+THEME_MOMENTUM_HORIZON = "medium"
+THEME_MOMENTUM_HORIZON_WINDOW = "2-12 weeks"
+THEME_MOMENTUM_HORIZON_WINDOW_ZH = "2-12周"
 
 
 def utc_now_iso() -> str:
@@ -218,6 +222,10 @@ def build_theme_momentum_snapshot(
         "as_of": snapshot_as_of,
         "generated_at": (generated_at or dt.datetime.now(dt.UTC)).isoformat().replace("+00:00", "Z"),
         "mode": "theme_momentum_snapshot",
+        "artifact_type": THEME_MOMENTUM_ARTIFACT_TYPE,
+        "horizon": THEME_MOMENTUM_HORIZON,
+        "horizon_window": THEME_MOMENTUM_HORIZON_WINDOW,
+        "horizon_window_label": THEME_MOMENTUM_HORIZON_WINDOW_ZH,
         "taxonomy_version": taxonomy_versions[0] if taxonomy_versions else "unknown",
         "methodology": {
             "windows": {
@@ -252,7 +260,7 @@ def build_theme_momentum_snapshot(
             "execution_allowed": False,
             "portfolio_allocation_allowed": False,
             "theme_rank_is_research_context_only": True,
-            "downstream_use": "Theme momentum snapshot for research ranking and replay only; do not route to broker execution.",
+            "downstream_use": "Medium-horizon theme context for research ranking and replay only; do not route to broker execution.",
         },
     }
 

tests/test_theme_momentum.py

@@ -57,6 +57,10 @@ def test_theme_momentum_ranks_strong_broad_theme_first() -> None:
     )
 
     ranked = snapshot["theme_ranks"]
+    assert snapshot["artifact_type"] == "medium_horizon_theme_context"
+    assert snapshot["horizon"] == "medium"
+    assert snapshot["horizon_window"] == "2-12 weeks"
+    assert snapshot["horizon_window_label"] == "2-12周"
     assert ranked[0]["theme_id"] == "hbm_memory"
     assert ranked[0]["rank"] == 1
     assert ranked[0]["breadth_3m"] == 1.0