Track horizon-specific recommendation context

Author: Pigbibi

README.md

@@ -29,6 +29,17 @@ Live site:
 
 <https://quantstrategylab.github.io/QuantAdvisorResearch/>
 
+
+## Horizon Source Split
+
+Advisor is the final composition layer. Source ownership by horizon is:
+
+- Short term (`1-10 trading days`): `source_events.csv` / `political_events.csv` from `PoliticalEventTrackingResearch` for event and policy/news catalysts.
+- Medium term (`2-12 weeks`): `theme_momentum_snapshot.json` from `AiLongHorizonSignalPipelines`, now explicitly marked as `medium_horizon_theme_context`.
+- Long term (`1-3 years`): `latest_signal.json` / `signal_history/*.json` from `AiLongHorizonSignalPipelines` as AI shadow context.
+
+Final recommendations are still deterministic Advisor outputs. The AI repository does not directly produce short-term recommendations or replace the final decision engine.
+
 ## Boundary
 
 This repository owns:

README.zh-CN.md

@@ -17,6 +17,17 @@ QuantStrategyLab 的“智慧顾投”研究协调仓库。它生成非个性化
 - 其他量化策略/快照仓库：保持独立，不作为当前推荐链路的直接输入。
 - 各券商平台仓库：继续只负责执行链路；本仓库不调用它们。
 
+
+## 短中长线来源分工
+
+Advisor 是最终合成层，三个周期的输入分工如下：
+
+- 短线（1-10 个交易日）：`PoliticalEventTrackingResearch` 的 `source_events.csv` / `political_events.csv`，用于事件和新闻政策催化。
+- 中线（2-12 周）：`AiLongHorizonSignalPipelines` 的 `theme_momentum_snapshot.json`，现在明确标记为 `medium_horizon_theme_context`。
+- 长线（1-3 年）：`AiLongHorizonSignalPipelines` 的 `latest_signal.json` / `signal_history/*.json`，作为 AI shadow 背景。
+
+最终推荐仍由本仓库确定性合成。AI 仓库不直接输出短线推荐，也不替代本仓库的最终决策。
+
 ## 当前 MVP
 
 当前实现一个确定性报告生成器：

docs/system_design.zh-CN.md

@@ -104,6 +104,15 @@ symbol_theme_exposure
 
 但使用边界保持不变：主题 bias 只能作为研究背景和轻量评分输入，不能绕过事件证据、来源质量、风险提示和非个性化/不执行的合约约束。这样可以避免因为近期热点临时修改 universe 或权重，从而降低类似量化回测过拟合的问题。
 
+
+## 短中长线来源分工
+
+- 短线（1-10 个交易日）：事件事实层负责，主要来自 `PoliticalEventTrackingResearch` 的官方来源、新闻政策和事件新鲜度。
+- 中线（2-12 周）：主题上下文层负责，`AiLongHorizonSignalPipelines` 的 `theme_momentum_snapshot.json` 标记为 `medium_horizon_theme_context`。
+- 长线（1-3 年）：AI shadow 背景层负责，来自 `latest_signal.json` 和 `signal_history/*.json`。
+
+`QuantAdvisorResearch` 只在最后做确定性合成，报告中的 `supporting_context` 会记录每个最终推荐用到了短线、中线、长线哪些输入。
+
 ## Theme momentum 展示边界
 
 `QuantAdvisorResearch` 可以消费 `theme_momentum_snapshot.json`，但只用于报告展示：

examples/ai_long_horizon_signal.example.json

@@ -3,7 +3,7 @@
   "as_of": "2026-05-28",
   "generated_at": "2026-05-28T14:38:47.474891Z",
   "mode": "shadow",
-  "horizon": "1-3 months",
+  "horizon": "1-3 years",
   "universe": [
     "IDX1",
     "IDX2",

examples/theme_momentum_snapshot.example.json

@@ -3,6 +3,10 @@
   "as_of": "2026-05-30",
   "generated_at": "2026-05-30T00:00:00Z",
   "mode": "theme_momentum_snapshot",
+  "artifact_type": "medium_horizon_theme_context",
+  "horizon": "medium",
+  "horizon_window": "2-12 weeks",
+  "horizon_window_label": "2-12周",
   "taxonomy_version": "2026-05-31-core-themes-v1",
   "methodology": {
     "windows": {
@@ -56,13 +60,20 @@
     }
   ],
   "data_quality": {
+    "coverage": {
+      "configured_symbol_count": 4,
+      "priced_symbol_count": 4,
+      "price_coverage_ratio": 1.0,
+      "insufficient_history_symbol_count": 0
+    },
     "missing_price_symbols": [],
+    "insufficient_history_symbols": [],
     "unranked_themes": []
   },
   "policy": {
     "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."
   }
 }

src/quant_advisor_research/advisory_report.py

@@ -51,6 +51,7 @@
     "long": "1-3年",
     "not_applicable": "不适用",
 }
+THEME_MOMENTUM_ARTIFACT_TYPE = "medium_horizon_theme_context"
 
 CADENCE_LABELS_ZH = {
     "daily": "日度",
@@ -284,12 +285,17 @@ def summarize_theme_momentum(payload: dict[str, Any] | None, *, max_themes: int
     return {
         "available": True,
         "as_of": payload.get("as_of", ""),
+        "artifact_type": payload.get("artifact_type", THEME_MOMENTUM_ARTIFACT_TYPE),
+        "horizon": payload.get("horizon", "medium"),
+        "horizon_window": payload.get("horizon_window", "2-12 weeks"),
+        "horizon_window_label": payload.get("horizon_window_label", HORIZON_WINDOWS["medium"]),
         "taxonomy_version": payload.get("taxonomy_version", ""),
         "top_themes": top_themes,
         "data_quality": payload.get("data_quality", {}),
         "policy": {
             "execution_allowed": False,
             "theme_rank_is_research_context_only": True,
+            "direct_short_term_recommendation_allowed": False,
         },
     }
 
@@ -728,6 +734,10 @@ def build_recommendation(
         ]
     )
 
+    long_horizon_ai_score = 0.0
+    if ai_bias in {"positive", "watch", "neutral"}:
+        long_horizon_ai_score = round(clamp(ai_confidence, 0, 1), 3)
+
     return {
         "symbol": symbol,
         "name": item.name if item else symbol,
@@ -752,6 +762,15 @@ def build_recommendation(
         "evidence_summary": " ".join(reasons),
         "evidence_refs": dedupe(evidence_refs),
         "review_checklist": dedupe(review_checklist),
+        "ai_context": {
+            "source": "latest_signal" if ai_signal else "",
+            "horizon": "long" if ai_signal else "",
+            "horizon_window": HORIZON_WINDOWS["long"] if ai_signal else "",
+            "bias": ai_bias or "",
+            "confidence": round(ai_confidence, 3),
+            "theme_ids": ai_bias_source_themes,
+        },
+        "long_horizon_ai_score": long_horizon_ai_score,
     }
 
 
@@ -829,6 +848,7 @@ def theme_symbol_context(theme_momentum: dict[str, Any] | None) -> dict[str, dic
                     "primary_theme_label": theme_label(theme_id, theme_name),
                     "best_theme_rank": rank,
                     "ai_signal_score": ai_signal_score,
+                    "medium_context_score": ai_signal_score,
                     "symbol_momentum_score": symbol_momentum_score,
                     "momentum_score": momentum_score,
                     "return_3m": return_3m,
@@ -843,6 +863,7 @@ def theme_symbol_context(theme_momentum: dict[str, Any] | None) -> dict[str, dic
                 current["best_theme_rank"] = rank
             if ai_signal_score > as_float(current.get("ai_signal_score")):
                 current["ai_signal_score"] = ai_signal_score
+                current["medium_context_score"] = ai_signal_score
             if momentum_score > as_float(current.get("momentum_score")):
                 current["symbol_momentum_score"] = symbol_momentum_score
                 current["momentum_score"] = momentum_score
@@ -881,6 +902,24 @@ def final_action_label(action: str) -> str:
     }.get(action, "跳过")
 
 
+def supporting_context_for(
+    rec: dict[str, Any] | None,
+    *,
+    source_score: float,
+    momentum_score: float,
+    medium_context_score: float,
+    long_context_score: float,
+) -> dict[str, list[str]]:
+    context = {"short": [], "medium": [], "long": []}
+    if source_score >= 0.35 and rec:
+        context["short"].append("source_events")
+    if momentum_score >= 0.35 or medium_context_score >= 0.35:
+        context["medium"].append("theme_momentum_snapshot")
+    if long_context_score >= 0.35 and rec:
+        context["long"].append("latest_signal")
+    return context
+
+
 def build_final_decisions(
     recommendations: list[dict[str, Any]],
     theme_momentum: dict[str, Any] | None,
@@ -898,10 +937,13 @@ def build_final_decisions(
         theme = theme_context.get(symbol, {})
         source_score = normalize_source_score(rec)
         momentum_score = as_float(theme.get("momentum_score"))
-        ai_signal_score = as_float(theme.get("ai_signal_score"))
-        support_count = sum(score >= 0.35 for score in (source_score, momentum_score, ai_signal_score))
-        combined_score = round(source_score * 0.15 + momentum_score * 0.40 + ai_signal_score * 0.45, 3)
-        action = final_action_for(rec, combined_score, support_count, momentum_score, ai_signal_score)
+        medium_context_score = as_float(theme.get("medium_context_score", theme.get("ai_signal_score")))
+        long_context_score = as_float(rec.get("long_horizon_ai_score")) if rec else 0.0
+        support_count = sum(
+            score >= 0.35 for score in (source_score, momentum_score, medium_context_score, long_context_score)
+        )
+        combined_score = round(source_score * 0.15 + momentum_score * 0.40 + medium_context_score * 0.45, 3)
+        action = final_action_for(rec, combined_score, support_count, momentum_score, medium_context_score)
         if action == "skip":
             continue
         name = rec.get("name", symbol) if rec else symbol
@@ -915,9 +957,12 @@ def build_final_decisions(
             reasons.append(
                 f"动量：个股动量分数={display_number(theme.get('symbol_momentum_score'))}，近3个月={display_percent(theme.get('return_3m'))}。"
             )
-        if ai_signal_score >= 0.35:
+        if medium_context_score >= 0.35:
             labels = ", ".join(theme.get("theme_labels", [])[:3]) or str(theme.get("primary_theme_label", ""))
-            reasons.append(f"AI信号仓库：{labels}。")
+            reasons.append(f"中线主题上下文：{labels}。")
+        if long_context_score >= 0.35 and rec:
+            bias = rec.get("ai_context", {}).get("bias", "")
+            reasons.append(f"长线AI背景：{bias or '已读取'}。")
         if not reasons:
             reasons.append("当前进入观察名单，但多源证据仍需继续补强。")
         if rec and rec.get("primary_horizon") != "not_applicable":
@@ -944,7 +989,16 @@ def build_final_decisions(
                 "combined_score": combined_score,
                 "source_score": round(source_score, 3),
                 "momentum_score": round(momentum_score, 3),
-                "ai_signal_score": round(ai_signal_score, 3),
+                "ai_signal_score": round(medium_context_score, 3),
+                "medium_context_score": round(medium_context_score, 3),
+                "long_context_score": round(long_context_score, 3),
+                "supporting_context": supporting_context_for(
+                    rec,
+                    source_score=source_score,
+                    momentum_score=momentum_score,
+                    medium_context_score=medium_context_score,
+                    long_context_score=long_context_score,
+                ),
                 "business_summary": profile["business"],
                 "prospect_summary": profile["prospect"],
                 "why_selected": dedupe(reasons),
@@ -1051,6 +1105,9 @@ def build_advisory_report(
             "source_mode": source_mode,
             "data_quality_warnings": data_quality_warnings,
             "theme_momentum_available": theme_momentum_summary["available"],
+            "theme_momentum_artifact_type": theme_momentum_summary.get("artifact_type", ""),
+            "theme_momentum_horizon": theme_momentum_summary.get("horizon", ""),
+            "theme_momentum_horizon_window": theme_momentum_summary.get("horizon_window_label", ""),
             "top_theme_ids": [theme["theme_id"] for theme in theme_momentum_summary["top_themes"]],
             "theme_first_candidate_count": len(theme_first_candidates),
             "top_theme_candidate_symbols": [item["symbol"] for item in theme_first_candidates[:8]],

src/quant_advisor_research/publisher.py

@@ -100,7 +100,7 @@ def render_final_decisions_html(report: dict[str, Any]) -> str:
                 <div><dt>综合分</dt><dd>{html.escape(display_number(pick.get('combined_score')))}</dd></div>
                 <div><dt>政策/新闻</dt><dd>{html.escape(display_number(pick.get('source_score')))}</dd></div>
                 <div><dt>动量</dt><dd>{html.escape(display_number(pick.get('momentum_score')))}</dd></div>
-                <div><dt>AI信号仓库</dt><dd>{html.escape(display_number(pick.get('ai_signal_score')))}</dd></div>
+                <div><dt>中线主题</dt><dd>{html.escape(display_number(pick.get('medium_context_score', pick.get('ai_signal_score'))))}</dd></div>
               </dl>
               <p><strong>股票背景：</strong>{html.escape(str(pick.get('business_summary', '')))}</p>
               <p><strong>推荐理由：</strong>{html.escape(str(pick.get('prospect_summary', '')))}</p>

tests/test_advisory_report.py

@@ -178,6 +178,8 @@ def test_render_markdown_keeps_public_report_direct() -> None:
     assert "受众:" not in markdown
     assert "AI 状态" not in markdown
     assert "本期最终结论" not in markdown
+    assert "中线主题上下文" in markdown
+    assert "AI信号仓库" not in markdown
     assert "AiLongHorizonSignalPipelines" not in markdown
 
 
@@ -340,6 +342,9 @@ def test_theme_momentum_snapshot_is_display_context_not_rating_input(tmp_path: P
         theme_momentum_path=theme_momentum_path,
     )
 
+    assert report_with_theme["summary"]["theme_momentum_artifact_type"] == "medium_horizon_theme_context"
+    assert report_with_theme["summary"]["theme_momentum_horizon"] == "medium"
+    assert report_with_theme["summary"]["theme_momentum_horizon_window"] == "2-12周"
     assert report_with_theme["summary"]["top_theme_ids"][:1] == ["hbm_memory"]
     assert report_with_theme["summary"]["top_theme_candidate_symbols"][:3] == ["MU", "NVDA", "DELL"]
     assert report_with_theme["theme_momentum"]["top_themes"][0]["theme_id"] == "hbm_memory"
@@ -349,10 +354,13 @@ def test_theme_momentum_snapshot_is_display_context_not_rating_input(tmp_path: P
     assert report_with_theme["theme_first_candidates"][0]["industry_background"]
     assert report_with_theme["theme_first_candidates"][0]["recommendation_summary"]
     assert report_with_theme["theme_first_candidates"][2]["symbol"] == "DELL"
-    assert report_with_theme["final_decisions"]["recommendations"][0]["symbol"] == "MU"
-    assert report_with_theme["final_decisions"]["recommendations"][0]["business_summary"]
-    assert "存储周期" in report_with_theme["final_decisions"]["recommendations"][0]["risk_summary"]
-    assert "ai_signal_score" in report_with_theme["final_decisions"]["recommendations"][0]
+    first_pick = report_with_theme["final_decisions"]["recommendations"][0]
+    assert first_pick["symbol"] == "MU"
+    assert first_pick["business_summary"]
+    assert "存储周期" in first_pick["risk_summary"]
+    assert "ai_signal_score" in first_pick
+    assert first_pick["medium_context_score"] == first_pick["ai_signal_score"]
+    assert first_pick["supporting_context"]["medium"] == ["theme_momentum_snapshot"]
     assert "AiLongHorizonSignalPipelines" not in report_with_theme["final_decisions"]["method"]
     assert report_with_theme["final_decisions"]["watchlist"][0]["symbol"] == "DELL"
     assert report_with_theme["recommendations"][0]["rating"] == report_without_theme["recommendations"][0]["rating"]
@@ -362,6 +370,8 @@ def test_theme_momentum_snapshot_is_display_context_not_rating_input(tmp_path: P
     assert "## 本期最终结论" not in markdown
     assert "股票背景" in markdown
     assert "推荐理由" in markdown
+    assert "中线主题上下文" in markdown
+    assert "AI信号仓库" not in markdown
     assert "AiLongHorizonSignalPipelines" not in markdown
     assert "## 主题候选（解释材料，不是最终推荐）" not in markdown
     assert "为什么入选" not in markdown

tests/test_publisher.py

@@ -123,7 +123,8 @@ def test_render_report_html_includes_theme_momentum_context() -> None:
     assert "<span class=\"pill\">模式：" not in html
     assert "受众：" not in html
     assert "AI 状态：" not in html
-    assert "AI信号仓库" in html
+    assert "中线主题" in html
+    assert "AI信号仓库" not in html
     assert "AiLongHorizonSignalPipelines" not in html
     assert "股票背景" in html
     assert "推荐理由" in html