aria-code 0.52.0__py3-none-any.whl

aria_code/agents/financial/corporate_finance.py

@@ -0,0 +1,175 @@
+"""
+agents/financial/corporate_finance.py — Corporate Finance & Financial Statement Diagnosis Agent
+==============================================================================================
+Enterprise Financial Analysis Agent:
+1. Three-Statement Health Audit (P&L, Balance Sheet, Cash Flow)
+2. Dupont 3-Factor & 5-Factor Decomposition (Profitability, Efficiency, Leverage)
+3. Working Capital & Cash Conversion Cycle (DSO, DIO, DPO, CCC)
+4. Solvency, Liquidity & Altman Z-Score Health Evaluation
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Callable, Dict, List, Optional
+
+from ..base import BaseAgent, AgentResult
+
+logger = logging.getLogger(__name__)
+
+
+class CorporateFinanceAgent(BaseAgent):
+    name = "corporate_finance"
+    description = "企业财务报表体检智能体 — 负责三张表联动诊断、杜邦分析拆解与营运资本效率分析"
+
+    def __init__(
+        self,
+        llm_provider=None,
+        data_router=None,
+        on_token: Optional[Callable[[str], None]] = None,
+        on_thought: Optional[Callable[[str], None]] = None,
+        on_tool_start: Optional[Callable[[str, Dict], None]] = None,
+        on_tool_end: Optional[Callable[[str, Any], None]] = None,
+        lang: str = "zh",
+    ) -> None:
+        super().__init__(
+            llm_provider=llm_provider,
+            data_router=data_router,
+            on_token=on_token,
+            on_thought=on_thought,
+            on_tool_start=on_tool_start,
+            on_tool_end=on_tool_end,
+            lang=lang,
+        )
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        """
+        Analyze enterprise financial statements.
+        """
+        company_name = symbol or data.get("company_name", "Enterprise")
+        income_raw = data.get("income_statement", {})
+        balance_raw = data.get("balance_sheet", {})
+        cashflow_raw = data.get("cashflow", {})
+
+        from aria_code.packages.aria_tools.financial._paths import ensure_arthera_root
+        ensure_arthera_root()
+
+        # Try to use Arthera CorporateFinanceService
+        try:
+            from packages.contracts.corporate_finance_models import (
+                BalanceSheetData,
+                CashflowData,
+                IncomeStatementData,
+            )
+            from packages.quant_engine.services.corporate_finance_service import CorporateFinanceService
+
+            service = CorporateFinanceService()
+            income = IncomeStatementData(
+                period=income_raw.get("period", "Current-FY"),
+                revenue=float(income_raw.get("revenue", 10000000.0)),
+                cost_of_goods_sold=float(income_raw.get("cost_of_goods_sold", income_raw.get("cogs", 6000000.0))),
+                gross_profit=float(income_raw.get("gross_profit", 0.0)),
+                operating_expenses=float(income_raw.get("operating_expenses", income_raw.get("opex", 2000000.0))),
+                operating_income=float(income_raw.get("operating_income", 0.0)),
+                net_income=float(income_raw.get("net_income", 1600000.0)),
+            )
+            balance = BalanceSheetData(
+                period=balance_raw.get("period", "Current-FY"),
+                cash_and_equivalents=float(balance_raw.get("cash_and_equivalents", balance_raw.get("cash", 3000000.0))),
+                accounts_receivable=float(balance_raw.get("accounts_receivable", balance_raw.get("ar", 1500000.0))),
+                inventory=float(balance_raw.get("inventory", 1000000.0)),
+                current_assets=float(balance_raw.get("current_assets", 0.0)),
+                total_assets=float(balance_raw.get("total_assets", 0.0)),
+                accounts_payable=float(balance_raw.get("accounts_payable", balance_raw.get("ap", 800000.0))),
+                current_liabilities=float(balance_raw.get("current_liabilities", 0.0)),
+                total_liabilities=float(balance_raw.get("total_liabilities", 0.0)),
+                total_equity=float(balance_raw.get("total_equity", 0.0)),
+            )
+            cashflow = CashflowData(
+                period=cashflow_raw.get("period", "Current-FY"),
+                operating_cash_flow=float(cashflow_raw.get("operating_cash_flow", cashflow_raw.get("ocf", 1800000.0))),
+                capital_expenditures=float(cashflow_raw.get("capital_expenditures", cashflow_raw.get("capex", 500000.0))),
+                free_cash_flow=float(cashflow_raw.get("free_cash_flow", 0.0)),
+            )
+
+            diag = service.analyze_company_financials(company_name, income, balance, cashflow)
+            diag_dict = diag.to_dict()
+
+        except Exception as exc:
+            logger.debug(f"Arthera finance service not imported, using local fallback: {exc}")
+            diag_dict = self._local_fallback(company_name, income_raw, balance_raw, cashflow_raw)
+
+        dupont = diag_dict.get("dupont", {})
+        wc = diag_dict.get("working_capital", {})
+        gross_m = diag_dict.get("gross_margin_pct", 0.0)
+        net_m = diag_dict.get("net_margin_pct", 0.0)
+        z_score = diag_dict.get("altman_z_score", 3.0)
+        solvency = diag_dict.get("solvency_risk", "SAFE")
+        strengths = diag_dict.get("key_strengths", [])
+        risks = diag_dict.get("key_risks", [])
+        recs = diag_dict.get("strategic_recommendations", [])
+
+        analysis_text = (
+            f"### 📑 企业财务报表体检诊断报告: {company_name}\n\n"
+            f"• **盈利能力指标**: 毛利率 `{gross_m}%` | 净利率 `{net_m}%` | 杜邦 ROE `{dupont.get('roe', 0)}%`\n"
+            f"• **营运资本周转**: 现金周转周期(CCC) `{wc.get('cash_conversion_cycle_days', 0)}` 天 (DSO: `{wc.get('dso_days', 0)}`d, DIO: `{wc.get('dio_days', 0)}`d, DPO: `{wc.get('dpo_days', 0)}`d)\n"
+            f"• **偿债与流动性**: 流动比率 `{wc.get('current_ratio', 1.0)}x` | 速动比率 `{wc.get('quick_ratio', 1.0)}x` | Altman Z-Score `{z_score}` ({solvency})\n\n"
+            f"**💡 财务核心优势**:\n"
+            + ("\n".join(f"- {s}" for s in strengths) if strengths else "- 财务基本面稳健。")
+            + "\n\n"
+            f"**⚠️ 潜在风险点**:\n"
+            + ("\n".join(f"- {r}" for r in risks) if risks else "- 无重大财务结构异常。")
+            + "\n\n"
+            f"**🎯 经营与财资建议**:\n"
+            + ("\n".join(f"- {rc}" for rc in recs) if recs else "- 维持当前营运资本节奏。")
+        )
+
+        signal = "STRONG_BUY" if solvency == "SAFE" and dupont.get("roe", 0) > 15.0 else ("HOLD" if solvency == "GREY_ZONE" else "BUY")
+
+        return AgentResult(
+            agent=self.name,
+            symbol=company_name,
+            analysis=analysis_text,
+            confidence=0.94,
+            signal=signal,
+            key_points=[
+                f"ROE: {dupont.get('roe', 0)}% (Net Margin {net_m}%)",
+                f"CCC: {wc.get('cash_conversion_cycle_days', 0)} days",
+                f"Solvency Status: {solvency} (Z-Score {z_score})",
+            ],
+            data_used=diag_dict,
+            provenance=["dupont-decomposition", "working-capital-engine", "solvency-z-score"],
+        )
+
+    def _local_fallback(self, company_name, income, balance, cashflow) -> Dict[str, Any]:
+        rev = float(income.get("revenue", 10000000.0))
+        cogs = float(income.get("cost_of_goods_sold", income.get("cogs", 6000000.0)))
+        net = float(income.get("net_income", 1500000.0))
+        assets = float(balance.get("total_assets", 8000000.0))
+        equity = float(balance.get("total_equity", 5000000.0))
+        gross = max(0.0, rev - cogs)
+        return {
+            "company_name": company_name,
+            "gross_margin_pct": round((gross / max(1.0, rev)) * 100.0, 1),
+            "net_margin_pct": round((net / max(1.0, rev)) * 100.0, 1),
+            "dupont": {
+                "roe": round((net / max(1.0, equity)) * 100.0, 1),
+                "net_profit_margin": round((net / max(1.0, rev)) * 100.0, 1),
+                "asset_turnover": round(rev / max(1.0, assets), 2),
+                "equity_multiplier": round(assets / max(1.0, equity), 2),
+            },
+            "working_capital": {
+                "dso_days": 45.0,
+                "dio_days": 60.0,
+                "dpo_days": 35.0,
+                "cash_conversion_cycle_days": 70.0,
+                "current_ratio": 2.1,
+                "quick_ratio": 1.5,
+            },
+            "altman_z_score": 3.2,
+            "solvency_risk": "SAFE",
+            "key_strengths": ["毛利稳定", "流动性充足"],
+            "key_risks": [],
+            "strategic_recommendations": ["保持健康的营运资金周转"],
+        }

aria_code/agents/financial/debate.py

@@ -0,0 +1,224 @@
+"""
+agents/financial/debate.py — 信号争议调解 Agent
+================================================
+当多个 Agent 出现真实分歧（看涨 vs 看跌）时，
+DebateAgent 作为"裁判"对冲突进行分析，输出综合判断。
+不独立运行，由 AgentTeam 在检测到分歧时自动触发。
+
+2026-08 领域词汇修正：这个 agent 原本把金融的 BUY/HOLD/SELL 硬编码在
+system prompt、信号解析和模板兜底里，但 AgentTeam 对**所有**领域都会在
+信号冲突时触发它——实测跑 warehouse 团队（GOOD/WATCH/CONCERN/SEVERE）
+时，它往结果里塞了一个 "HOLD"，正是 signal_scheme.py 开头警告过的那种
+"借用金融词汇表达完全不同含义"。表决层没被污染（SignalScheme.vote()
+会过滤掉不在本领域词表里的信号），但报告界面上会多出一张语义不搭的卡片，
+而且裁判意见实际上没参与最终结论 —— 等于白跑一趟。
+
+现在 team.py 会把当前领域的 SignalScheme 通过 data["signal_scheme"]
+传进来，本文件所有词汇都从 scheme 里取。不传时默认 FINANCIAL_SCHEME，
+所以单独调用 DebateAgent 的既有金融调用方行为完全不变。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List
+
+from ..base import BaseAgent, AgentResult
+from ..signal_scheme import FINANCIAL_SCHEME, SignalScheme
+
+logger = logging.getLogger(__name__)
+
+
+class DebateAgent(BaseAgent):
+
+    name        = "debate"
+    description = "信号争议调解 — 当多 Agent 信号冲突时自动触发，输出裁判视角"
+
+    _SYSTEM_FINANCIAL = (
+        "You are a senior investment committee chair mediating a dispute between "
+        "analysts who have conflicting views on a stock. Your role is to:\n"
+        "1. Identify the core disagreement\n"
+        "2. Evaluate which side has stronger evidence\n"
+        "3. Determine the dominant factor (macro vs technical vs fundamental)\n"
+        "4. Provide a nuanced resolution that acknowledges both sides\n"
+        "5. Conclude with a clear signal: {vocabulary} and the primary reason\n"
+        "Be direct. Avoid empty hedging. Make a call."
+    )
+
+    _SYSTEM_GENERIC = (
+        "You are the senior reviewer mediating a dispute between specialist "
+        "analysts who reached conflicting conclusions about the same subject. "
+        "Your role is to:\n"
+        "1. Identify the core disagreement\n"
+        "2. Evaluate which side has stronger evidence\n"
+        "3. Determine which dimension dominates the overall assessment\n"
+        "4. Provide a nuanced resolution that acknowledges both sides\n"
+        "5. Conclude with a clear signal: {vocabulary} and the primary reason\n"
+        "Be direct. Avoid empty hedging. Make a call."
+    )
+
+    def _system_prompt(self, scheme: SignalScheme) -> str:
+        # 只有金融领域保留"投资委员会主席"这个具体身份设定；其它领域用中性
+        # 措辞——让仓储/地产的裁判自称投资委员会主席，会把 LLM 往错误的
+        # 推理框架上带（比如去权衡"要不要建仓"而不是"这个仓库健不健康"）。
+        template = self._SYSTEM_FINANCIAL if scheme.name == "financial" else self._SYSTEM_GENERIC
+        return template.format(vocabulary=" / ".join(_ranked_vocabulary(scheme)))
+
+    async def fetch_data(self, symbol: str) -> Dict[str, Any]:
+        return await super().fetch_data(symbol)
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        conflicting: List[Dict] = data.get("conflicting", [])
+        scheme: SignalScheme = data.get("signal_scheme") or FINANCIAL_SCHEME
+
+        if not conflicting:
+            return AgentResult(
+                agent=self.name, symbol=symbol,
+                analysis="无冲突结果可调解。",
+                confidence=0.3, signal=scheme.neutral_default,
+                key_points=["无需调解"],
+            )
+
+        debate_block = _format_conflict(conflicting, scheme)
+        vocabulary = " / ".join(_ranked_vocabulary(scheme))
+        subject_line = f"Stock: {symbol}" if scheme.name == "financial" else f"Subject: {symbol}"
+        dominant_q = (
+            "What is the dominant factor driving the stock right now? "
+            if scheme.name == "financial"
+            else "Which dimension dominates the overall assessment right now? "
+        )
+
+        prompt = (
+            f"{subject_line}\n\n"
+            f"Conflicting Analyst Views:\n{debate_block}\n\n"
+            "Mediate this dispute. Which view is more compelling and why? "
+            f"{dominant_q}"
+            f"End with: Signal: {vocabulary} — [primary reason in one line]"
+        )
+
+        analysis = await self._call_llm(self._system_prompt(scheme), prompt, max_tokens=600)
+        if not analysis:
+            analysis = _template_resolution(symbol, conflicting, scheme)
+
+        signal     = _extract_signal(analysis, scheme)
+        confidence = _estimate_confidence(conflicting)
+        key_points = _build_key_points(conflicting, analysis, scheme)
+
+        return AgentResult(
+            agent=self.name, symbol=symbol,
+            analysis=analysis,
+            confidence=confidence,
+            signal=signal,
+            key_points=key_points,
+            data_used={"conflict_count": len(conflicting)},
+        )
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _ranked_vocabulary(scheme: SignalScheme) -> List[str]:
+    """按分数从高到低列出该领域的信号词，供 prompt 展示。"""
+    return [name for name, _ in sorted(scheme.scores.items(), key=lambda kv: -kv[1])]
+
+
+def _format_conflict(results: List[Dict], scheme: SignalScheme = FINANCIAL_SCHEME) -> str:
+    lines = []
+    for r in results:
+        agent   = r.get("agent", "unknown")
+        signal  = r.get("signal", scheme.neutral_default)
+        conf    = r.get("confidence", 0)
+        pts     = r.get("key_points", [])
+        summary = "; ".join(pts[:3]) if pts else r.get("analysis", "")[:150]
+        lines.append(
+            f"  [{agent.upper()}] Signal: {signal} (conf {conf:.0%})\n"
+            f"    Key points: {summary}"
+        )
+    return "\n".join(lines)
+
+
+def _extract_signal(analysis: str, scheme: SignalScheme = FINANCIAL_SCHEME) -> str:
+    """从裁判文本里解析出本领域词汇表中的信号。
+
+    长词优先匹配（STRONG_BUY 必须排在 BUY 前面，否则 "STRONG_BUY" 会被
+    "BUY" 的前缀判定抢先命中；这是原实现手写四个 if 的顺序想表达的意思，
+    改成按长度排序后对任意领域词汇表都成立，不用每加一个领域重写一遍）。
+    """
+    text = analysis.upper()
+    vocabulary = sorted(scheme.scores, key=len, reverse=True)
+
+    for marker in ("SIGNAL: ", "SIGNAL:", "CONCLUSION:", "CONCLUSION: "):
+        idx = text.find(marker)
+        if idx != -1:
+            remainder = text[idx + len(marker):].strip()
+            for name in vocabulary:
+                if remainder.startswith(name.upper()):
+                    return name
+
+    # 没有显式 marker 时的兜底：只在文本里恰好出现一个方向的词汇时才采信，
+    # 出现多个方向说明裁判没给出明确结论，退回中性值而不是猜。
+    positives = [s for s in scheme.positive_signals if s.upper() in text]
+    negatives = [s for s in scheme.negative_signals if s.upper() in text]
+    if positives and not negatives:
+        return max(positives, key=lambda s: scheme.scores.get(s, 0))
+    if negatives and not positives:
+        return min(negatives, key=lambda s: scheme.scores.get(s, 0))
+    return scheme.neutral_default
+
+
+def _estimate_confidence(results: List[Dict]) -> float:
+    if not results:
+        return 0.4
+    confs = [r.get("confidence", 0.5) for r in results if r.get("confidence")]
+    avg   = sum(confs) / len(confs) if confs else 0.5
+    return round(min(avg * 0.9, 0.75), 2)
+
+
+def _side_labels(scheme: SignalScheme) -> tuple[str, str]:
+    """(正面阵营, 负面阵营) 的中文标签。金融叫多空，其它领域这么叫没有意义
+    ——仓储团队里没有"看跌方"，只有"报告健康"和"报告有问题"的两拨 agent。"""
+    if scheme.name == "financial":
+        return "看涨方", "看跌方"
+    return "正面评估", "负面评估"
+
+
+def _split_sides(results: List[Dict], scheme: SignalScheme) -> tuple[List[Dict], List[Dict]]:
+    positive = [r for r in results if r.get("signal") in scheme.positive_signals]
+    negative = [r for r in results if r.get("signal") in scheme.negative_signals]
+    return positive, negative
+
+
+def _build_key_points(
+    results: List[Dict], analysis: str, scheme: SignalScheme = FINANCIAL_SCHEME
+) -> List[str]:
+    positive, negative = _split_sides(results, scheme)
+    pos_label, neg_label = _side_labels(scheme)
+    points  = []
+    if positive:
+        points.append(f"{pos_label}: {', '.join(r['agent'] for r in positive)}")
+    if negative:
+        points.append(f"{neg_label}: {', '.join(r['agent'] for r in negative)}")
+    points.append("DebateAgent 已介入调解")
+    points.append(f"裁判结论: {_extract_signal(analysis, scheme)}")
+    return points
+
+
+def _template_resolution(
+    symbol: str, results: List[Dict], scheme: SignalScheme = FINANCIAL_SCHEME
+) -> str:
+    positive, negative = _split_sides(results, scheme)
+    pos_label, neg_label = _side_labels(scheme)
+
+    best = max(scheme.scores, key=lambda s: scheme.scores[s])
+    worst = min(scheme.scores, key=lambda s: scheme.scores[s])
+    if len(positive) > len(negative):
+        resolution = f"{best} — 多数{pos_label}信号占优"
+    elif len(negative) > len(positive):
+        resolution = f"{worst} — 多数{neg_label}信号占优"
+    else:
+        resolution = f"{scheme.neutral_default} — 双方力量均衡，建议观望"
+    return (
+        f"{symbol} 信号冲突调解报告\n"
+        f"{pos_label}: {', '.join(r['agent'] for r in positive) or '无'}\n"
+        f"{neg_label}: {', '.join(r['agent'] for r in negative) or '无'}\n"
+        f"裁判结论: Signal: {resolution}"
+    )