aria-code 0.167.0__py3-none-win_amd64.whl

aria_code/tools/enterprise_finance_tools.py

@@ -0,0 +1,202 @@
+"""Corporate financial metrics from actual, period-aligned statements."""
+from __future__ import annotations
+
+import math
+import time
+from typing import Any, Dict, List
+
+
+def _number(data: dict, key: str) -> float | None:
+    value = data.get(key)
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        raise ValueError(f"{key} must be a finite number")
+    try:
+        value = float(value)
+    except (TypeError, ValueError, OverflowError) as exc:
+        raise ValueError(f"{key} must be a finite number") from exc
+    if not math.isfinite(value):
+        raise ValueError(f"{key} must be a finite number")
+    return value
+
+
+def _ratio(numerator, denominator, scale=1):
+    if numerator is None or denominator is None or denominator == 0:
+        return None
+    value = numerator / denominator * scale
+    return round(value, 2) if math.isfinite(value) else None
+
+
+def compute_financial_metrics(income: dict, balance: dict, cashflow: dict) -> dict:
+    """Missing inputs stay unknown; zero denominators never become one."""
+    revenue = _number(income, "revenue")
+    net_income = _number(income, "net_income")
+    assets = _number(balance, "total_assets")
+    equity = _number(balance, "total_equity")
+    current_assets = _number(balance, "current_assets")
+    current_liabilities = _number(balance, "current_liabilities")
+    inventory = _number(balance, "inventory")
+    quick_assets = None if current_assets is None or inventory is None else current_assets - inventory
+    return {
+        "gross_margin_pct": _ratio(_number(income, "gross_profit"), revenue, 100),
+        "net_margin_pct": _ratio(net_income, revenue, 100),
+        "dupont": {
+            "roe": _ratio(net_income, equity, 100),
+            "net_profit_margin": _ratio(net_income, revenue, 100),
+            "asset_turnover": _ratio(revenue, assets),
+            "equity_multiplier": _ratio(assets, equity),
+        },
+        "working_capital": {
+            "current_ratio": _ratio(current_assets, current_liabilities),
+            "quick_ratio": _ratio(quick_assets, current_liabilities),
+        },
+        # The former three-term approximation is not a full Altman model.
+        "altman_z_score": None,
+        "solvency_risk": "UNKNOWN",
+        "limitations": ["Unavailable metrics are null. No complete Altman model was evaluated."],
+    }
+
+
+def _fetch_yahoo_statements(symbol: str):
+    import yfinance as yf
+    from curl_cffi.requests import Session
+
+    deadline = time.monotonic() + 20
+
+    class BoundedSession(Session):
+        def request(self, method, url, **kwargs):
+            # yfinance passes timeout=30 explicitly, overriding a session default.
+            requested = kwargs.get("timeout", 8)
+            if isinstance(requested, (tuple, list)):
+                requested = max(requested)
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError("Financial statement source deadline exceeded")
+            kwargs["timeout"] = min(float(requested or 8), 8, remaining)
+            return super().request(method, url, **kwargs)
+
+    with BoundedSession(impersonate="chrome") as session:
+        ticker = yf.Ticker(symbol, session=session)
+        inc_df = ticker.income_stmt
+        bal_df = ticker.balance_sheet
+        if time.monotonic() >= deadline:
+            raise TimeoutError("Financial statement source deadline exceeded")
+        if inc_df.empty or bal_df.empty:
+            raise ValueError("empty_statements")
+        periods = inc_df.columns.intersection(bal_df.columns)
+        if periods.empty:
+            raise ValueError("no_common_period")
+        period = max(periods)
+        inc, bal = inc_df[period], bal_df[period]
+        def fields(series, mapping):
+            values = {}
+            for source, target in mapping.items():
+                value = series.get(source)
+                # pandas marks absent financial cells with NaN.
+                if value is not None and math.isfinite(float(value)):
+                    values[target] = float(value)
+            return values
+        income = fields(inc, {
+            "Total Revenue": "revenue", "Cost Of Revenue": "cost_of_goods_sold",
+            "Gross Profit": "gross_profit", "Operating Income": "operating_income", "Net Income": "net_income",
+        })
+        balance = fields(bal, {
+            "Total Assets": "total_assets", "Stockholders Equity": "total_equity",
+            "Current Assets": "current_assets", "Current Liabilities": "current_liabilities",
+            "Inventory": "inventory", "Retained Earnings": "retained_earnings",
+        })
+        if not income:
+            raise ValueError("empty_statements")
+        return income, balance, str(period.date())
+
+
+def tool_analyze_financial_statements(params: Dict[str, Any]) -> Dict[str, Any]:
+    company_name = str(params.get("company_name") or "").strip().upper()
+    data = params.get("financials") or {}
+    if not isinstance(data, dict):
+        return {"success": False, "error_code": "invalid_financials", "error": "financials must be an object"}
+    if params.get("file_path"):
+        return {"success": False, "error_code": "use_file_tool", "error": "Read the JSON file with read_file, then pass its contents as financials. This tool does not read arbitrary paths."}
+    income, balance, cashflow = (data.get(k, {}) for k in ("income_statement", "balance_sheet", "cashflow"))
+    if not all(isinstance(item, dict) for item in (income, balance, cashflow)):
+        return {"success": False, "error_code": "invalid_financials", "error": "Statement sections must be objects"}
+    source, period = "caller-supplied statements", None
+    source_attempts = []
+    disclosure = {}
+    diagnosis = "missing_statements"
+    if company_name and len(company_name) <= 10 and not income:
+        if not params.get("network_enabled", True):
+            diagnosis = "network_disabled"
+        else:
+            try:
+                income, balance, period = _fetch_yahoo_statements(company_name)
+                source = f"yfinance:{company_name}"
+            except ImportError:
+                diagnosis = "dependency_missing"
+            except TimeoutError:
+                diagnosis = "source_timeout"
+            except ValueError as exc:
+                diagnosis = str(exc) if str(exc) in {"empty_statements", "no_common_period"} else "source_error"
+            except Exception:
+                diagnosis = "source_unavailable"
+            source_attempts.append({'source': 'yfinance', 'success': bool(income), 'error_code': None if income else diagnosis})
+            if not income:
+                from aria_code.datasources.sec_statements import SECError, fetch_annual_statements
+                try:
+                    disclosure = fetch_annual_statements(company_name)
+                    income, balance = disclosure['income_statement'], disclosure['balance_sheet']
+                    cashflow, period = disclosure['cashflow'], disclosure['period']
+                    source = f"sec-edgar:{company_name}"
+                    source_attempts.append({'source': 'sec-edgar', 'success': True})
+                except SECError as exc:
+                    source_attempts.append({'source': 'sec-edgar', 'success': False, 'error_code': exc.code})
+    if not income:
+        fallback_code = next((attempt.get('error_code') for attempt in source_attempts if attempt['source'] == 'sec-edgar'), None)
+        fallback_message = {
+            'sec_identity_required': ' SEC fallback needs your declared company/contact email.',
+            'sec_access_denied': ' SEC fallback denied access.',
+            'sec_rate_limited': ' SEC fallback is rate-limited; no automatic retry was made.',
+        }.get(fallback_code, f' SEC fallback: {fallback_code}.' if fallback_code else '')
+        return {
+            "success": False, "error_code": diagnosis, "source": f"yfinance:{company_name}",
+            "source_attempts": source_attempts,
+            "error": f"No financial statements available for {company_name or 'this company'} ({diagnosis}).{fallback_message} This tool does not estimate missing figures.",
+            "next_actions": ["Continue other analysis using available market data; disclose missing financial statements.",
+                             "Supply income_statement, balance_sheet and cashflow through financials.",
+                             "Check source_attempts. Configure EDGAR_USER_AGENT with your company and contact email for the SEC fallback. Google login does not authorize financial sources."],
+        }
+    try:
+        metrics = compute_financial_metrics(income, balance, cashflow)
+    except ValueError as exc:
+        return {"success": False, "error_code": "invalid_financials", "error": str(exc)}
+    metrics.update(company_name=company_name, data_source=source, period=period)
+    if disclosure:
+        metrics.update({key: value for key, value in disclosure.items() if key not in {'income_statement', 'balance_sheet', 'cashflow'}})
+        metrics['limitations'].append('SEC metrics describe the disclosed annual period, not live market data. Cash flow was not evaluated.')
+        if disclosure.get('stale'):
+            metrics['limitations'].append('The selected annual period is over 550 days old; do not describe it as current financial data.')
+    def display(value):
+        return "unavailable" if value is None else str(value)
+    return {
+        "success": True, "data": metrics, "source_attempts": source_attempts,
+        "summary": f"{company_name} financial metrics ({source}, period {period or 'caller supplied'}): gross margin {display(metrics['gross_margin_pct'])}%; net margin {display(metrics['net_margin_pct'])}%; ROE {display(metrics['dupont']['roe'])}%. Missing metrics are unavailable; solvency was not classified.",
+    }
+
+
+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": "Compute supported corporate financial metrics. For a ticker, try Yahoo then SEC annual disclosures. Missing metrics stay unknown; no solvency classification is inferred. Each result identifies its source and reporting period.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "file_path": {"type": "string", "description": "Use read_file for JSON and pass financials; direct paths are not read"},
+                "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)