aria-code 4.1.3__py3-none-any.whl

agents/deep/deepen.py

@@ -0,0 +1,193 @@
+"""P0 — tool-augmented deepening for material/uncertain findings.
+
+The flat agents summarise pre-fetched data in a single pass. This layer runs a
+small *gap-driven tool loop*: it looks at where the analysis is thin (no risk
+angle, momentum undecided, no catalyst coverage) and calls finance tools to pull
+the missing evidence — the same move Claude Code's agent loop makes when it needs
+more before concluding.
+
+v1 selects tools deterministically from the gaps (testable, no LLM). The selector
+is isolated in ``_plan_steps`` so an LLM-driven planner can drop in later without
+touching the execution loop. The tool runner is injectable for tests.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, List, Optional, Tuple
+
+from .models import Provenance, QuantEvidence, ThemeGroup
+
+
+def _default_runner(tool: str, params: Dict) -> Optional[Dict]:
+    try:
+        import local_finance_tools as lft
+    except Exception:
+        return None
+    fn = getattr(lft, tool, None)
+    if not fn:
+        return None
+    try:
+        return fn(params)
+    except Exception:
+        return None
+
+
+def _plan_steps(themes: List[ThemeGroup], quant: Optional[QuantEvidence]) -> List[Tuple[str, str]]:
+    """Decide which tools to call based on coverage gaps. Returns [(tool, label)]."""
+    by_theme = {t.theme: t for t in themes}
+    plan: List[Tuple[str, str]] = []
+
+    risk = next((t for k, t in by_theme.items() if k.startswith("风险")), None)
+    if risk is None or risk.confidence < 0.5:
+        plan.append(("_get_risk_metrics", "下行风险"))
+
+    mom = next((t for k, t in by_theme.items() if k.startswith("动量")), None)
+    if mom is not None and mom.signal == "HOLD":
+        plan.append(("_calculate_factors", "动量/因子"))
+
+    cat = next((t for k, t in by_theme.items() if k.startswith("催化")), None)
+    if cat is None:
+        plan.append(("_analyze_news", "催化/消息"))
+
+    # quant undecided → a backtest gives an independent, data-grounded read
+    if quant is None or not quant.available or quant.verdict() == "NEUTRAL":
+        plan.append(("_backtest_strategy", "策略回测"))
+
+    return plan
+
+
+def _summarize(tool: str, res: Dict) -> str:
+    if tool == "_get_risk_metrics":
+        bits = []
+        if "var_daily" in res:     bits.append(f"日VaR {res['var_daily']:.1%}")
+        for k in ("sharpe", "sharpe_ratio"):
+            if isinstance(res.get(k), (int, float)): bits.append(f"Sharpe {res[k]:.2f}"); break
+        for k in ("max_drawdown", "max_dd"):
+            if isinstance(res.get(k), (int, float)): bits.append(f"MaxDD {res[k]:.1%}"); break
+        return "，".join(bits)
+    if tool == "_calculate_factors":
+        bits = [f"{k}={v:.3f}" for k, v in res.items()
+                if isinstance(v, (int, float)) and k in
+                ("momentum", "volatility", "beta", "rsi", "ic")][:4]
+        return "，".join(bits)
+    if tool == "_analyze_news":
+        s = res.get("sentiment") or res.get("score")
+        return f"新闻情绪 {s}" if s is not None else (res.get("summary", "")[:80])
+    if tool == "_backtest_strategy":
+        bits = []
+        for k in ("total_return", "return", "cagr"):
+            if isinstance(res.get(k), (int, float)): bits.append(f"收益 {res[k]:+.1%}"); break
+        for k in ("sharpe", "sharpe_ratio"):
+            if isinstance(res.get(k), (int, float)): bits.append(f"Sharpe {res[k]:.2f}"); break
+        return "，".join(bits)
+    return ""
+
+
+def deepen(
+    symbol: str,
+    themes: List[ThemeGroup],
+    quant: Optional[QuantEvidence] = None,
+    tool_runner: Optional[Callable[[str, Dict], Optional[Dict]]] = None,
+    max_steps: int = 3,
+) -> Tuple[List[str], List[Provenance]]:
+    """Deterministic gap-driven tool loop. Returns (deepening_notes, provenance)."""
+    runner = tool_runner or _default_runner
+    notes: List[str] = []
+    prov: List[Provenance] = []
+    for tool, label in _plan_steps(themes, quant)[:max_steps]:
+        res = None
+        try:
+            res = runner(tool, {"symbol": symbol})
+        except Exception:
+            res = None
+        if isinstance(res, dict) and res.get("success"):
+            line = _summarize(tool, res)
+            if line:
+                notes.append(f"[{label}] {line}")
+                prov.append(Provenance(label, f"deepen:{tool}"))
+    return notes, prov
+
+
+# ── P0 agentic: LLM-driven tool loop (plan → act → observe → re-plan) ──────────
+_TOOL_MENU = {
+    "_get_risk_metrics":      "下行风险:VaR / Sharpe / 最大回撤",
+    "_calculate_factors":     "量化因子:动量 / 波动 / Beta / IC",
+    "_analyze_news":          "新闻情绪与催化事件",
+    "_backtest_strategy":     "对该标的做策略回测(收益/Sharpe)",
+    "_get_sector_performance":"所属板块近期表现",
+    "_get_northbound_flow":   "北向资金流向(A股)",
+}
+
+
+async def _collect_llm(llm, system: str, user: str, max_tokens: int = 120) -> str:
+    try:
+        from providers.llm.base import Message
+    except Exception:
+        return ""
+    msgs = [Message(role="system", content=system), Message(role="user", content=user)]
+    out = ""
+    try:
+        async for ev in llm.stream(msgs, max_tokens=max_tokens):
+            if ev.get("type") == "token":
+                out += ev.get("text", "")
+            elif ev.get("type") == "error":
+                break
+    except Exception:
+        return ""
+    return out.strip()
+
+
+async def _llm_pick_tool(llm, symbol: str, context: str, used: set) -> str:
+    menu = "\n".join(f"- {t}: {d}" for t, d in _TOOL_MENU.items() if t not in used)
+    if not menu:
+        return "DONE"
+    system = ("你是量化研究的工具调度器。看已知信息的缺口，从工具清单里挑【最该补的一个】"
+              "来补证据。只输出工具名(如 _get_risk_metrics)；证据已够就只输出 DONE。不要解释。")
+    user = f"标的: {symbol}\n已知:\n{context}\n\n可用工具:\n{menu}\n\n选一个工具名或 DONE:"
+    resp = (await _collect_llm(llm, system, user)).strip()
+    for t in _TOOL_MENU:
+        if t in resp and t not in used:
+            return t
+    return "DONE"
+
+
+def _gap_summary(themes: List[ThemeGroup], quant: Optional[QuantEvidence]) -> str:
+    bits = [t.summary for t in themes]
+    if quant and quant.available:
+        bits.append(f"量化: {quant.verdict()}")
+    return "；".join(bits) or "(无)"
+
+
+async def deepen_agentic(
+    symbol: str,
+    themes: List[ThemeGroup],
+    quant: Optional[QuantEvidence] = None,
+    llm=None,
+    tool_runner: Optional[Callable[[str, Dict], Optional[Dict]]] = None,
+    max_steps: int = 3,
+) -> Tuple[List[str], List[Provenance]]:
+    """LLM-driven deepening loop. Falls back to the deterministic planner if no LLM."""
+    if llm is None:
+        return deepen(symbol, themes, quant, tool_runner, max_steps)
+    runner = tool_runner or _default_runner
+    notes: List[str] = []
+    prov: List[Provenance] = []
+    used: set = set()
+    context = _gap_summary(themes, quant)
+    for _ in range(max_steps):
+        tool = await _llm_pick_tool(llm, symbol, context, used)
+        if not tool or tool == "DONE":
+            break
+        used.add(tool)
+        res = None
+        try:
+            res = runner(tool, {"symbol": symbol})
+        except Exception:
+            res = None
+        if isinstance(res, dict) and res.get("success"):
+            line = _summarize(tool, res) or "已查询"
+            label = _TOOL_MENU.get(tool, tool).split(":")[0][:8]
+            notes.append(f"[{label}] {line}")
+            prov.append(Provenance(label, f"deepen:{tool}"))
+            context += f"\n已补({label}): {line}"
+    return notes, prov

agents/deep/models.py

@@ -0,0 +1,149 @@
+"""Structured data model for the deep analysis pipeline.
+
+Everything the pipeline produces is captured here as plain dataclasses with
+``to_dict()`` so the whole analysis is machine-readable (downstream tools, audit,
+training data) — not just a blob of synthesis text.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+# ── P3: data provenance / lineage ─────────────────────────────────────────────
+@dataclass
+class Provenance:
+    """Where a datum came from and how fresh it is."""
+    field:        str                       # e.g. "price", "fundamentals", "ai_signal"
+    source:       str                       # e.g. "yfinance", "akshare", "ml_pipeline"
+    fetched_at:   float = field(default_factory=time.time)
+    age_sec:      Optional[float] = None    # data age (not fetch age) when known
+    note:         str = ""
+
+    @property
+    def freshness(self) -> str:
+        age = self.age_sec if self.age_sec is not None else (time.time() - self.fetched_at)
+        if age < 90:
+            return "live"
+        if age < 3600:
+            return f"{int(age // 60)}m old"
+        if age < 86400:
+            return f"{int(age // 3600)}h old"
+        return f"{int(age // 86400)}d old"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"field": self.field, "source": self.source,
+                "freshness": self.freshness, "note": self.note}
+
+
+# ── P2: quantitative ground truth ─────────────────────────────────────────────
+@dataclass
+class QuantEvidence:
+    """Quantitative signals used to anchor and calibrate the qualitative verdict."""
+    ai_signal:        Optional[str] = None      # BUY/HOLD/SELL from the quant model
+    ai_score:         Optional[float] = None     # -1..1 expected-return-ish score
+    ic:               Optional[float] = None      # information coefficient (model skill)
+    sharpe:           Optional[float] = None
+    max_drawdown:     Optional[float] = None
+    backtest_return:  Optional[float] = None
+    factors:          Dict[str, Any] = field(default_factory=dict)
+    available:        bool = False
+    note:             str = ""
+
+    def verdict(self) -> str:
+        """Collapse the quant signals into BULLISH / BEARISH / NEUTRAL."""
+        if not self.available:
+            return "NEUTRAL"
+        if self.ai_signal in ("STRONG_BUY", "BUY"):
+            return "BULLISH"
+        if self.ai_signal in ("STRONG_SELL", "SELL"):
+            return "BEARISH"
+        if self.ai_score is not None:
+            if self.ai_score >= 0.15:
+                return "BULLISH"
+            if self.ai_score <= -0.15:
+                return "BEARISH"
+        return "NEUTRAL"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "ai_signal": self.ai_signal, "ai_score": self.ai_score,
+            "ic": self.ic, "sharpe": self.sharpe,
+            "max_drawdown": self.max_drawdown, "backtest_return": self.backtest_return,
+            "verdict": self.verdict(), "available": self.available, "note": self.note,
+        }
+
+
+# ── P1: hierarchical synthesis ────────────────────────────────────────────────
+@dataclass
+class ThemeGroup:
+    """A cluster of agents that speak to the same theme (valuation, momentum, …)."""
+    theme:        str
+    agents:       List[str] = field(default_factory=list)
+    signal:       str = "HOLD"
+    confidence:   float = 0.0
+    summary:      str = ""
+    key_points:   List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"theme": self.theme, "agents": self.agents, "signal": self.signal,
+                "confidence": round(self.confidence, 3), "summary": self.summary,
+                "key_points": self.key_points}
+
+
+# ── P1: critic / self-check ───────────────────────────────────────────────────
+@dataclass
+class CritiqueIssue:
+    severity: str       # "high" | "medium" | "low"
+    kind:     str       # "unsupported" | "missing_risk" | "stale_data" | "thin_coverage" | "conflict"
+    message:  str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"severity": self.severity, "kind": self.kind, "message": self.message}
+
+
+@dataclass
+class Critique:
+    issues:  List[CritiqueIssue] = field(default_factory=list)
+    passed:  bool = True
+
+    @property
+    def high(self) -> List[CritiqueIssue]:
+        return [i for i in self.issues if i.severity == "high"]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"passed": self.passed, "issues": [i.to_dict() for i in self.issues]}
+
+
+# ── Top-level result ──────────────────────────────────────────────────────────
+@dataclass
+class DeepAnalysisResult:
+    symbol:               str
+    final_signal:         str = "HOLD"
+    raw_confidence:       float = 0.0        # team vote, uncalibrated
+    calibrated_confidence: float = 0.0       # after quant fusion + reliability
+    themes:               List[ThemeGroup] = field(default_factory=list)
+    quant:                Optional[QuantEvidence] = None
+    critique:             Optional[Critique] = None
+    provenance:           List[Provenance] = field(default_factory=list)
+    synthesis:            str = ""           # top-level narrative (post-critic)
+    agent_results:        List[Dict[str, Any]] = field(default_factory=list)
+    elapsed_sec:          float = 0.0
+    error:                Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "symbol": self.symbol,
+            "final_signal": self.final_signal,
+            "raw_confidence": round(self.raw_confidence, 3),
+            "calibrated_confidence": round(self.calibrated_confidence, 3),
+            "themes": [t.to_dict() for t in self.themes],
+            "quant": self.quant.to_dict() if self.quant else None,
+            "critique": self.critique.to_dict() if self.critique else None,
+            "provenance": [p.to_dict() for p in self.provenance],
+            "synthesis": self.synthesis,
+            "elapsed_sec": self.elapsed_sec,
+            "error": self.error,
+        }

agents/deep/pipeline.py

@@ -0,0 +1,164 @@
+"""Deep analysis orchestrator — ties P0–P3 into one layered pass.
+
+    team (parallel agents) ─▶ group by theme (P1a) ─▶ deepen gaps (P0)
+        ─▶ quant fusion (P2) ─▶ vote ─▶ calibrate (P2) ─▶ critic (P1b)
+        ─▶ synthesis ─▶ tiered result (P3)
+
+``analyze()`` is the deterministic core (assembles a DeepAnalysisResult from given
+agent results); it needs no LLM or network and is fully unit-tested. ``run()`` is
+the async convenience that first runs the AgentTeam, then calls ``analyze()``.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Callable, Dict, List, Optional
+
+from ..base import AgentResult
+from .critic import critique, soften_signal
+from .deepen import deepen
+from .models import DeepAnalysisResult
+from .quant_fusion import CalibrationStore, calibrate_confidence, gather_quant_evidence
+from .themes import group_by_theme
+
+
+def _vote_all(results: List[AgentResult]):
+    """Confidence-weighted majority over every successful result."""
+    try:
+        from ..team import _vote_signal
+        return _vote_signal(results)
+    except Exception:
+        return "HOLD", 0.0
+
+
+def _build_synthesis(themes, notes, team_synthesis, agree, quant) -> str:
+    parts: List[str] = []
+    if team_synthesis and team_synthesis.strip():
+        parts.append(team_synthesis.strip())
+    elif themes:
+        parts.append("；".join(t.summary for t in themes))
+    if notes:
+        parts.append("补充证据（深挖）：" + "；".join(notes))
+    if quant and quant.available:
+        if agree == "disagree":
+            parts.append(f"⚠️ 量化信号为 {quant.verdict()}，与定性方向相反，已下调置信度，建议人工复核。")
+        elif agree == "agree":
+            parts.append(f"量化信号（{quant.verdict()}）与定性方向一致，置信度已上调。")
+    return "\n\n".join(p for p in parts if p)
+
+
+class DeepAnalysisPipeline:
+    def __init__(self, llm_provider=None, data_router=None,
+                 store: Optional[CalibrationStore] = None, lang: str = "zh"):
+        self.llm = llm_provider
+        self.data = data_router
+        self.store = store if store is not None else CalibrationStore()
+        self.lang = lang
+
+    def analyze(
+        self,
+        symbol: str,
+        agent_results: List[AgentResult],
+        *,
+        team_synthesis: str = "",
+        quant_provider: Optional[Callable[[str], Dict[str, Dict]]] = None,
+        tool_runner: Optional[Callable[[str, Dict], Optional[Dict]]] = None,
+        deepen_result: Optional[tuple] = None,
+    ) -> DeepAnalysisResult:
+        """Deterministic assembly of the deep result (no LLM/network required).
+
+        ``deepen_result`` lets ``run()`` inject the LLM-driven (agentic) deepening
+        output; when absent the deterministic gap planner runs instead.
+        """
+        if not agent_results:
+            return DeepAnalysisResult(symbol=symbol, error="no_agent_results")
+
+        themes = group_by_theme(agent_results)                       # P1a
+        quant, qprov = gather_quant_evidence(symbol, quant_provider)  # P2
+        if deepen_result is not None:                                 # P0 (agentic, injected)
+            notes, dprov = deepen_result
+        else:
+            notes, dprov = deepen(symbol, themes, quant, tool_runner)  # P0 (deterministic)
+
+        raw_signal, raw_conf = _vote_all(agent_results)
+        cal_conf, agree = calibrate_confidence(raw_conf, raw_signal, quant, self.store)  # P2
+
+        kp_count = sum(len(t.key_points) for t in themes)
+        crit = critique(agent_results, raw_signal, cal_conf, quant, agree,  # P1b
+                        qprov + dprov, kp_count)
+
+        final_signal = raw_signal if crit.passed else soften_signal(raw_signal)
+        synthesis = _build_synthesis(themes, notes, team_synthesis, agree, quant)
+
+        return DeepAnalysisResult(
+            symbol=symbol,
+            final_signal=final_signal,
+            raw_confidence=raw_conf,
+            calibrated_confidence=cal_conf,
+            themes=themes,
+            quant=quant,
+            critique=crit,
+            provenance=qprov + dprov,
+            synthesis=synthesis,
+            agent_results=[r.to_dict() for r in agent_results],
+        )
+
+    async def run(
+        self,
+        symbol: str,
+        agents: Optional[List[str]] = None,
+        quant_provider: Optional[Callable] = None,
+        tool_runner: Optional[Callable] = None,
+        on_agent_done: Optional[Callable] = None,
+    ) -> DeepAnalysisResult:
+        t0 = time.time()
+        from ..team import AgentTeam
+        team = AgentTeam(llm_provider=self.llm, data_router=self.data,
+                         on_agent_done=on_agent_done, lang=self.lang)
+        tr = await team.run(symbol, agents=agents)
+
+        # P0 agentic deepening (LLM-driven tool loop) when an LLM is available.
+        deepen_result = None
+        if self.llm and tr.results:
+            try:
+                from .deepen import deepen_agentic
+                from .themes import group_by_theme as _grp
+                deepen_result = await deepen_agentic(
+                    symbol, _grp(tr.results), None, self.llm, tool_runner)
+            except Exception:
+                deepen_result = None
+
+        res = self.analyze(symbol, tr.results, team_synthesis=tr.synthesis,
+                           quant_provider=quant_provider, tool_runner=tool_runner,
+                           deepen_result=deepen_result)
+
+        # P1b LLM self-check — augments the deterministic critic when an LLM is present.
+        if self.llm and res.critique is not None and res.synthesis:
+            try:
+                from .critic import llm_critique, soften_signal
+                theme_sum = "；".join(t.summary for t in res.themes)
+                extra = await llm_critique(symbol, res.synthesis, theme_sum, self.llm)
+                if extra:
+                    had_high = bool(res.critique.high)
+                    res.critique.issues.extend(extra)
+                    new_high = any(i.severity == "high" for i in extra)
+                    if new_high:
+                        res.critique.passed = False
+                        # soften once if the deterministic pass had cleared it
+                        if not had_high:
+                            res.final_signal = soften_signal(res.final_signal)
+            except Exception:
+                pass
+
+        res.elapsed_sec = round(time.time() - t0, 1)
+        if tr.error and not tr.results:
+            res.error = tr.error
+        return res
+
+
+async def run_deep_analysis(symbol: str, llm_provider=None, data_router=None,
+                            agents: Optional[List[str]] = None, lang: str = "zh",
+                            **kw) -> DeepAnalysisResult:
+    """Convenience: run the full team + deep pipeline for ``symbol``."""
+    pipe = DeepAnalysisPipeline(llm_provider=llm_provider, data_router=data_router, lang=lang)
+    return await pipe.run(symbol, agents=agents, **kw)