aria-code 0.52.0__py3-none-any.whl

aria_code/tools/enterprise_finance_tools.py

@@ -0,0 +1,156 @@
+"""
+tools/enterprise_finance_tools.py — Corporate Financial Statement Analysis Tool
+================================================================================
+Provides CLI and agent tools to ingest and analyze company financial reports.
+Now supports fetching real data from Yahoo Finance.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import pathlib
+from typing import Any, Dict, List
+
+logger = logging.getLogger(__name__)
+
+def compute_financial_metrics(income: dict, balance: dict, cashflow: dict) -> dict:
+    """Perform real financial math."""
+    revenue = income.get("revenue", 0) or 1
+    net_income = income.get("net_income", 0)
+    gross_profit = income.get("gross_profit", 0)
+    total_assets = balance.get("total_assets", 0) or 1
+    total_equity = balance.get("total_equity", 0) or 1
+    current_assets = balance.get("current_assets", 0)
+    current_liabilities = balance.get("current_liabilities", 0) or 1
+    inventory = balance.get("inventory", 0)
+    cogs = income.get("cost_of_goods_sold", 0) or 1
+    
+    # Dupont
+    net_margin = net_income / revenue
+    asset_turnover = revenue / total_assets
+    equity_multiplier = total_assets / total_equity
+    roe = net_margin * asset_turnover * equity_multiplier
+    
+    # Working capital
+    current_ratio = current_assets / current_liabilities
+    quick_ratio = (current_assets - inventory) / current_liabilities
+    
+    # Altman Z-Score approximation (simplified)
+    working_capital = current_assets - current_liabilities
+    retained_earnings = balance.get("retained_earnings", 0)
+    ebit = income.get("operating_income", 0)
+    
+    z_score = 1.2 * (working_capital/total_assets) + 1.4 * (retained_earnings/total_assets) + 3.3 * (ebit/total_assets)
+    
+    return {
+        "gross_margin_pct": round((gross_profit / revenue) * 100, 2),
+        "net_margin_pct": round(net_margin * 100, 2),
+        "dupont": {
+            "roe": round(roe * 100, 2),
+            "net_profit_margin": round(net_margin * 100, 2),
+            "asset_turnover": round(asset_turnover, 2),
+            "equity_multiplier": round(equity_multiplier, 2)
+        },
+        "working_capital": {
+            "current_ratio": round(current_ratio, 2),
+            "quick_ratio": round(quick_ratio, 2)
+        },
+        "altman_z_score": round(z_score, 2),
+        "solvency_risk": "SAFE" if z_score > 2.99 else ("DISTRESS" if z_score < 1.8 else "GREY")
+    }
+
+def tool_analyze_financial_statements(params: Dict[str, Any]) -> Dict[str, Any]:
+    company_name = params.get("company_name", "").upper()
+    data = params.get("financials", {})
+    
+    income = data.get("income_statement", {})
+    balance = data.get("balance_sheet", {})
+    cashflow = data.get("cashflow", {})
+    
+    # Try fetching real data via yfinance if it looks like a ticker and we have no data
+    if company_name and len(company_name) <= 5 and not income:
+        try:
+            import yfinance as yf
+            ticker = yf.Ticker(company_name)
+            inc_df = ticker.income_stmt
+            bal_df = ticker.balance_sheet
+            cf_df = ticker.cashflow
+            
+            if not inc_df.empty and not bal_df.empty:
+                # Take most recent year
+                inc_latest = inc_df.iloc[:, 0]
+                bal_latest = bal_df.iloc[:, 0]
+                
+                income = {
+                    "revenue": inc_latest.get("Total Revenue", 0),
+                    "cost_of_goods_sold": inc_latest.get("Cost Of Revenue", 0),
+                    "gross_profit": inc_latest.get("Gross Profit", 0),
+                    "operating_income": inc_latest.get("Operating Income", 0),
+                    "net_income": inc_latest.get("Net Income", 0)
+                }
+                balance = {
+                    "total_assets": bal_latest.get("Total Assets", 0),
+                    "total_equity": bal_latest.get("Stockholders Equity", 0),
+                    "current_assets": bal_latest.get("Current Assets", 0),
+                    "current_liabilities": bal_latest.get("Current Liabilities", 0),
+                    "inventory": bal_latest.get("Inventory", 0),
+                    "retained_earnings": bal_latest.get("Retained Earnings", 0)
+                }
+        except ImportError:
+            pass
+        except Exception as e:
+            logger.warning(f"yfinance failed for {company_name}: {e}")
+            
+    # No statements, no diagnosis.
+    #
+    # A "sensible mock" used to fill in here — revenue 12,000,000, net income
+    # 2,000,000 — and the result then carried the requested company's name.
+    # Asked about a real company whose filings could not be fetched, the tool
+    # returned a complete, confident diagnosis of a business that does not
+    # exist, labelled with that company's ticker. There is no way for the
+    # caller to tell that apart from a real one.
+    if not income:
+        return {
+            "success": False,
+            "error": (
+                f"No financial statements available"
+                f"{f' for {company_name}' if company_name else ''}. "
+                "Pass financials={income_statement, balance_sheet, cashflow}, or "
+                "give a ticker whose filings yfinance can fetch. "
+                "This tool does not estimate missing figures."
+            ),
+        }
+
+    metrics = compute_financial_metrics(income, balance, cashflow)
+    metrics["company_name"] = company_name
+    metrics["data_source"] = (
+        "caller-supplied statements" if params.get("financials") else f"yfinance:{company_name}"
+    )
+
+    return {
+        "success": True,
+        "data": metrics,
+        "summary": (
+            f"{company_name} 财务诊断完成（来源：{metrics['data_source']}）: 毛利率 {metrics.get('gross_margin_pct')}%，"
+            f"净利率 {metrics.get('net_margin_pct')}%，杜邦 ROE {metrics.get('dupont', {}).get('roe')}%，"
+            f"偿债安全性 {metrics.get('solvency_risk')} (Altman Z: {metrics.get('altman_z_score')})。"
+        ),
+    }
+
+def register_enterprise_finance_tools(tools_dict: Dict[str, Any], schemas_list: List[Dict[str, Any]]) -> int:
+    tools_dict["analyze_financial_statements"] = (tool_analyze_financial_statements, "Analyze company financial statements (P&L, Balance Sheet, Cash Flow) and Dupont decomposition")
+    schemas_list.append({
+        "name": "analyze_financial_statements",
+        "description": "Analyze corporate financial statements, working capital cycle, and solvency. If company_name is a ticker (e.g. AAPL), it fetches real Yahoo Finance data.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "file_path": {"type": "string", "description": "Optional path to JSON financial statements"},
+                "financials": {"type": "object", "description": "Optional dict containing income_statement, balance_sheet, cashflow"},
+                "company_name": {"type": "string", "description": "Company name or ticker symbol (e.g. AAPL)"},
+            },
+        },
+    })
+    return 1
+

aria_code/tools/extended_tools.py

@@ -0,0 +1,240 @@
+"""Enterprise connector tools — SHAPES ONLY, not implementations.
+
+Read this before using anything here.
+=====================================
+None of these functions contact the service they name. Every one returns a
+hardcoded payload: ``tool_send_slack_notification`` reports
+``"Successfully posted to Slack channel"`` with an invented timestamp and
+permalink without opening a socket, and the QuickBooks, Shopify and Snowflake
+tools return fabricated figures in the same way.
+
+They define the intended request/response shape for six integrations that have
+not been built. That is a legitimate thing to have; what is not legitimate is
+letting a model call one and report the fabricated result to a user as fact —
+"I posted the alert to #trading-desk" when nothing was sent, or a cash-runway
+number invented out of nothing.
+
+So ``register_extended_tools`` wraps each one in a guard that refuses to run
+and says why. The shapes stay here as the specification for whoever implements
+them; ``ARIA_ALLOW_STUB_TOOLS=1`` returns the canned payloads for tests and
+demos, and names itself in the result so the caller cannot mistake it for real.
+
+Implementing one means replacing the body with a real client call and dropping
+it from ``_STUB_TOOLS``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def tool_send_slack_notification(params: Dict[str, Any]) -> Dict[str, Any]:
+    """Send an automated report or approval card to a connected Slack channel."""
+    channel = params.get("channel", "#trading-desk")
+    text = params.get("text", "Aria Quantitative Alert: Portfolio Rebalanced.")
+    blocks = params.get("blocks", [])
+
+    return {
+        "success": True,
+        "channel": channel,
+        "ts": "1724502800.102900",
+        "permalink": f"https://arthera.slack.com/archives/{channel.replace('#', '')}/p1724502800102900",
+        "message": f"Successfully posted to Slack channel {channel}",
+    }
+
+
+def tool_push_feishu_card(params: Dict[str, Any]) -> Dict[str, Any]:
+    """Send an interactive approval card to Feishu / Lark."""
+    title = params.get("title", "Aria 投资策略审批通知")
+    receive_id = params.get("receive_id", "ou_arthera_admin_001")
+
+    return {
+        "success": True,
+        "instance_code": "FEISHU_APPR_8829104",
+        "status": "PENDING",
+        "target": receive_id,
+        "title": title,
+        "message": f"已将「{title}」推送到飞书工作台，等待责任人审批",
+    }
+
+
+def tool_parse_tradingview_alert(params: Dict[str, Any]) -> Dict[str, Any]:
+    """Ingest TradingView Webhook alert and map to quantitative execution order."""
+    ticker = params.get("ticker", "NASDAQ:NVDA")
+    action = params.get("action", "BUY").upper()
+    price = float(params.get("price", 128.5))
+    timeframe = params.get("timeframe", "1h")
+    strategy = params.get("strategy", "Aria Momentum Alpha V3")
+
+    return {
+        "success": True,
+        "ticker": ticker,
+        "action": action,
+        "trigger_price": price,
+        "timeframe": timeframe,
+        "strategy": strategy,
+        "order_intent": {
+            "symbol": ticker.split(":")[-1] if ":" in ticker else ticker,
+            "side": action,
+            "limit_price": price,
+            "quantity": 100,
+        },
+        "message": f"TradingView 信号已解析: {strategy} 触发 {action} {ticker} @ {price}",
+    }
+
+
+def tool_get_quickbooks_pnl(params: Dict[str, Any]) -> Dict[str, Any]:
+    """Fetch corporate P&L statement, burn rate, and runway from QuickBooks / Xero."""
+    company = params.get("company_name", "Arthera Enterprise Corp")
+    period = params.get("period", "2026-Q2")
+
+    total_income = 485000.0
+    cogs = 142000.0
+    gross_profit = total_income - cogs
+    operating_expenses = 195000.0
+    net_operating_income = gross_profit - operating_expenses
+    monthly_burn = 45000.0
+    cash_balance = 1250000.0
+    runway_months = round(cash_balance / monthly_burn, 1)
+
+    return {
+        "success": True,
+        "company_name": company,
+        "period": period,
+        "currency": "USD",
+        "metrics": {
+            "total_revenue": total_income,
+            "cogs": cogs,
+            "gross_profit": gross_profit,
+            "gross_margin_pct": round((gross_profit / total_income) * 100, 2),
+            "operating_expenses": operating_expenses,
+            "net_income": net_operating_income,
+            "net_margin_pct": round((net_operating_income / total_income) * 100, 2),
+            "cash_burn_rate_monthly": monthly_burn,
+            "total_cash_reserve": cash_balance,
+            "runway_months": runway_months,
+            "overdue_ar": 18500.0,
+        },
+        "health_rating": "HEALTHY",
+    }
+
+
+def tool_get_shopify_store_analytics(params: Dict[str, Any]) -> Dict[str, Any]:
+    """Fetch Shopify / Amazon Seller GMV, order volume, and ROAS."""
+    store = params.get("store_domain", "shop.arthera.com")
+
+    total_gmv = 248600.0
+    total_orders = 3120
+    aov = round(total_gmv / total_orders, 2)
+    ad_spend = 48000.0
+    roas = round(total_gmv / ad_spend, 2)
+
+    return {
+        "success": True,
+        "store_domain": store,
+        "period_days": 30,
+        "currency": "USD",
+        "metrics": {
+            "total_gmv": total_gmv,
+            "total_orders": total_orders,
+            "average_order_value": aov,
+            "refund_rate_pct": 2.45,
+            "ad_spend": ad_spend,
+            "blended_roas": roas,
+            "out_of_stock_skus": 3,
+        },
+    }
+
+
+def tool_query_snowflake_data(params: Dict[str, Any]) -> Dict[str, Any]:
+    """Execute read-only SQL query against Snowflake / BigQuery Lakehouse."""
+    sql = params.get("sql", "SELECT date, ticker, factor_score FROM analytics.equity_factors LIMIT 5")
+
+    return {
+        "success": True,
+        "query_id": "01b23456-0001-abcd-0001-1234567890ab",
+        "execution_time_ms": 142,
+        "row_count": 5,
+        "columns": ["date", "ticker", "factor_score", "sector", "z_score"],
+        "rows": [
+            ["2026-08-20", "NVDA", 2.84, "Semiconductors", 2.15],
+            ["2026-08-20", "AAPL", 1.95, "Consumer Tech", 1.42],
+            ["2026-08-20", "MSFT", 2.10, "Software Cloud", 1.68],
+            ["2026-08-20", "AMZN", 1.82, "E-Commerce", 1.30],
+            ["2026-08-20", "GOOGL", 1.65, "Internet Media", 1.15],
+        ],
+    }
+
+
+# name → the service it would need, for the message the guard returns.
+_STUB_TOOLS = {
+    "send_slack_notification": "Slack (bot token + channel)",
+    "push_feishu_card": "Feishu/Lark (app credentials + webhook)",
+    "parse_tradingview_alert": "TradingView webhook receiver",
+    "get_quickbooks_pnl": "QuickBooks Online API (OAuth)",
+    "get_shopify_store_analytics": "Shopify Admin API (store + token)",
+    "query_snowflake_data": "Snowflake (account, warehouse, credentials)",
+}
+
+
+def stub_guard(name: str, service: str, handler):
+    """Wrap a shape-only tool so it reports its status instead of inventing one.
+
+    Returning fabricated success is the one behaviour that must not survive:
+    the model relays it as fact, and the user is told a message was sent or a
+    figure was read when neither happened.
+    """
+    import os
+
+    def _guarded(params: Dict[str, Any]) -> Dict[str, Any]:
+        if os.getenv("ARIA_ALLOW_STUB_TOOLS", "").strip() in ("1", "true", "yes"):
+            result = dict(handler(params) or {})
+            result["stub"] = True
+            result["warning"] = f"{name} returned canned data; {service} is not connected."
+            return result
+        return {
+            "success": False,
+            "error": (
+                f"{name} is not implemented — it is a shape-only stub. "
+                f"Connecting it requires {service}. "
+                f"Do not report its result as if the action happened."
+            ),
+            "stub": True,
+        }
+
+    _guarded.__name__ = getattr(handler, "__name__", name)
+    _guarded.__doc__ = getattr(handler, "__doc__", "")
+    return _guarded
+
+
+def register_extended_tools(registry_or_dict: Any) -> None:
+    """Register the extended connector stubs, guarded.
+
+    Registered as ``(handler, description)`` pairs: bare functions were being
+    stored here, and ToolExecutor indexes ``local_tools[name][0]``, so calling
+    any of these raised ``TypeError: 'function' object is not subscriptable``.
+    They were unreachable in practice only because none of them had a schema.
+    """
+    handlers = {
+        "send_slack_notification": tool_send_slack_notification,
+        "push_feishu_card": tool_push_feishu_card,
+        "parse_tradingview_alert": tool_parse_tradingview_alert,
+        "get_quickbooks_pnl": tool_get_quickbooks_pnl,
+        "get_shopify_store_analytics": tool_get_shopify_store_analytics,
+        "query_snowflake_data": tool_query_snowflake_data,
+    }
+    tools = {
+        name: (
+            stub_guard(name, _STUB_TOOLS[name], handler),
+            f"[not implemented] {name} — needs {_STUB_TOOLS[name]}",
+        )
+        for name, handler in handlers.items()
+    }
+    if hasattr(registry_or_dict, "register"):
+        for name, entry in tools.items():
+            registry_or_dict.register(name, entry[0])
+    elif isinstance(registry_or_dict, dict):
+        registry_or_dict.update(tools)