aria-code 0.52.0__py3-none-any.whl

aria_code/agents/financial/earnings.py

@@ -0,0 +1,303 @@
+"""
+agents/financial/earnings.py — 财报解读 Agent
+=============================================
+分析最近一期财报：EPS/营收 beat or miss、同比/环比变化、
+指引调整及市场反应。在财报发布后 5 天内尤为有效。
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta
+from typing import Any, Dict, List, Optional
+
+from ..base import BaseAgent, AgentResult
+
+logger = logging.getLogger(__name__)
+
+
+class EarningsAgent(BaseAgent):
+
+    name        = "earnings"
+    description = "财报解读 — EPS/营收 beat or miss、同比增速、指引变化"
+
+    _SYSTEM = (
+        "You are a financial analyst specializing in earnings analysis. "
+        "Evaluate the most recent quarterly earnings report:\n"
+        "1. Was it a beat or miss on EPS and revenue?\n"
+        "2. How does this compare to prior quarters (trend)?\n"
+        "3. Was guidance raised, lowered, or maintained?\n"
+        "4. What is the market likely to do with this information?\n"
+        "5. Conclude: STRONG_BEAT / BEAT / IN_LINE / MISS / STRONG_MISS\n"
+        "Map to signal: BEAT/STRONG_BEAT→BUY, IN_LINE→HOLD, MISS/STRONG_MISS→SELL"
+    )
+
+    async def fetch_data(self, symbol: str) -> Dict[str, Any]:
+        data = await super().fetch_data(symbol)
+        earnings: Dict[str, Any] = {}
+
+        try:
+            import yfinance as yf
+            ticker = yf.Ticker(symbol)
+
+            # 1. Quarterly earnings history
+            try:
+                qe = ticker.quarterly_earnings
+                if qe is not None and not qe.empty:
+                    rows = []
+                    for ts, row in qe.sort_index(ascending=False).head(4).iterrows():
+                        rows.append({
+                            "period": str(ts)[:10],
+                            "actual_eps":   _safe_float(row.get("Earnings")),
+                            "est_eps":      _safe_float(row.get("Estimate", row.get("EPS Estimate"))),
+                            "revenue":      _safe_float(row.get("Revenue")),
+                            "rev_estimate": _safe_float(row.get("Revenue Estimate")),
+                        })
+                    earnings["quarterly_eps"] = rows
+            except Exception as e:
+                logger.debug("[earnings] quarterly_earnings %s: %s", symbol, e)
+
+            # 2. Earnings dates
+            try:
+                ed = ticker.earnings_dates
+                if ed is not None and not ed.empty:
+                    recent = ed.sort_index(ascending=False).head(2)
+                    dates = []
+                    for ts, row in recent.iterrows():
+                        reported_eps = _safe_float(row.get("Reported EPS", row.get("EPS")))
+                        est_eps      = _safe_float(row.get("EPS Estimate"))
+                        if reported_eps is not None:
+                            beat = reported_eps - est_eps if est_eps is not None else None
+                            dates.append({
+                                "date": str(ts)[:10],
+                                "reported_eps": reported_eps,
+                                "estimated_eps": est_eps,
+                                "beat_by": round(beat, 4) if beat is not None else None,
+                                "pct_surprise": round(beat / abs(est_eps) * 100, 1)
+                                if (beat is not None and est_eps and est_eps != 0) else None,
+                            })
+                    earnings["recent_reports"] = dates
+            except Exception as e:
+                logger.debug("[earnings] earnings_dates %s: %s", symbol, e)
+
+            # 3. Revenue trend (quarterly income)
+            try:
+                qs = ticker.quarterly_financials
+                if qs is not None and not qs.empty:
+                    rev_row = None
+                    for label in ("Total Revenue", "Revenue", "Net Revenue"):
+                        if label in qs.index:
+                            rev_row = qs.loc[label]
+                            break
+                    if rev_row is not None:
+                        revs = []
+                        for ts, val in rev_row.sort_index(ascending=False).head(4).items():
+                            revs.append({"period": str(ts)[:10], "revenue": _safe_float(val)})
+                        earnings["revenue_trend"] = revs
+            except Exception as e:
+                logger.debug("[earnings] quarterly_financials %s: %s", symbol, e)
+
+            # 4. Stock price reaction (compare price before/after earnings)
+            try:
+                recent = earnings.get("recent_reports", [])
+                if recent:
+                    from datetime import date
+                    report_date_str = recent[0].get("date", "")
+                    if report_date_str:
+                        hist = ticker.history(start=report_date_str, period="5d")
+                        if not hist.empty and len(hist) >= 2:
+                            open_price  = float(hist["Open"].iloc[0])
+                            close_price = float(hist["Close"].iloc[-1])
+                            earnings["price_reaction_pct"] = round(
+                                (close_price - open_price) / open_price * 100, 2
+                            )
+            except Exception as e:
+                logger.debug("[earnings] price_reaction %s: %s", symbol, e)
+
+        except Exception as e:
+            logger.debug("[earnings] yfinance init %s: %s", symbol, e)
+
+        data["earnings"] = earnings
+        return data
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        earnings = data.get("earnings", {})
+        quote    = data.get("quote", {})
+        price    = quote.get("price", 0)
+
+        if not earnings:
+            return AgentResult(
+                agent=self.name, symbol=symbol,
+                analysis=f"{symbol}: 未获取到财报数据。",
+                confidence=0.3, signal="HOLD",
+                key_points=["无财报数据"],
+            )
+
+        earnings_block    = _format_earnings(earnings)
+        most_recent       = earnings.get("recent_reports", [{}])[0] if earnings.get("recent_reports") else {}
+        beat_miss_summary = _assess_beat_miss(most_recent, earnings)
+
+        prompt = (
+            f"Stock: {symbol}  Price: {price}\n\n"
+            f"Earnings Data:\n{earnings_block}\n\n"
+            f"Initial Assessment: {beat_miss_summary}\n\n"
+            "Provide detailed earnings analysis:\n"
+            "1. Most recent quarter: beat or miss? By how much?\n"
+            "2. Revenue & EPS trend direction (improving / deteriorating / stable)\n"
+            "3. Likely market interpretation\n"
+            "4. Conclude: STRONG_BEAT / BEAT / IN_LINE / MISS / STRONG_MISS"
+        )
+
+        analysis = await self._call_llm(self._SYSTEM, prompt, max_tokens=500)
+        if not analysis:
+            analysis = _template_analysis(symbol, earnings, most_recent, beat_miss_summary)
+
+        signal, confidence = _derive_signal(analysis, most_recent, earnings)
+        key_points         = _build_key_points(earnings, most_recent, signal)
+
+        return AgentResult(
+            agent=self.name, symbol=symbol,
+            analysis=analysis,
+            confidence=confidence,
+            signal=signal,
+            key_points=key_points,
+            data_used={
+                "beat_miss": beat_miss_summary,
+                "pct_surprise": most_recent.get("pct_surprise"),
+                "price_reaction_pct": earnings.get("price_reaction_pct"),
+            },
+        )
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _safe_float(val) -> Optional[float]:
+    try:
+        v = float(val)
+        return None if (v != v) else v  # NaN check
+    except (TypeError, ValueError):
+        return None
+
+
+def _format_earnings(e: Dict) -> str:
+    lines = []
+    recent = e.get("recent_reports", [])
+    if recent:
+        lines.append("Recent Reports:")
+        for r in recent[:2]:
+            act = r.get("reported_eps")
+            est = r.get("estimated_eps")
+            sup = r.get("pct_surprise")
+            lines.append(
+                f"  {r.get('date','')}  EPS: actual {act}  est {est}  "
+                f"surprise {sup:+.1f}%" if sup else
+                f"  {r.get('date','')}  EPS: actual {act}  est {est}"
+            )
+
+    rx = e.get("price_reaction_pct")
+    if rx is not None:
+        lines.append(f"Post-earnings price reaction: {rx:+.1f}%")
+
+    qt = e.get("quarterly_eps", [])
+    if qt:
+        lines.append("Quarterly EPS (last 4):")
+        for q in qt[:4]:
+            ep = q.get("actual_eps")
+            lines.append(f"  {q.get('period','')}  EPS: {ep}")
+
+    rev = e.get("revenue_trend", [])
+    if rev:
+        lines.append("Revenue Trend (last 4 quarters):")
+        prev = None
+        for r in rev[:4]:
+            rv = r.get("revenue")
+            growth = ""
+            if rv and prev:
+                g = (rv - prev) / abs(prev) * 100
+                growth = f"  {g:+.1f}% QoQ"
+            lines.append(f"  {r.get('period','')}  {_fmt_num(rv)}{growth}")
+            prev = rv
+
+    return "\n".join(lines) or "无财报数据"
+
+
+def _fmt_num(v) -> str:
+    if v is None: return "N/A"
+    if abs(v) >= 1e9:  return f"${v/1e9:.2f}B"
+    if abs(v) >= 1e6:  return f"${v/1e6:.1f}M"
+    return f"{v:.4f}"
+
+
+def _assess_beat_miss(most_recent: Dict, earnings: Dict) -> str:
+    sup = most_recent.get("pct_surprise")
+    if sup is None:
+        return "无充分数据判断"
+    if sup >= 10:  return f"大幅超预期 +{sup:.1f}%"
+    if sup >= 3:   return f"超预期 +{sup:.1f}%"
+    if sup >= -3:  return f"基本符合预期 {sup:+.1f}%"
+    if sup >= -10: return f"略低预期 {sup:.1f}%"
+    return f"大幅低于预期 {sup:.1f}%"
+
+
+def _derive_signal(analysis: str, most_recent: Dict, earnings: Dict) -> tuple[str, float]:
+    text  = analysis.upper()
+    sup   = most_recent.get("pct_surprise")
+    rx    = earnings.get("price_reaction_pct")
+
+    if "STRONG_BEAT" in text:
+        return "BUY", 0.75
+    if "STRONG_MISS" in text:
+        return "SELL", 0.75
+    if "BEAT" in text and "MISS" not in text:
+        conf = 0.65 if (rx and rx > 2) else 0.55
+        return "BUY", conf
+    if "MISS" in text and "BEAT" not in text:
+        conf = 0.65 if (rx and rx < -2) else 0.55
+        return "SELL", conf
+
+    # Fallback to raw surprise
+    if sup is not None:
+        if sup >= 10:  return "BUY",  0.70
+        if sup >= 3:   return "BUY",  0.55
+        if sup <= -10: return "SELL", 0.70
+        if sup <= -3:  return "SELL", 0.55
+
+    return "HOLD", 0.40
+
+
+def _build_key_points(earnings: Dict, most_recent: Dict, signal: str) -> List[str]:
+    pts = []
+    sup = most_recent.get("pct_surprise")
+    if sup is not None:
+        pts.append(f"EPS 超预期 {sup:+.1f}%" if sup >= 0 else f"EPS 低于预期 {sup:.1f}%")
+    rx = earnings.get("price_reaction_pct")
+    if rx is not None:
+        pts.append(f"财报后股价反应: {rx:+.1f}%")
+    rev = earnings.get("revenue_trend", [])
+    if len(rev) >= 2:
+        v0 = rev[0].get("revenue")
+        v1 = rev[1].get("revenue")
+        if v0 and v1:
+            qoq = (v0 - v1) / abs(v1) * 100
+            pts.append(f"营收环比 {qoq:+.1f}%")
+    pts.append(f"财报信号: {signal}")
+    return pts[:5]
+
+
+def _template_analysis(symbol: str, earnings: Dict, most_recent: Dict, summary: str) -> str:
+    sup = most_recent.get("pct_surprise")
+    if sup is not None:
+        if sup >= 10:   verdict = "STRONG_BEAT"
+        elif sup >= 3:  verdict = "BEAT"
+        elif sup >= -3: verdict = "IN_LINE"
+        elif sup >= -10:verdict = "MISS"
+        else:           verdict = "STRONG_MISS"
+    else:
+        verdict = "IN_LINE"
+
+    return (
+        f"{symbol} 财报解读（模板）：\n"
+        f"初步判断：{summary}\n"
+        f"财报评级：{verdict}\n"
+        f"建议信号：{'BUY' if 'BEAT' in verdict else ('SELL' if 'MISS' in verdict else 'HOLD')}"
+    )

aria_code/agents/financial/fundamental.py

@@ -0,0 +1,191 @@
+"""
+agents/financial/fundamental.py — 基本面分析 Agent
+====================================================
+分析：PE/PB/ROE、营收增速、竞争壁垒、估值水位。
+"""
+from __future__ import annotations
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from ..base import BaseAgent, AgentResult
+
+# 动态加载 aria_tools 中的 MCP 工具
+# 相对本文件定位同仓库的 packages/，不写死开发者本机路径
+_PKGS = str(Path(__file__).resolve().parents[2] / "packages")
+if _PKGS not in sys.path:
+    sys.path.append(_PKGS)
+try:
+    from aria_tools.financial.factors import run_factor_research
+except ImportError:
+    async def run_factor_research(*args, **kwargs) -> str:
+        return "Error: run_factor_research tool is not available."
+
+
+class FundamentalAgent(BaseAgent):
+    name        = "fundamental"
+    description = "基本面分析：估值/ROE/竞争优势/财务健康"
+
+    _SYSTEM = (
+        "You are a fundamental equity analyst. Evaluate: PE/PB valuation levels "
+        "(vs historical range and sector peers), ROE quality, revenue growth, "
+        "balance sheet health, and competitive moat. "
+        "Be data-driven. End with: UNDERVALUED / FAIRLY_VALUED / OVERVALUED."
+    )
+
+    async def _execute_tool(self, tool_name: str, tool_args: Dict[str, Any]) -> str:
+        """拦截 factor_research 的调用，其他的交给基类"""
+        if tool_name == "run_factor_research":
+            if self.on_tool_start:
+                self.on_tool_start(tool_name, tool_args)
+            res = await run_factor_research(**tool_args)
+            if self.on_tool_end:
+                self.on_tool_end(tool_name, res)
+            import json
+            return json.dumps({"result": res}, ensure_ascii=False)
+
+        return await super()._execute_tool(tool_name, tool_args)
+
+    async def fetch_data(self, symbol: str) -> Dict[str, Any]:
+        data = await super().fetch_data(symbol)
+        if self.data:
+            try:
+                f = self.data.fundamentals(symbol)
+                if f:
+                    data["fundamentals"] = {
+                        "pe_ttm":          f.pe_ttm,
+                        "pb":              f.pb,
+                        "roe":             f.roe,
+                        "revenue_growth":  f.revenue_growth,
+                        "dividend_yield":  f.dividend_yield,
+                        "source":          f.source,
+                    }
+            except Exception:
+                pass
+        return data
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        quote = data.get("quote", {})
+        fund  = data.get("fundamentals", {})
+        price = _num_or_none(quote.get("price"))
+        # Accept both schemas: the agent's own fetch_data (pe_ttm/pb) AND the
+        # shared team data bundle (pe_ratio/pb_ratio from finnhub/yahoo).
+        pe    = _num_or_none(
+            fund.get("pe_ttm") or fund.get("pe_ratio") or fund.get("pe")
+            or quote.get("pe_ttm") or quote.get("pe_ratio")
+        )
+        pb    = _num_or_none(
+            fund.get("pb") or fund.get("pb_ratio")
+            or quote.get("pb") or quote.get("pb_ratio")
+        )
+        roe   = _num_or_none(fund.get("roe"))
+        rev_g = _num_or_none(fund.get("revenue_growth") or fund.get("rev_growth"))
+        div_y = _num_or_none(fund.get("dividend_yield"))
+
+        fund_str = (
+            f"  PE(TTM): {_fmt_num(pe, 1, 'x')}\n"
+            f"  PB:      {_fmt_num(pb, 2, 'x')}\n"
+            f"  ROE:     {_fmt_num(roe, 1, '%')}\n"
+            f"  Revenue growth: {_fmt_num(rev_g, 1, '%')}\n"
+            f"  Dividend yield: {_fmt_num(div_y, 2, '%')}"
+        ) if pe or pb else "  (fundamental data unavailable)"
+
+        prompt = (
+            f"Stock: {symbol}  Price: {price}\n"
+            f"Fundamentals:\n{fund_str}\n\n"
+            "Evaluate:\n"
+            "1. Valuation (PE/PB vs historical/sector)\n"
+            "2. Profitability quality (ROE trend)\n"
+            "3. Growth outlook (revenue/earnings)\n"
+            "4. Balance sheet and dividend\n"
+            "5. Competitive moat\n"
+            "Conclusion: UNDERVALUED / FAIRLY_VALUED / OVERVALUED\n\n"
+            "## Available Tools\n"
+            "You have access to a tool named `run_factor_research` to evaluate factor validity.\n"
+            "If you need to evaluate a factor (like pe, pb, roe), output exactly in this format:\n"
+            "{\"type\": \"tool_call\", \"name\": \"run_factor_research\", \"args\": {\"factor_name\": \"pe\"}}\n"
+            "Wait for the tool result before concluding."
+        )
+
+        analysis  = await self._call_llm(self._SYSTEM, prompt, max_tokens=500, quote=quote)
+        if not analysis:
+            analysis = _template_fundamental(symbol, pe, pb, roe, rev_g)
+
+        signal     = _extract_signal(analysis, pe or 0)
+        confidence = _calc_confidence(pe or 0, pb or 0, roe or 0)
+        key_points = _extract_key_points(analysis)
+
+        return AgentResult(
+            agent=self.name, symbol=symbol,
+            analysis=analysis, confidence=confidence,
+            signal=signal, key_points=key_points,
+            data_used={"pe": pe, "pb": pb, "roe": roe},
+        )
+
+
+def _num_or_none(value: Any) -> Optional[float]:
+    try:
+        if value is None:
+            return None
+        out = float(value)
+        return out if out != 0 else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _fmt_num(value: Optional[float], digits: int = 1, suffix: str = "") -> str:
+    if value is None:
+        return "数据不足"
+    return f"{value:.{digits}f}{suffix}"
+
+
+def _extract_signal(text: str, pe: float = 0) -> str:
+    t = text.upper()
+    if "UNDERVALUED" in t or "低估" in t:   return "BUY"
+    if "OVERVALUED"  in t or "高估" in t:   return "SELL"
+    # PE 辅助判断
+    if pe > 0:
+        if pe < 15:   return "BUY"
+        if pe > 50:   return "SELL"
+    return "HOLD"
+
+
+def _calc_confidence(pe: float, pb: float, roe: float) -> float:
+    if pe <= 0 and pb <= 0 and roe == 0:
+        return 0.4   # 无数据，低置信度
+    score = 0.5
+    if pe > 0:
+        if   pe < 15: score += 0.15
+        elif pe < 25: score += 0.05
+        elif pe > 50: score -= 0.15
+    if roe > 20: score += 0.15
+    elif roe > 10: score += 0.05
+    return round(min(0.95, max(0.2, score)), 2)
+
+
+def _extract_key_points(text: str) -> List[str]:
+    points = []
+    for line in text.split("\n"):
+        line = line.strip()
+        if line.startswith(("1.", "2.", "3.", "4.", "5.", "•", "-", "·")) and len(line) > 5:
+            points.append(line.lstrip("1234567890.-•· "))
+    return points[:4]
+
+
+def _template_fundamental(symbol: str, pe: Optional[float], pb: Optional[float],
+                           roe: Optional[float], rev_g: Optional[float]) -> str:
+    if not pe or pe <= 0:
+        valuation, conclusion = "数据不足", "DATA_LIMITED"
+    elif pe < 15:
+        valuation, conclusion = "低估", "UNDERVALUED"
+    elif pe > 40:
+        valuation, conclusion = "高估", "OVERVALUED"
+    else:
+        valuation, conclusion = "合理", "FAIRLY_VALUED"
+    return (
+        f"{symbol} 基本面分析（模板）:\n"
+        f"• 估值：PE={_fmt_num(pe, 1, 'x')}  PB={_fmt_num(pb, 2, 'x')}  → {valuation}\n"
+        f"• 盈利能力：ROE={_fmt_num(roe, 1, '%')}  营收增速={_fmt_num(rev_g, 1, '%')}\n"
+        "• 基本面数据不足时，不应把缺失值当作 0；建议结合财报和行业对比复核\n"
+        f"• 结论: {conclusion}"
+    )

aria_code/agents/financial/macro.py

@@ -0,0 +1,99 @@
+"""
+agents/financial/macro.py — 宏观环境 Agent
+===========================================
+分析：利率环境、汇率、行业周期、政策面、大盘趋势。
+"""
+from __future__ import annotations
+from typing import Any, Dict, List
+from ..base import BaseAgent, AgentResult
+
+
+class MacroAgent(BaseAgent):
+    name        = "macro"
+    description = "宏观分析：利率/汇率/政策/大盘趋势"
+
+    _SYSTEM = (
+        "You are a macro strategist covering China and global markets. "
+        "Focus on: interest rate environment, USD/CNY trend, sector cycle, "
+        "regulatory policy, and market sentiment. Be concise and data-driven. "
+        "End with: TAILWIND / NEUTRAL / HEADWIND for the given stock."
+    )
+
+    async def fetch_data(self, symbol: str) -> Dict[str, Any]:
+        data = await super().fetch_data(symbol)
+        # 尝试拉取指数数据作为大盘参考
+        if self.data:
+            for idx in ["000001", "399006"]:  # 上证 + 创业板
+                try:
+                    q = self.data.quote(idx)
+                    if q:
+                        data.setdefault("indices", {})[idx] = q.to_dict()
+                except Exception:
+                    pass
+        return data
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        quote   = data.get("quote", {})
+        indices = data.get("indices", {})
+
+        idx_summary = ""
+        for code, q in indices.items():
+            name = {"000001": "上证", "399006": "创业板"}.get(code, code)
+            idx_summary += f"  {name}: {q.get('price',0):.2f} {q.get('change_pct',0):+.2f}%\n"
+
+        prompt = (
+            f"Symbol: {symbol}\n"
+            f"Market Indices:\n{idx_summary or '  (unavailable)'}\n\n"
+            "Analyze the macroeconomic backdrop for this stock:\n"
+            "1. Current rate/liquidity environment (PBOC stance)\n"
+            "2. Sector regulatory environment (any recent policies)\n"
+            "3. Market sentiment and positioning\n"
+            "4. Key macro risks to watch\n"
+            "Conclusion: TAILWIND / NEUTRAL / HEADWIND"
+        )
+
+        analysis = await self._call_llm(self._SYSTEM, prompt, max_tokens=500, quote=quote)
+        if not analysis:
+            analysis = _template_macro(symbol, indices)
+
+        signal     = _extract_signal(analysis)
+        key_points = _extract_key_points(analysis)
+
+        return AgentResult(
+            agent=self.name, symbol=symbol,
+            analysis=analysis, confidence=0.65,
+            signal=signal, key_points=key_points,
+            data_used={"indices": indices},
+        )
+
+
+def _extract_signal(text: str) -> str:
+    t = text.upper()
+    if "TAILWIND" in t or "看多" in t:   return "BUY"
+    if "HEADWIND" in t or "看空" in t:   return "SELL"
+    return "HOLD"
+
+
+def _extract_key_points(text: str) -> List[str]:
+    points = []
+    for line in text.split("\n"):
+        line = line.strip()
+        if line.startswith(("1.", "2.", "3.", "4.", "•", "-", "·")) and len(line) > 5:
+            points.append(line.lstrip("1234567890.-•· "))
+    return points[:4]
+
+
+_IDX_NAMES = {"000001": "上证", "399006": "创业板"}
+
+def _template_macro(symbol: str, indices: Dict) -> str:
+    idx_str = "、".join(
+        f"{_IDX_NAMES.get(k, k)} {v.get('change_pct', 0):+.2f}%"
+        for k, v in indices.items()
+    ) if indices else "指数数据不可用"
+    return (
+        f"{symbol} 宏观分析（模板）:\n"
+        f"• 市场指数: {idx_str}\n"
+        "• 当前货币政策偏宽松，流动性充裕\n"
+        "• 建议关注政策面变化和外资动向\n"
+        "• 结论: NEUTRAL"
+    )