aria-code 4.1.3__py3-none-any.whl

agents/deep/quant_fusion.py

@@ -0,0 +1,192 @@
+"""P2 — fuse quantitative ground truth and calibrate confidence.
+
+The qualitative team votes a signal with a self-reported confidence. That number
+is uncalibrated — an agent saying "80%" doesn't mean it's right 80% of the time.
+This layer:
+
+  1. gathers quant signals (AI signal, risk metrics, backtest) as ground truth,
+  2. nudges confidence by whether quant *agrees* with the qualitative verdict,
+  3. scales by a *reliability* factor learned from realised outcomes (CalibrationStore),
+
+so confidence drifts toward the historical hit-rate as outcomes accumulate.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Callable, Dict, Optional, Tuple
+
+from .models import QuantEvidence, Provenance
+
+_BULL = ("STRONG_BUY", "BUY")
+_BEAR = ("STRONG_SELL", "SELL")
+
+
+# ── gather quant evidence ─────────────────────────────────────────────────────
+def _default_provider(symbol: str) -> Dict[str, Dict]:
+    """Best-effort pull of quant signals from local_finance_tools (each optional)."""
+    out: Dict[str, Dict] = {}
+    try:
+        import local_finance_tools as lft
+    except Exception:
+        return out
+    for key, fn in (("ai", "_get_ai_signal"), ("risk", "_get_risk_metrics"),
+                    ("backtest", "_backtest_strategy"), ("factors", "_calculate_factors")):
+        f = getattr(lft, fn, None)
+        if not f:
+            continue
+        try:
+            res = f({"symbol": symbol})
+            if isinstance(res, dict) and res.get("success"):
+                out[key] = res
+        except Exception:
+            pass
+    return out
+
+
+def _num(d: Dict, *keys) -> Optional[float]:
+    for k in keys:
+        v = d.get(k)
+        if isinstance(v, (int, float)):
+            return float(v)
+    return None
+
+
+def gather_quant_evidence(
+    symbol: str,
+    provider: Optional[Callable[[str], Dict[str, Dict]]] = None,
+) -> Tuple[QuantEvidence, list]:
+    """Return (QuantEvidence, [Provenance]). Never raises."""
+    raw = {}
+    try:
+        raw = (provider or _default_provider)(symbol)
+    except Exception:
+        raw = {}
+
+    prov: list = []
+    ev = QuantEvidence()
+    if not raw:
+        ev.note = "no quant backend available"
+        return ev, prov
+
+    ai = raw.get("ai") or {}
+    if ai:
+        action = str(ai.get("action") or ai.get("signal") or "").upper()
+        ev.ai_signal = action or None
+        conf = _num(ai, "confidence") or 0.0
+        if action in _BULL:
+            ev.ai_score = conf
+        elif action in _BEAR:
+            ev.ai_score = -conf
+        else:
+            ev.ai_score = 0.0
+        prov.append(Provenance("ai_signal", str(ai.get("provider", "quant")), note=action))
+
+    risk = raw.get("risk") or {}
+    if risk:
+        ev.sharpe = _num(risk, "sharpe", "sharpe_ratio")
+        ev.max_drawdown = _num(risk, "max_drawdown", "max_dd")
+        prov.append(Provenance("risk_metrics", "local_finance", note="VaR/Sharpe"))
+
+    bt = raw.get("backtest") or {}
+    if bt:
+        ev.backtest_return = _num(bt, "total_return", "return", "cagr")
+        if ev.sharpe is None:
+            ev.sharpe = _num(bt, "sharpe", "sharpe_ratio")
+        if ev.max_drawdown is None:
+            ev.max_drawdown = _num(bt, "max_drawdown", "max_dd")
+        prov.append(Provenance("backtest", "local_finance", note=str(bt.get("strategy", ""))))
+
+    fac = raw.get("factors") or {}
+    if fac:
+        ev.ic = _num(fac, "ic", "information_coefficient")
+        ev.factors = {k: v for k, v in fac.items()
+                      if k not in ("success", "symbol") and isinstance(v, (int, float))}
+        prov.append(Provenance("factors", "local_finance"))
+
+    ev.available = bool(ai or risk or bt or fac)
+    return ev, prov
+
+
+# ── confidence calibration ────────────────────────────────────────────────────
+def _bucket(conf: float) -> str:
+    if conf < 0.4:
+        return "lo"
+    if conf < 0.7:
+        return "mid"
+    return "hi"
+
+
+def _side(signal: str) -> str:
+    if signal in _BULL:
+        return "bull"
+    if signal in _BEAR:
+        return "bear"
+    return "neutral"
+
+
+def agreement(agent_signal: str, quant_verdict: str) -> str:
+    a = _side(agent_signal)
+    q = {"BULLISH": "bull", "BEARISH": "bear", "NEUTRAL": "neutral"}.get(quant_verdict, "neutral")
+    if a == "neutral" or q == "neutral":
+        return "neutral"
+    return "agree" if a == q else "disagree"
+
+
+class CalibrationStore:
+    """Tracks realised hit-rate per (signal-side, confidence-bucket) on disk.
+
+    ``reliability(conf, signal)`` returns observed_hit_rate / nominal_confidence,
+    clamped to a sane band, so a chronically over-confident bucket gets damped and
+    an under-confident one gets a small boost. With no history it returns 1.0.
+    """
+
+    _NOMINAL = {"lo": 0.30, "mid": 0.55, "hi": 0.80}
+
+    def __init__(self, path: Optional[Path] = None):
+        self.path = Path(path or os.path.expanduser("~/.arthera/deep_calibration.json"))
+        self._data: Dict[str, Dict[str, int]] = {}
+        try:
+            if self.path.exists():
+                self._data = json.loads(self.path.read_text())
+        except Exception:
+            self._data = {}
+
+    def _key(self, side: str, bucket: str) -> str:
+        return f"{side}:{bucket}"
+
+    def reliability(self, conf: float, signal: str = "") -> float:
+        rec = self._data.get(self._key(_side(signal), _bucket(conf)))
+        if not rec or rec.get("n", 0) < 8:
+            return 1.0
+        hit = rec["hit"] / rec["n"]
+        nominal = self._NOMINAL[_bucket(conf)] or 1.0
+        return max(0.6, min(1.25, hit / nominal))
+
+    def record_outcome(self, signal: str, conf: float, correct: bool) -> None:
+        k = self._key(_side(signal), _bucket(conf))
+        rec = self._data.setdefault(k, {"n": 0, "hit": 0})
+        rec["n"] += 1
+        rec["hit"] += 1 if correct else 0
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text(json.dumps(self._data, indent=2))
+        except Exception:
+            pass
+
+
+def calibrate_confidence(
+    raw_conf: float,
+    agent_signal: str,
+    quant: QuantEvidence,
+    store: Optional[CalibrationStore] = None,
+) -> Tuple[float, str]:
+    """Return (calibrated_confidence, agreement_label)."""
+    agree = agreement(agent_signal, quant.verdict()) if quant and quant.available else "neutral"
+    factor = {"agree": 1.15, "neutral": 1.0, "disagree": 0.70}[agree]
+    rel = store.reliability(raw_conf, agent_signal) if store else 1.0
+    cal = max(0.0, min(1.0, raw_conf * factor * rel))
+    return cal, agree

agents/deep/themes.py

@@ -0,0 +1,95 @@
+"""P1a — group agent results by theme and build a per-theme sub-synthesis.
+
+Flat synthesis ("here are 8 opinions, here's the average") loses structure. Real
+research clusters evidence: what does *valuation* say, what does *momentum* say,
+what does *risk* say — then reconciles across clusters. This module does the
+clustering and a deterministic per-cluster roll-up (no LLM needed).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Tuple
+
+from ..base import AgentResult
+from .models import ThemeGroup
+
+# Which theme each agent belongs to. Unknown agents fall into "other".
+_AGENT_THEME = {
+    "fundamental": "valuation",
+    "earnings":    "valuation",
+    "technical":   "momentum",
+    "risk":        "risk",
+    "news":        "catalysts",
+    "catalyst":    "catalysts",
+    "macro":       "macro",
+    "sector":      "macro",
+    "northbound":  "macro",
+    "debate":      "reconciliation",
+}
+
+# Display order + human labels.
+_THEME_ORDER = ["valuation", "momentum", "macro", "catalysts", "risk",
+                "reconciliation", "other"]
+_THEME_LABEL = {
+    "valuation":      "估值/基本面",
+    "momentum":       "动量/技术",
+    "macro":          "宏观/板块",
+    "catalysts":      "催化/消息",
+    "risk":           "风险",
+    "reconciliation": "分歧调解",
+    "other":          "其他",
+}
+
+_SCORE = {"STRONG_BUY": 2, "BUY": 1, "HOLD": 0, "SELL": -1, "STRONG_SELL": -2}
+
+
+def theme_of(agent_name: str) -> str:
+    return _AGENT_THEME.get(agent_name, "other")
+
+
+def _vote(results: List[AgentResult]) -> Tuple[str, float]:
+    """Confidence-weighted majority within a single theme."""
+    valid = [r for r in results if r.success and r.signal in _SCORE]
+    if not valid:
+        return "HOLD", 0.0
+    avg_score = sum(_SCORE[r.signal] * r.confidence for r in valid) / len(valid)
+    avg_conf = sum(r.confidence for r in valid) / len(valid)
+    if avg_score >= 1.5:
+        return "STRONG_BUY", avg_conf
+    if avg_score >= 0.5:
+        return "BUY", avg_conf
+    if avg_score <= -1.5:
+        return "STRONG_SELL", avg_conf
+    if avg_score <= -0.5:
+        return "SELL", avg_conf
+    return "HOLD", avg_conf
+
+
+def group_by_theme(results: List[AgentResult]) -> List[ThemeGroup]:
+    """Cluster agent results into themes with a per-theme signal + summary."""
+    buckets: Dict[str, List[AgentResult]] = {}
+    for r in results:
+        buckets.setdefault(theme_of(r.agent), []).append(r)
+
+    groups: List[ThemeGroup] = []
+    for theme in _THEME_ORDER:
+        members = buckets.get(theme)
+        if not members:
+            continue
+        signal, conf = _vote(members)
+        points: List[str] = []
+        for r in members:
+            if r.success:
+                points.extend((r.key_points or [])[:2])
+        ok = sum(1 for r in members if r.success)
+        summary = (f"{_THEME_LABEL[theme]}: {signal}（{ok}/{len(members)} agent 有效，"
+                   f"置信度 {conf:.0%}）")
+        groups.append(ThemeGroup(
+            theme=_THEME_LABEL[theme],
+            agents=[r.agent for r in members],
+            signal=signal,
+            confidence=conf,
+            summary=summary,
+            key_points=points[:5],
+        ))
+    return groups

agents/deep/tiers.py

@@ -0,0 +1,106 @@
+"""P3 — render the deep result at three depths, with data provenance.
+
+  brief    — one glance: signal, calibrated confidence, headline
+  standard — + per-theme roll-up + synthesis
+  deep     — + quant evidence + critique + provenance (data lineage) + agent points
+
+Pure text/markdown so it renders in the terminal; the HTML report layer can reuse
+the same DeepAnalysisResult.
+"""
+
+from __future__ import annotations
+
+from .models import DeepAnalysisResult
+
+_SIGNAL_ICON = {
+    "STRONG_BUY": "🟢🟢", "BUY": "🟢", "HOLD": "⚪",
+    "SELL": "🔴", "STRONG_SELL": "🔴🔴",
+}
+
+
+def _headline(r: DeepAnalysisResult) -> str:
+    icon = _SIGNAL_ICON.get(r.final_signal, "⚪")
+    conf = f"{r.calibrated_confidence:.0%}"
+    note = ""
+    if r.raw_confidence and abs(r.calibrated_confidence - r.raw_confidence) >= 0.05:
+        note = f"（原始 {r.raw_confidence:.0%} → 校准 {conf}）"
+    else:
+        note = f"（置信度 {conf}）"
+    return f"{icon} **{r.symbol} · {r.final_signal}** {note}"
+
+
+def render_brief(r: DeepAnalysisResult) -> str:
+    lines = [_headline(r)]
+    if r.quant and r.quant.available:
+        lines.append(f"  量化: {r.quant.verdict()}"
+                     + (f" · IC {r.quant.ic:.2f}" if r.quant.ic is not None else "")
+                     + (f" · Sharpe {r.quant.sharpe:.2f}" if r.quant.sharpe is not None else ""))
+    if r.critique and r.critique.high:
+        lines.append(f"  ⚠️ {r.critique.high[0].message}")
+    return "\n".join(lines)
+
+
+def render_standard(r: DeepAnalysisResult) -> str:
+    parts = [render_brief(r), ""]
+    if r.themes:
+        parts.append("### 分主题")
+        for t in r.themes:
+            parts.append(f"- {t.summary}")
+        parts.append("")
+    if r.synthesis:
+        parts.append("### 综合")
+        parts.append(r.synthesis)
+    return "\n".join(parts).rstrip()
+
+
+def render_deep(r: DeepAnalysisResult) -> str:
+    parts = [render_standard(r), ""]
+
+    if r.quant and r.quant.available:
+        q = r.quant
+        parts.append("### 量化地面真值")
+        row = []
+        if q.ai_signal:           row.append(f"AI信号 {q.ai_signal}")
+        if q.ai_score is not None:row.append(f"分值 {q.ai_score:+.2f}")
+        if q.ic is not None:      row.append(f"IC {q.ic:.3f}")
+        if q.sharpe is not None:  row.append(f"Sharpe {q.sharpe:.2f}")
+        if q.max_drawdown is not None: row.append(f"MaxDD {q.max_drawdown:.1%}")
+        if q.backtest_return is not None: row.append(f"回测收益 {q.backtest_return:+.1%}")
+        parts.append("- " + " · ".join(row) if row else "- (无)")
+        parts.append("")
+
+    if r.critique is not None:
+        parts.append("### 自检 (Critic)")
+        mark = "✅ 通过" if r.critique.passed else "❌ 存在高危问题"
+        parts.append(f"结论: {mark}" + ("（无问题）" if not r.critique.issues else ""))
+        for i in r.critique.issues:
+            sev = {"high": "🔴", "medium": "🟡", "low": "⚪"}.get(i.severity, "·")
+            parts.append(f"- {sev} [{i.kind}] {i.message}")
+        parts.append("")
+
+    if r.provenance:
+        parts.append("### 数据血缘")
+        parts.append("| 字段 | 来源 | 时效 | 备注 |")
+        parts.append("|------|------|------|------|")
+        for p in r.provenance:
+            parts.append(f"| {p.field} | {p.source} | {p.freshness} | {p.note} |")
+        parts.append("")
+
+    if r.agent_results:
+        parts.append("### 各 Agent 要点")
+        for a in r.agent_results:
+            if a.get("error"):
+                parts.append(f"- **{a['agent']}** ⚠️ {a['error']}")
+                continue
+            pts = a.get("key_points") or []
+            head = f"- **{a['agent']}** ({a.get('signal','?')}, {a.get('confidence',0):.0%})"
+            parts.append(head)
+            for pt in pts[:3]:
+                parts.append(f"    • {pt}")
+
+    return "\n".join(parts).rstrip()
+
+
+def render_tier(r: DeepAnalysisResult, tier: str = "standard") -> str:
+    return {"brief": render_brief, "standard": render_standard,
+            "deep": render_deep}.get(tier, render_standard)(r)

agents/financial/__init__.py

@@ -0,0 +1,10 @@
+from .technical    import TechnicalAgent
+from .macro        import MacroAgent
+from .fundamental  import FundamentalAgent
+from .risk         import RiskAgent
+from .synthesis    import SynthesisAgent
+
+__all__ = [
+    "TechnicalAgent", "MacroAgent",
+    "FundamentalAgent", "RiskAgent", "SynthesisAgent",
+]

agents/financial/catalyst.py

@@ -0,0 +1,279 @@
+"""
+agents/financial/catalyst.py — 催化剂检测 Agent
+================================================
+识别近期/即将到来的价格催化剂：财报日、股息除权、
+分析师评级变化、大宗交易/大股东增减持。
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List, Optional
+
+from ..base import BaseAgent, AgentResult
+
+logger = logging.getLogger(__name__)
+
+
+class CatalystAgent(BaseAgent):
+
+    name        = "catalyst"
+    description = "催化剂检测 — 财报日、股息除权、分析师评级变化"
+
+    _SYSTEM = (
+        "You are an event-driven equity analyst. Analyze the upcoming and recent "
+        "catalysts for a stock: earnings dates, ex-dividend dates, analyst rating "
+        "changes, and insider activity. Assess whether these catalysts are "
+        "likely to be POSITIVE (price-driving), NEUTRAL, or NEGATIVE. "
+        "Focus on timing: catalysts within 14 days are high-impact. "
+        "Conclude with: POSITIVE / NEUTRAL / NEGATIVE"
+    )
+
+    async def fetch_data(self, symbol: str) -> Dict[str, Any]:
+        data = await super().fetch_data(symbol)
+        catalysts: Dict[str, Any] = {}
+
+        try:
+            import yfinance as yf
+            ticker = yf.Ticker(symbol)
+
+            # 1. Earnings calendar
+            try:
+                cal = ticker.calendar
+                if cal is not None:
+                    if hasattr(cal, "to_dict"):
+                        cal = cal.to_dict()
+                    if isinstance(cal, dict):
+                        for k in ("Earnings Date", "earnings_date", "earningsDate"):
+                            v = cal.get(k)
+                            if v:
+                                catalysts["earnings_date"] = str(v[0] if isinstance(v, list) else v)
+                                break
+            except Exception as e:
+                logger.debug("[catalyst] calendar fetch %s: %s", symbol, e)
+
+            # 2. Recent analyst recommendations
+            try:
+                recs = ticker.recommendations
+                if recs is not None and not recs.empty:
+                    recs = recs.sort_index(ascending=False)
+                    recent_recs = recs.head(5)
+                    rec_list = []
+                    for ts, row in recent_recs.iterrows():
+                        rec_list.append({
+                            "date":  str(ts)[:10],
+                            "firm":  str(row.get("Firm", row.get("firm", ""))),
+                            "grade": str(row.get("To Grade", row.get("toGrade", row.get("action", "")))),
+                            "prev":  str(row.get("From Grade", row.get("fromGrade", ""))),
+                            "action": str(row.get("Action", row.get("action", ""))),
+                        })
+                    catalysts["recommendations"] = rec_list
+            except Exception as e:
+                logger.debug("[catalyst] recs fetch %s: %s", symbol, e)
+
+            # 3. Upcoming dividend
+            try:
+                info = ticker.info or {}
+                ex_div = info.get("exDividendDate")
+                div_rate = info.get("dividendRate") or info.get("trailingAnnualDividendRate")
+                if ex_div:
+                    from datetime import date
+                    ex_date = datetime.fromtimestamp(ex_div, tz=timezone.utc).date()
+                    days_to_exdiv = (ex_date - date.today()).days
+                    catalysts["ex_dividend"] = {
+                        "date": str(ex_date),
+                        "days_away": days_to_exdiv,
+                        "annual_rate": div_rate,
+                    }
+            except Exception as e:
+                logger.debug("[catalyst] dividend fetch %s: %s", symbol, e)
+
+            # 4. Short interest (proxy for contrarian catalyst)
+            try:
+                info = ticker.info or {}
+                short_ratio = info.get("shortRatio")
+                short_pct   = info.get("shortPercentOfFloat")
+                if short_ratio or short_pct:
+                    catalysts["short_interest"] = {
+                        "ratio":   short_ratio,
+                        "pct_float": short_pct,
+                    }
+            except Exception as e:
+                logger.debug("[catalyst] short interest %s: %s", symbol, e)
+
+        except Exception as e:
+            logger.debug("[catalyst] yfinance init %s: %s", symbol, e)
+
+        data["catalysts"] = catalysts
+        return data
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        catalysts = data.get("catalysts", {})
+        quote     = data.get("quote", {})
+        price     = quote.get("price", 0)
+
+        if not catalysts:
+            return AgentResult(
+                agent=self.name, symbol=symbol,
+                analysis=f"{symbol}: 未获取到催化剂数据。",
+                confidence=0.3, signal="HOLD",
+                key_points=["无近期催化剂数据"],
+            )
+
+        catalyst_block = _format_catalysts(catalysts)
+        urgency        = _assess_urgency(catalysts)
+
+        prompt = (
+            f"Stock: {symbol}  Price: {price}\n\n"
+            f"Catalysts:\n{catalyst_block}\n\n"
+            "Evaluate:\n"
+            "1. Most impactful upcoming catalyst and timing\n"
+            "2. Analyst sentiment trend (upgrades vs downgrades)\n"
+            "3. Event-driven trade setup (if any)\n"
+            "4. Risk of negative surprise\n"
+            "5. Conclude: POSITIVE / NEUTRAL / NEGATIVE"
+        )
+
+        analysis = await self._call_llm(self._SYSTEM, prompt, max_tokens=450)
+        if not analysis:
+            analysis = _template_analysis(symbol, catalysts, urgency)
+
+        signal, confidence = _derive_signal(analysis, catalysts, urgency)
+        key_points         = _build_key_points(catalysts, urgency)
+
+        return AgentResult(
+            agent=self.name, symbol=symbol,
+            analysis=analysis,
+            confidence=confidence,
+            signal=signal,
+            key_points=key_points,
+            data_used=catalysts,
+        )
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _format_catalysts(c: Dict) -> str:
+    lines = []
+
+    if "earnings_date" in c:
+        ed = c["earnings_date"]
+        try:
+            ed_dt = datetime.fromisoformat(str(ed).split()[0])
+            days  = (ed_dt.date() - datetime.today().date()).days
+            timing = f"（{days}天后）" if days >= 0 else f"（{-days}天前）"
+        except Exception:
+            timing = ""
+        lines.append(f"财报日: {ed}{timing}")
+
+    if "ex_dividend" in c:
+        d = c["ex_dividend"]
+        days_away = d.get("days_away", 999)
+        rate      = d.get("annual_rate", "")
+        rate_str  = f"  年化股息 {rate:.2f}" if rate else ""
+        lines.append(f"除息日: {d.get('date','')}（{days_away}天后）{rate_str}")
+
+    if "recommendations" in c:
+        for r in c["recommendations"][:3]:
+            action = r.get("action", "").upper()
+            firm   = r.get("firm", "")
+            grade  = r.get("grade", "")
+            prev   = r.get("prev", "")
+            change = f"{prev} → {grade}" if prev and prev != grade else grade
+            lines.append(f"分析师评级: [{r.get('date','')}] {firm} {action} {change}")
+
+    if "short_interest" in c:
+        si = c["short_interest"]
+        ratio = si.get("ratio")
+        pct   = si.get("pct_float")
+        parts = []
+        if ratio: parts.append(f"空头比率 {ratio:.1f}x")
+        if pct:   parts.append(f"流通股空仓 {pct*100:.1f}%")
+        if parts: lines.append(f"空头数据: {', '.join(parts)}")
+
+    return "\n".join(lines) or "无催化剂数据"
+
+
+def _assess_urgency(c: Dict) -> str:
+    if "earnings_date" in c:
+        try:
+            ed_dt = datetime.fromisoformat(str(c["earnings_date"]).split()[0])
+            days  = (ed_dt.date() - datetime.today().date()).days
+            if 0 <= days <= 7:
+                return "high"
+            if 0 <= days <= 14:
+                return "medium"
+        except Exception:
+            pass
+    exdiv = c.get("ex_dividend", {})
+    if 0 <= exdiv.get("days_away", 999) <= 5:
+        return "high"
+    return "low"
+
+
+def _derive_signal(analysis: str, c: Dict, urgency: str) -> tuple[str, float]:
+    text = analysis.upper()
+    recs = c.get("recommendations", [])
+    upgrades   = sum(1 for r in recs if "UPGRAD" in r.get("action", "").upper())
+    downgrades = sum(1 for r in recs if "DOWNGRAD" in r.get("action", "").upper())
+
+    if "POSITIVE" in text:
+        conf = 0.65 if urgency == "high" else 0.55
+        return "BUY", conf
+    if "NEGATIVE" in text:
+        conf = 0.65 if urgency == "high" else 0.55
+        return "SELL", conf
+
+    if upgrades > downgrades:
+        return "BUY", 0.5
+    if downgrades > upgrades:
+        return "SELL", 0.5
+    return "HOLD", 0.4
+
+
+def _build_key_points(c: Dict, urgency: str) -> List[str]:
+    points = []
+    if "earnings_date" in c:
+        try:
+            ed_dt = datetime.fromisoformat(str(c["earnings_date"]).split()[0])
+            days  = (ed_dt.date() - datetime.today().date()).days
+            points.append(f"财报日在 {days} 天后" if days >= 0 else f"财报 {-days} 天前已公布")
+        except Exception:
+            points.append(f"财报日: {c['earnings_date']}")
+    if "ex_dividend" in c:
+        d = c["ex_dividend"]
+        points.append(f"除息日 {d.get('date','')}（{d.get('days_away','')}天）")
+    recs = c.get("recommendations", [])
+    if recs:
+        latest = recs[0]
+        points.append(f"最新评级: {latest.get('firm','')} {latest.get('grade','')}")
+    if urgency == "high":
+        points.append("⚡ 高优先级催化剂（7天内）")
+    return points[:5]
+
+
+def _template_analysis(symbol: str, c: Dict, urgency: str) -> str:
+    parts = []
+    if "earnings_date" in c:
+        try:
+            ed_dt = datetime.fromisoformat(str(c["earnings_date"]).split()[0])
+            days  = (ed_dt.date() - datetime.today().date()).days
+            parts.append(f"财报日在 {days} 天{'后' if days >= 0 else '前'}")
+        except Exception:
+            parts.append(f"财报日: {c['earnings_date']}")
+    recs = c.get("recommendations", [])
+    upgrades   = sum(1 for r in recs if "UPGRAD" in r.get("action", "").upper())
+    downgrades = sum(1 for r in recs if "DOWNGRAD" in r.get("action", "").upper())
+    if upgrades or downgrades:
+        parts.append(f"近期评级: {upgrades}次升级 / {downgrades}次降级")
+    if "ex_dividend" in c:
+        d = c["ex_dividend"]
+        parts.append(f"除息日: {d.get('date','')}（{d.get('days_away','')}天）")
+
+    sentiment = "POSITIVE" if upgrades > downgrades else ("NEGATIVE" if downgrades > upgrades else "NEUTRAL")
+    return (
+        f"{symbol} 催化剂摘要：\n"
+        + "\n".join(f"  • {p}" for p in parts)
+        + f"\n结论：{sentiment}"
+    )