aria-code 4.1.3__py3-none-any.whl

agents/__init__.py

@@ -0,0 +1,32 @@
+"""
+agents/ — Aria Code 可组合多智能体系统
+=======================================
+用户可在项目根放置 aria_agents/ 目录，其中的 Agent 类自动被发现。
+
+内置 Agent:
+  macro       → 宏观环境、利率、行业周期
+  fundamental → 财务指标、估值、竞争壁垒
+  technical   → 图形形态、动量、关键价位
+  risk        → 风险评分、仓位建议
+  synthesis   → 汇总以上，输出可操作建议
+
+自定义 Agent 示例 (aria_agents/northbound_agent.py):
+    from agents.base import BaseAgent, AgentResult
+
+    class NorthboundAgent(BaseAgent):
+        name        = "northbound"
+        description = "北向资金分析专家"
+
+        async def analyze(self, symbol: str, data: dict) -> AgentResult:
+            ...
+"""
+
+from .base import BaseAgent, AgentResult
+from .registry import AgentRegistry, get_registry
+from .team import AgentTeam, run_team
+
+__all__ = [
+    "BaseAgent", "AgentResult",
+    "AgentRegistry", "get_registry",
+    "AgentTeam", "run_team",
+]

agents/base.py

@@ -0,0 +1,190 @@
+"""
+agents/base.py — Agent 统一抽象基类
+=====================================
+所有 agent 继承 BaseAgent，实现 analyze() 方法。
+LLM provider 和数据源从外部注入，agent 本身不关心底层实现。
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AgentResult:
+    """Agent 分析结果，统一输出格式"""
+    agent:       str                    # agent 名称
+    symbol:      str                    # 分析标的
+    analysis:    str                    # 核心分析文本
+    confidence:  float                  # 置信度 0.0-1.0
+    signal:      str = "HOLD"           # BUY / HOLD / SELL / STRONG_BUY / STRONG_SELL
+    key_points:  List[str] = field(default_factory=list)   # 关键结论（用于 synthesis）
+    data_used:   Dict[str, Any] = field(default_factory=dict)  # 使用的原始数据
+    error:       Optional[str] = None   # 失败时的错误信息
+
+    @property
+    def success(self) -> bool:
+        return self.error is None
+
+    def to_dict(self) -> Dict:
+        return {
+            "agent":      self.agent,
+            "symbol":     self.symbol,
+            "analysis":   self.analysis,
+            "confidence": self.confidence,
+            "signal":     self.signal,
+            "key_points": self.key_points,
+            "error":      self.error,
+        }
+
+
+class BaseAgent(ABC):
+    """
+    所有 Agent 的抽象基类。
+
+    子类必须声明:
+        name:        str   — 唯一标识（用于 /team --agents macro,fundamental）
+        description: str   — 简短描述（显示在 /help 中）
+
+    子类必须实现:
+        analyze(symbol, data) → AgentResult
+
+    可选覆盖:
+        fetch_data(symbol) → dict  — 自定义数据获取逻辑
+    """
+
+    name:        str = "base"
+    description: str = "基础 Agent"
+
+    # Post-training IPO facts injected into every agent's system prompt
+    _POST_TRAINING_FACTS = (
+        "\n\n## ⚡ Critical post-training facts (override training memory)\n"
+        "- **SPCX** = SpaceX (Space Exploration Technologies Corp.) — IPO'd June 12, 2026 "
+        "on NASDAQ. It is NOT an ETF. ⛔ Never say 'SPCX is a China ETF' or 'SPCX is private'.\n"
+        "- **2026 FIFA World Cup** opened June 11, 2026 in USA/Canada/Mexico.\n"
+    )
+
+    # Language rule injected per-call based on detected user language
+    _LANG_RULES = {
+        "zh": "\n\n## Language rule\nRespond in Chinese (中文). Technical terms (RSI, MACD, P/E, EPS) may stay in English.\n",
+        "en": "\n\n## Language rule\nRespond in English.\n",
+    }
+
+    def __init__(
+        self,
+        llm_provider=None,         # BaseLLMProvider 实例（可选，None 则用模板生成）
+        data_router=None,          # DataRouter 实例（可选）
+        on_token: Optional[Callable[[str], None]] = None,  # 流式 token 回调
+        config: Optional[Dict] = None,
+        lang: str = "zh",          # user language: "zh" | "en"
+    ):
+        self.llm      = llm_provider
+        self.data     = data_router
+        self.on_token = on_token
+        self.config   = config or {}
+        self.lang     = lang
+
+    async def fetch_data(self, symbol: str) -> Dict[str, Any]:
+        """
+        从数据路由器获取分析所需数据。
+        子类可覆盖此方法以自定义数据获取逻辑。
+        """
+        if not self.data:
+            return {}
+        result = {}
+        try:
+            q = self.data.quote(symbol)
+            if q:
+                result["quote"] = q.to_dict()
+        except Exception as e:
+            logger.debug(f"[{self.name}] fetch quote {symbol}: {e}")
+        return result
+
+    def _data_guard(self, quote: Dict[str, Any]) -> str:
+        """Return a warning string if real data is unavailable; empty string if data is present."""
+        price = quote.get("price") if quote else None
+        if not price or float(price) == 0:
+            return (
+                "\n\n## ⛔ DATA UNAVAILABLE — STRICT RULES\n"
+                "Real market data could not be fetched (price=0 or missing).\n"
+                "You MUST:\n"
+                "1. State clearly that no real data is available.\n"
+                "2. NEVER invent specific prices, P/E ratios, EPS, revenue, RSI, MACD, or any numbers.\n"
+                "3. NEVER give specific price targets, stop-loss levels, or entry prices.\n"
+                "4. Give only qualitative analysis based on publicly known company characteristics.\n"
+                "5. End with the signal word (BUY/HOLD/SELL) but with low confidence (≤40%).\n"
+            )
+        return ""
+
+    async def _call_llm(
+        self,
+        system: str,
+        user: str,
+        max_tokens: int = 800,
+        quote: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """调用 LLM 生成分析文本（无 LLM 时返回空字符串）"""
+        if not self.llm:
+            return ""
+        # Inject language rule + post-training facts + data guard into system prompt
+        _lang_rule = self._LANG_RULES.get(self.lang, self._LANG_RULES["zh"])
+        _data_warn = self._data_guard(quote or {})
+        system = system + self._POST_TRAINING_FACTS + _lang_rule + _data_warn
+        from providers.llm.base import Message
+        messages = [
+            Message(role="system", content=system),
+            Message(role="user",   content=user),
+        ]
+        full_text = ""
+        try:
+            async for event in self.llm.stream(
+                messages, max_tokens=max_tokens
+            ):
+                t = event.get("type")
+                if t == "token":
+                    tok = event.get("text", "")
+                    full_text += tok
+                    if self.on_token:
+                        self.on_token(tok)
+                elif t == "error":
+                    logger.warning(f"[{self.name}] LLM 错误: {event.get('message')}")
+                    break
+        except Exception as e:
+            logger.warning(f"[{self.name}] LLM 调用失败: {e}")
+        return full_text.strip()
+
+    @abstractmethod
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        """
+        核心分析方法。
+
+        Args:
+            symbol: 股票/资产代码
+            data:   由 fetch_data() 预取的数据字典
+
+        Returns:
+            AgentResult
+        """
+        ...
+
+    async def run(self, symbol: str) -> AgentResult:
+        """完整执行：fetch_data → analyze，异常自动捕获。"""
+        try:
+            data   = await self.fetch_data(symbol)
+            result = await self.analyze(symbol, data)
+            return result
+        except Exception as e:
+            logger.error(f"[{self.name}] run({symbol}) 失败: {e}", exc_info=True)
+            return AgentResult(
+                agent=self.name, symbol=symbol,
+                analysis="", confidence=0.0,
+                error=str(e),
+            )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name={self.name!r})"

agents/deep/__init__.py

@@ -0,0 +1,37 @@
+"""Deep analysis pipeline — Claude-Code-style layered research on top of AgentTeam.
+
+Adds the four "deep" layers the flat team pipeline was missing:
+
+  P0  deepen      — tool-augmented evidence gathering for material/uncertain findings
+  P1  hierarchical + critic — theme-grouped sub-synthesis, then a self-check pass
+  P2  quant fusion — fuse ML/backtest/risk signals as ground truth + calibrate confidence
+  P3  tiered output + provenance — brief / standard / deep reports with data lineage
+
+Everything degrades gracefully: any layer whose dependency (LLM, quant tools, data
+cleaner) is unavailable is skipped, never raised. The deterministic parts (theme
+grouping, calibration math, critic rules, tier rendering) run with no LLM/network,
+which keeps the pipeline testable.
+"""
+
+from __future__ import annotations
+
+from .models import (
+    Critique,
+    CritiqueIssue,
+    DeepAnalysisResult,
+    Provenance,
+    QuantEvidence,
+    ThemeGroup,
+)
+from .pipeline import DeepAnalysisPipeline, run_deep_analysis
+
+__all__ = [
+    "Critique",
+    "CritiqueIssue",
+    "DeepAnalysisResult",
+    "Provenance",
+    "QuantEvidence",
+    "ThemeGroup",
+    "DeepAnalysisPipeline",
+    "run_deep_analysis",
+]

agents/deep/calibration_loop.py

@@ -0,0 +1,144 @@
+"""P2 closed loop — log predictions, later score them against realised price.
+
+Calibration only improves if confidence is checked against what actually happened.
+This module:
+
+  1. logs every deep verdict (symbol, signal, confidence, reference price, time),
+  2. once a prediction's horizon has elapsed, fetches the realised return and
+     marks it correct/incorrect,
+  3. feeds the outcome into CalibrationStore so the reliability factor — and thus
+     future calibrated confidence — drifts toward the true hit-rate.
+
+Everything is injectable (price function, clock) so it tests without network.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from pathlib import Path
+from typing import Callable, Dict, List, Optional
+
+from .quant_fusion import CalibrationStore
+
+_BULL = ("STRONG_BUY", "BUY")
+_BEAR = ("STRONG_SELL", "SELL")
+
+
+def correctness(signal: str, ret: float, threshold: float = 0.02) -> bool:
+    """Was the call right given the realised return?"""
+    if signal in _BULL:
+        return ret > threshold
+    if signal in _BEAR:
+        return ret < -threshold
+    return abs(ret) <= threshold       # HOLD: right when it stayed flat
+
+
+class PredictionLog:
+    """Append-only log of deep verdicts, JSON-list backed (low volume)."""
+
+    def __init__(self, path: Optional[Path] = None):
+        self.path = Path(path or os.path.expanduser("~/.arthera/deep_predictions.json"))
+        self._items: List[Dict] = []
+        try:
+            if self.path.exists():
+                self._items = json.loads(self.path.read_text())
+        except Exception:
+            self._items = []
+
+    def _save(self) -> None:
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text(json.dumps(self._items, ensure_ascii=False, indent=2))
+        except Exception:
+            pass
+
+    def log(self, symbol: str, signal: str, confidence: float,
+            ref_price: float, ts: Optional[float] = None) -> str:
+        pid = uuid.uuid4().hex[:12]
+        self._items.append({
+            "id": pid, "symbol": symbol, "signal": signal,
+            "confidence": float(confidence), "ref_price": float(ref_price),
+            "ts": ts if ts is not None else time.time(), "evaluated": False,
+        })
+        self._save()
+        return pid
+
+    def pending(self, horizon_days: float, now: Optional[float] = None) -> List[Dict]:
+        now = now if now is not None else time.time()
+        cutoff = now - horizon_days * 86400
+        return [p for p in self._items if not p.get("evaluated") and p["ts"] <= cutoff]
+
+    def mark_evaluated(self, pid: str, ret: float, correct: bool,
+                       source: str = "price") -> None:
+        for p in self._items:
+            if p["id"] == pid:
+                p["evaluated"] = True
+                p["realised_return"] = ret
+                p["correct"] = correct
+                p["source"] = source
+                break
+        self._save()
+
+
+def evaluate_due(
+    store: CalibrationStore,
+    log: PredictionLog,
+    price_fn: Callable[[str], Optional[float]],
+    horizon_days: float = 5.0,
+    threshold: float = 0.02,
+    now: Optional[float] = None,
+) -> Dict[str, int]:
+    """Score every prediction past its horizon and update calibration. Returns counts."""
+    evaluated = hits = 0
+    for p in log.pending(horizon_days, now=now):
+        try:
+            cur = price_fn(p["symbol"])
+        except Exception:
+            cur = None
+        if not cur or not p.get("ref_price"):
+            continue
+        ret = (cur - p["ref_price"]) / p["ref_price"]
+        ok = correctness(p["signal"], ret, threshold)
+        store.record_outcome(p["signal"], p["confidence"], ok)
+        log.mark_evaluated(p["id"], round(ret, 5), ok)
+        evaluated += 1
+        hits += 1 if ok else 0
+    return {"evaluated": evaluated, "hits": hits,
+            "hit_rate": round(hits / evaluated, 3) if evaluated else 0.0}
+
+
+def evaluate_from_ledger(
+    store: CalibrationStore,
+    log: PredictionLog,
+    ledger,
+) -> Dict[str, int]:
+    """Score predictions against the portfolio ledger's REALISED P&L (actual closed
+    trades) — a stronger ground truth than market price for symbols you traded.
+
+    BUY is right when the symbol's realised P&L is positive, SELL when negative.
+    HOLD is skipped (no clean threshold without a cost basis). ``ledger`` is any
+    object exposing ``get_realized_pnl() -> [{symbol, realized_pnl, ...}]``.
+    """
+    try:
+        realized = ledger.get_realized_pnl()
+    except Exception:
+        return {"evaluated": 0, "hits": 0, "hit_rate": 0.0}
+    pnl_map = {str(r.get("symbol", "")).upper(): r.get("realized_pnl", 0.0)
+               for r in (realized or []) if r.get("realized_pnl")}
+
+    evaluated = hits = 0
+    for p in log.pending(0.0):          # any un-evaluated prediction
+        sym = str(p["symbol"]).upper()
+        if sym not in pnl_map or p["signal"] not in (_BULL + _BEAR):
+            continue
+        pnl = pnl_map[sym]
+        ok = (pnl > 0) if p["signal"] in _BULL else (pnl < 0)
+        store.record_outcome(p["signal"], p["confidence"], ok)
+        log.mark_evaluated(p["id"], round(pnl, 2), ok, source="ledger")
+        evaluated += 1
+        hits += 1 if ok else 0
+    return {"evaluated": evaluated, "hits": hits,
+            "hit_rate": round(hits / evaluated, 3) if evaluated else 0.0}

agents/deep/critic.py

@@ -0,0 +1,125 @@
+"""P1b — a self-check pass over the assembled analysis.
+
+Claude Code verifies its own work; the flat pipeline never did. The critic applies
+deterministic rules (no LLM, fully testable) to flag the failure modes that quietly
+ruin a research note: thin agent coverage, no risk angle, a strong call on weak
+confidence, or the quant signal contradicting the qualitative verdict. An optional
+LLM pass can add free-text findings on top.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from ..base import AgentResult
+from .models import Critique, CritiqueIssue, Provenance, QuantEvidence
+from .themes import theme_of
+
+_STRONG = ("STRONG_BUY", "STRONG_SELL")
+
+
+def critique(
+    agent_results: List[AgentResult],
+    final_signal: str,
+    calibrated_confidence: float,
+    quant: Optional[QuantEvidence] = None,
+    agreement: str = "neutral",
+    provenance: Optional[List[Provenance]] = None,
+    key_point_count: int = 0,
+) -> Critique:
+    """Deterministic self-check. Returns a Critique; ``passed`` is False on any
+    high-severity issue so the caller can soften an over-confident conclusion."""
+    issues: List[CritiqueIssue] = []
+
+    total = len(agent_results)
+    ok = sum(1 for r in agent_results if r.success)
+
+    # 1) coverage
+    if ok < 2:
+        issues.append(CritiqueIssue("high", "thin_coverage",
+            f"只有 {ok} 个 agent 成功，结论证据不足，不应作为决策依据。"))
+    elif total and ok / total < 0.5:
+        issues.append(CritiqueIssue("medium", "thin_coverage",
+            f"{total - ok}/{total} 个 agent 失败，覆盖偏薄。"))
+
+    # 2) risk angle present?
+    has_risk = any(r.success and theme_of(r.agent) == "risk" for r in agent_results)
+    if not has_risk:
+        issues.append(CritiqueIssue("medium", "missing_risk",
+            "缺少有效的风险维度分析，下行风险可能被低估。"))
+
+    # 3) quant contradicts qualitative verdict
+    if quant and quant.available and agreement == "disagree":
+        issues.append(CritiqueIssue("high", "conflict",
+            f"量化信号（{quant.verdict()}）与定性结论（{final_signal}）相反，置信度已下调；建议人工复核。"))
+
+    # 4) strong call on weak confidence
+    if final_signal in _STRONG and calibrated_confidence < 0.5:
+        issues.append(CritiqueIssue("medium", "unsupported",
+            f"给出强信号 {final_signal} 但校准后置信度仅 {calibrated_confidence:.0%}，"
+            "强度与把握不匹配。"))
+
+    # 5) strong call with little supporting evidence
+    if final_signal in _STRONG and key_point_count < 3:
+        issues.append(CritiqueIssue("medium", "unsupported",
+            "强信号但关键论据少于 3 条，论证偏薄。"))
+
+    # 6) stale data
+    for p in (provenance or []):
+        if p.freshness.endswith("d old"):
+            issues.append(CritiqueIssue("low", "stale_data",
+                f"{p.field} 数据为 {p.freshness}（来源 {p.source}），注意时效。"))
+
+    passed = not any(i.severity == "high" for i in issues)
+    return Critique(issues=issues, passed=passed)
+
+
+def soften_signal(final_signal: str) -> str:
+    """Step a verdict one notch toward HOLD (used when the critic fails)."""
+    ladder = {"STRONG_BUY": "BUY", "BUY": "HOLD", "HOLD": "HOLD",
+              "SELL": "HOLD", "STRONG_SELL": "SELL"}
+    return ladder.get(final_signal, "HOLD")
+
+
+_SEV = {"高": "high", "中": "medium", "低": "low",
+        "high": "high", "medium": "medium", "low": "low"}
+
+
+def parse_llm_issues(text: str, max_issues: int = 3) -> List[CritiqueIssue]:
+    """Parse the LLM reviewer's reply (``高|问题`` per line) into issues. Pure/testable."""
+    import re
+    issues: List[CritiqueIssue] = []
+    for line in (text or "").splitlines():
+        line = line.strip().lstrip("-•*0123456789. ").strip()
+        if not line or line.upper().startswith("OK") or line in ("无", "无问题"):
+            continue
+        parts = re.split(r"[|｜:：]", line, maxsplit=1)
+        if len(parts) == 2 and _SEV.get(parts[0].strip().lower()):
+            sev, msg = _SEV[parts[0].strip().lower()], parts[1].strip()
+        else:
+            sev, msg = "medium", line
+        if msg:
+            issues.append(CritiqueIssue(sev, "llm_review", msg))
+        if len(issues) >= max_issues:
+            break
+    return issues
+
+
+async def llm_critique(
+    symbol: str,
+    synthesis: str,
+    theme_summaries: str,
+    llm,
+    max_issues: int = 3,
+) -> List[CritiqueIssue]:
+    """Optional LLM reviewer — flags unsupported claims / missing risk / contradiction
+    / overconfidence in the synthesis. Returns extra issues (empty if no LLM)."""
+    if llm is None or not (synthesis or "").strip():
+        return []
+    from .deepen import _collect_llm
+    system = ("你是严格的研究审稿人。只挑【确凿的】问题：无数据支撑的论断、漏掉的下行风险、"
+              "自相矛盾、过度自信。每行一个，格式 `高|问题` / `中|问题` / `低|问题`，"
+              f"最多 {max_issues} 条。没有问题就只输出 OK。不要多余的话。")
+    user = f"标的: {symbol}\n各维度小结: {theme_summaries}\n\n综合结论:\n{synthesis}\n\n审查:"
+    resp = await _collect_llm(llm, system, user, max_tokens=300)
+    return parse_llm_issues(resp, max_issues)