Skip to content

"Vibe-Trading: Your Personal Trading Agent"

24.7 KB
Raw Blame
"""Agent tool: financial-rigor checks with exact decimal arithmetic.

A thin ``BaseTool`` wrapper around six pure-stdlib verification routines that
guard investment research against numerical error and hallucinated metrics.
Auto-discovered and registered via ``BaseTool.__subclasses__()``.

All arithmetic uses ``decimal.Decimal`` under a shared 28-digit context, so
results are free of IEEE-754 drift and are reproducible and auditable. The
tool takes raw numbers only — it does not fetch data. Pair it with the
market-data / financial-statement tools: fetch there, verify here.

Sub-commands (selected via ``command``):

- ``verify_market_cap`` — price × shares vs a reported cap; verdict at 1%/5%.
- ``verify_valuation`` — PE / PB / ROE / P/FCF / FCF yield / dividend yield /
  PS derived from raw per-share inputs.
- ``cross_validate`` — one field across several sources, flag deviations over
  a tolerance (default 2%), expose the median consensus.
- ``benford`` — Benford's-law first-digit check on a list of values; needs
  ≥50 samples; reports MAD / chi-square / conformity.
- ``calc`` — safe exact evaluation of an arithmetic expression string
  (AST-whitelisted: numbers and +, -, *, / only).
- ``three_scenario`` — bull / base / bear target prices from EPS-growth and
  target-PE assumptions.

Read-only: returns JSON verdicts, writes nothing.
"""

from __future__ import annotations

import ast
import json
import math
from decimal import Context, Decimal, ROUND_HALF_EVEN
from typing import Any

from src.agent.tools import BaseTool

_CTX = Context(prec=28, rounding=ROUND_HALF_EVEN)

# Benford's-law expected first-digit frequencies.
_BENFORD = {d: math.log10(1 + 1 / d) for d in range(1, 10)}

# AST operator handlers for the ``calc`` evaluator. Only numbers and
# +, -, *, / (with optional unary sign) are honoured; anything else raises.
_AST_BINOPS = {
    ast.Add: _CTX.add,
    ast.Sub: _CTX.subtract,
    ast.Mult: _CTX.multiply,
    ast.Div: _CTX.divide,
}
_AST_UNARYOPS = {
    ast.UAdd: lambda d: d,
    ast.USub: lambda d: -d,
}


def _err(msg: str) -> str:
    """Build the standard error JSON envelope."""
    return json.dumps({"status": "error", "error": msg}, ensure_ascii=False)


def _exact(value: Any) -> Decimal:
    """Convert any numeric to an exact Decimal, avoiding float binary traps.

    Raises:
        ValueError: If ``value`` is a bool or is NaN / infinite, so a bad input
            becomes an error envelope instead of an ``ok`` verdict.
    """
    if isinstance(value, bool):
        raise ValueError("boolean is not a valid number")
    number = value if isinstance(value, Decimal) else Decimal(str(value))
    if not number.is_finite():
        raise ValueError(f"number must be finite, got {value}")
    return number


def _fmt(value: float) -> str:
    """Render a large number with K / M / B / T suffixes for readability."""
    abs_v = abs(value)
    if abs_v >= 1e12:
        return f"{value / 1e12:.2f}T"
    if abs_v >= 1e9:
        return f"{value / 1e9:.2f}B"
    if abs_v >= 1e6:
        return f"{value / 1e6:.2f}M"
    if abs_v >= 1e3:
        return f"{value / 1e3:.2f}K"
    return f"{value:,.2f}"


def _eval_arith_node(node: ast.AST) -> Decimal:
    """Recursively evaluate an arithmetic AST node in the Decimal domain.

    Args:
        node: An AST node from a parsed expression.

    Returns:
        The exact Decimal value of the node.

    Raises:
        ValueError: If the node is not a supported numeric/arithmetic form.
    """
    if isinstance(node, ast.Constant):
        # bool is a subclass of int — reject it explicitly.
        if isinstance(node.value, bool) or not isinstance(node.value, (int, float)):
            raise ValueError("only numeric constants are allowed")
        return _exact(node.value)
    if isinstance(node, ast.BinOp):
        op_fn = _AST_BINOPS.get(type(node.op))
        if op_fn is None:
            raise ValueError(f"unsupported operator: {type(node.op).__name__}")
        return op_fn(_eval_arith_node(node.left), _eval_arith_node(node.right))
    if isinstance(node, ast.UnaryOp):
        op_fn = _AST_UNARYOPS.get(type(node.op))
        if op_fn is None:
            raise ValueError(f"unsupported unary operator: {type(node.op).__name__}")
        return op_fn(_eval_arith_node(node.operand))
    raise ValueError(f"disallowed element in expression: {type(node).__name__}")


def _safe_arith(expr: str) -> Decimal:
    """Evaluate a numeric arithmetic expression in the exact-Decimal domain.

    The expression is parsed and evaluated recursively with Decimal arithmetic,
    so ``0.1 + 0.2`` is exactly ``0.3`` — no IEEE-754 drift, and no ``eval``.
    Only numbers and the operators ``+ - * /`` (with optional unary sign) are
    permitted; any other AST node raises ``ValueError``.

    Args:
        expr: Arithmetic expression string, e.g. ``"510 * 9.11e9"``.

    Returns:
        The exact Decimal result.

    Raises:
        ValueError: If the expression is malformed or contains a disallowed
            element.
    """
    try:
        tree = ast.parse(expr, mode="eval")
    except SyntaxError as exc:
        raise ValueError(f"malformed expression: {exc}") from exc
    return _eval_arith_node(tree.body)


# ---------------------------------------------------------------------------
# Core verification routines (pure, return structured dicts, no I/O)
# ---------------------------------------------------------------------------

def verify_market_cap(
    price: Any, shares: Any, reported_cap: Any, currency: str = "",
) -> dict[str, Any]:
    """Verify ``market cap = price × shares`` against a reported value.

    Args:
        price: Current share price.
        shares: Total share count.
        reported_cap: The market-cap figure being checked.
        currency: Optional currency label for display only.

    Returns:
        Verdict dict. ``verdict`` is ``pass`` (≤1%), ``warn`` (1–5%) or
        ``fail`` (>5%).
    """
    p, s, r = _exact(price), _exact(shares), _exact(reported_cap)
    calculated = _CTX.multiply(p, s)
    # A zero reported cap has no percent deviation; it can only match a zero
    # calculated cap, so a non-zero product fails rather than reading as 0%.
    deviation = abs(float(calculated - r) / float(r)) * 100 if r != 0 else None
    if deviation is None:
        verdict = "pass" if calculated == 0 else "fail"
        deviation = 0.0 if calculated == 0 else None
    elif deviation > 5:
        verdict = "fail"
    elif deviation > 1:
        verdict = "warn"
    else:
        verdict = "pass"
    return {
        "price": float(p),
        "shares": float(s),
        "currency": currency,
        "calculated_market_cap": float(calculated),
        "calculated_market_cap_display": _fmt(float(calculated)),
        "reported_market_cap": float(r),
        "deviation_pct": round(deviation, 4) if deviation is not None else None,
        "verdict": verdict,
    }


def verify_valuation(
    price: Any,
    eps: Any | None = None,
    bvps: Any | None = None,
    fcf_per_share: Any | None = None,
    dividend: Any | None = None,
    revenue_per_share: Any | None = None,
) -> dict[str, Any]:
    """Derive valuation ratios from raw per-share inputs (exact decimal).

    Each optional input, when supplied and non-zero, contributes its metric(s).
    ROE additionally requires both ``eps`` and ``bvps``. Earnings yield and
    FCF yield also need a non-zero price; a zero price omits them, the same
    way dividend yield already does, instead of raising.

    Args:
        price: Current share price.
        eps: Earnings per share (TTM).
        bvps: Book value per share.
        fcf_per_share: Free cash flow per share.
        dividend: Dividend per share.
        revenue_per_share: Revenue per share.

    Returns:
        Dict with ``price`` and a ``metrics`` map (PE, PB, ROE_pct, P_FCF,
        FCF_yield_pct, dividend_yield_pct, PS — whichever apply).
    """
    p = _exact(price)
    metrics: dict[str, float] = {}
    if eps is not None:
        e = _exact(eps)
        if e != 0:
            metrics["PE"] = float(_CTX.divide(p, e))
            if p != 0:
                metrics["earnings_yield_pct"] = float(_CTX.divide(e, p) * 100)
    if bvps is not None:
        b = _exact(bvps)
        if b != 0:
            metrics["PB"] = float(_CTX.divide(p, b))
            if eps is not None and _exact(eps) != 0:
                metrics["ROE_pct"] = float(_CTX.divide(_exact(eps), b) * 100)
    if fcf_per_share is not None:
        f = _exact(fcf_per_share)
        if f != 0:
            metrics["P_FCF"] = float(_CTX.divide(p, f))
            if p != 0:
                metrics["FCF_yield_pct"] = float(_CTX.divide(f, p) * 100)
    if dividend is not None:
        d = _exact(dividend)
        if p != 0:
            metrics["dividend_yield_pct"] = float(_CTX.divide(d, p) * 100)
    if revenue_per_share is not None:
        rps = _exact(revenue_per_share)
        if rps != 0:
            metrics["PS"] = float(_CTX.divide(p, rps))
    return {"price": float(p), "metrics": metrics}


def cross_validate(
    field_name: str,
    source_values: dict[str, Any],
    unit: str = "",
    tolerance_pct: float = 2.0,
) -> dict[str, Any]:
    """Compare one field across sources, flag deviations over a tolerance.

    The median of the supplied values is used as the reference, and each
    source's percent deviation from it is reported.

    Args:
        field_name: Field being compared (e.g. ``"revenue"``).
        source_values: Mapping of source name to numeric value.
        unit: Optional unit label for display.
        tolerance_pct: Percent deviation above which a source is inconsistent.

    Returns:
        Dict with ``median_reference``/``consensus``, ``all_consistent`` and a
        per-source breakdown.
    """
    values = {k: _exact(v) for k, v in source_values.items()}
    nums = sorted(float(v) for v in values.values())
    n = len(nums)
    if n == 0:
        median = 0.0
    elif n % 2 == 1:
        median = nums[n // 2]
    else:
        median = (nums[n // 2 - 1] + nums[n // 2]) / 2
    per_source: list[dict[str, Any]] = []
    all_consistent = True
    for src, val in values.items():
        # Against a zero reference only an exactly-zero value agrees; any
        # other value has no finite percent deviation and is inconsistent.
        if median != 0:
            dev = abs(float(val) - median) / abs(median) * 100
            consistent = dev <= tolerance_pct
        else:
            dev = 0.0 if float(val) == 0 else None
            consistent = dev is not None
        all_consistent = all_consistent and consistent
        per_source.append({
            "source": src,
            "value": float(val),
            "deviation_pct": round(dev, 4) if dev is not None else None,
            "consistent": consistent,
        })
    return {
        "field": field_name,
        "unit": unit,
        "tolerance_pct": tolerance_pct,
        "median_reference": median,
        "consensus": median,
        "all_consistent": all_consistent,
        "per_source": per_source,
    }


def benford_check(values: list[Any]) -> dict[str, Any]:
    """First-digit Benford's-law check on a list of financial values.

    Args:
        values: Numeric values to inspect.

    Returns:
        Dict with ``sample_size``, ``reliable`` (False when ``n < 50``), and —
        when reliable — ``mad`` (Nigrini's MAD), ``chi2``, ``conformity`` and a
        per-digit ``distribution``.
    """
    digits: list[int] = []
    for raw in values:
        # Decimal construction preserves the supplied digits without a float
        # round-trip or context rounding at a leading-digit boundary.
        value = Decimal(int(raw)) if isinstance(raw, bool) else Decimal(str(raw))
        if value.is_finite() and not value.is_zero():
            digits.append(value.as_tuple().digits[0])
    n = len(digits)
    if n < 50:
        return {
            "sample_size": n,
            "reliable": False,
            "note": "Benford analysis needs >= 50 samples to be meaningful",
        }
    counts = {d: 0 for d in range(1, 10)}
    for d in digits:
        counts[d] += 1
    observed = {d: counts[d] / n for d in range(1, 10)}
    mad = sum(abs(observed[d] - _BENFORD[d]) for d in range(1, 10)) / 9
    chi2 = sum(
        (counts[d] - _BENFORD[d] * n) ** 2 / (_BENFORD[d] * n) for d in range(1, 10)
    )
    if mad < 0.006:
        conformity = "close"
    elif mad < 0.012:
        conformity = "acceptable"
    elif mad < 0.015:
        conformity = "marginal"
    else:
        conformity = "nonconforming"
    distribution = [
        {
            "digit": d,
            "observed": round(observed[d], 4),
            "expected": round(_BENFORD[d], 4),
            "deviation": round(observed[d] - _BENFORD[d], 4),
        }
        for d in range(1, 10)
    ]
    return {
        "sample_size": n,
        "reliable": True,
        "mad": round(mad, 6),
        "chi2": round(chi2, 4),
        "conformity": conformity,
        "is_conforming": mad < 0.015,
        "distribution": distribution,
    }


def exact_calc(expr: str) -> dict[str, Any]:
    """Evaluate an arithmetic expression with exact decimal arithmetic.

    Args:
        expr: Arithmetic expression string (numbers and ``+ - * /`` only).

    Returns:
        Dict with ``result`` (float) and ``result_exact`` (Decimal string).

    Raises:
        ValueError: If the expression is malformed or contains a disallowed
            element (surfaced by the caller as a tool error).
    """
    d = _safe_arith(expr)
    return {"expr": expr, "result": float(d), "result_exact": str(d)}


def three_scenario_valuation(
    current_price: Any,
    current_eps: Any,
    shares_billion: Any,
    growth_optimistic: Any,
    growth_neutral: Any,
    growth_pessimistic: Any,
    pe_optimistic: Any,
    pe_neutral: Any,
    pe_pessimistic: Any,
    years: int = 3,
    currency: str = "",
) -> dict[str, Any]:
    """Bull / base / bear target prices from EPS-growth and target-PE assumptions.

    Future EPS = ``current_eps × (1 + growth) ** years``; target price = future
    EPS × target PE. All math is exact decimal.

    Args:
        current_price: Current share price.
        current_eps: Current EPS.
        shares_billion: Share count in billions.
        growth_optimistic / growth_neutral / growth_pessimistic: Annual EPS
            growth rate per scenario (e.g. ``0.15`` for 15%).
        pe_optimistic / pe_neutral / pe_pessimistic: Target PE per scenario.
        years: Forecast horizon in years.
        currency: Optional currency label.

    Returns:
        Dict with the assumptions and a ``scenarios`` list, each carrying its
        ``future_eps``, ``target_price`` and ``upside_pct`` (``None`` when the
        current price is not positive).

    Raises:
        ValueError: If ``years`` is negative.
    """
    p, eps, shares = _exact(current_price), _exact(current_eps), _exact(shares_billion)
    if int(years) < 0:
        raise ValueError(f"years must be >= 0, got {years!r}")
    spec = [
        ("bull", growth_optimistic, pe_optimistic),
        ("base", growth_neutral, pe_neutral),
        ("bear", growth_pessimistic, pe_pessimistic),
    ]
    scenarios: list[dict[str, Any]] = []
    normalized: list[str] = []
    for name, growth, pe in spec:
        g, target_pe = _exact(growth), _exact(pe)
        # Defensive: LLMs frequently pass "15%" as 15 instead of 0.15. Treat
        # |growth| > 1 (i.e. > 100%) as a percent and normalize, flagging it.
        if abs(float(g)) > 1:
            g = _CTX.divide(g, Decimal("100"))
            normalized.append(name)
        future_eps = eps
        for _ in range(int(years)):
            future_eps = _CTX.multiply(future_eps, _CTX.add(Decimal("1"), g))
        target_price = _CTX.multiply(future_eps, target_pe)
        # Upside relative to a non-positive price is undefined; report null
        # rather than a 0% that reads as "fairly valued".
        upside = float(target_price - p) / float(p) * 100 if p > 0 else None
        scenarios.append({
            "scenario": name,
            "annual_growth": float(g),
            "target_pe": float(target_pe),
            "future_eps": float(future_eps),
            "target_price": float(target_price),
            "upside_pct": round(upside, 2) if upside is not None else None,
        })
    result: dict[str, Any] = {
        "current_price": float(p),
        "current_eps": float(eps),
        "shares_billion": float(shares),
        "years": int(years),
        "currency": currency,
        "scenarios": scenarios,
    }
    if normalized:
        result["growth_normalized_from_percent"] = normalized
        result["note"] = (
            f"growth values > 1 (100%) were treated as percentages and divided "
            f"by 100 for scenarios: {normalized}. Pass 0.15 for 15% to avoid this."
        )
    return result


class FinancialRigorTool(BaseTool):
    """Exact-decimal financial verification across six sub-commands."""

    name = "financial_rigor"
    description = (
        "Verify financial-data accuracy with exact decimal arithmetic (no float "
        "drift). Takes raw numbers only — does not fetch data. Pair it with the "
        "market-data / financial-statement tools: fetch there, verify here. Six "
        "sub-commands selected via `command`: 'verify_market_cap' (price x shares "
        "vs reported cap, verdict at 1%/5%), 'verify_valuation' (PE/PB/ROE/P-FCF/"
        "yields/PS from raw per-share inputs), 'cross_validate' (one field across "
        "sources, flag deviations > tolerance_pct, expose median consensus), "
        "'benford' (Benford first-digit fabrication check, needs >=50 samples), "
        "'calc' (safe exact arithmetic on an expression string), 'three_scenario' "
        "(bull/base/bear target prices from EPS-growth and target-PE assumptions)."
    )
    parameters = {
        "type": "object",
        "properties": {
            "command": {
                "type": "string",
                "enum": [
                    "verify_market_cap", "verify_valuation", "cross_validate",
                    "benford", "calc", "three_scenario",
                ],
                "description": "Which verification to run.",
            },
            "price": {"type": "number", "description": "Share price."},
            "shares": {
                "type": "number",
                "description": "verify_market_cap: total share count; "
                               "three_scenario: share count in billions.",
            },
            "reported_cap": {"type": "number", "description": "Reported market cap."},
            "currency": {"type": "string", "description": "Currency label (display only)."},
            "eps": {"type": "number", "description": "Earnings per share."},
            "bvps": {"type": "number", "description": "Book value per share."},
            "fcf_per_share": {"type": "number", "description": "Free cash flow per share."},
            "dividend": {"type": "number", "description": "Dividend per share."},
            "revenue_per_share": {"type": "number", "description": "Revenue per share."},
            "field": {"type": "string", "description": "cross_validate: field name."},
            "source_values": {
                "type": "object",
                "description": "cross_validate: mapping of source name to value.",
            },
            "unit": {"type": "string", "description": "cross_validate: unit label."},
            "tolerance_pct": {
                "type": "number", "default": 2.0,
                "description": "cross_validate: max acceptable percent deviation.",
            },
            "values": {
                "type": "array", "items": {"type": "number"},
                "description": "benford: list of financial values to inspect.",
            },
            "expr": {
                "type": "string",
                "description": "calc: arithmetic expression (numbers and + - * /).",
            },
            "growth": {
                "type": "array", "items": {"type": "number"},
                "minItems": 3, "maxItems": 3,
                "description": "three_scenario: annual EPS growth as a decimal [bull, base, bear], e.g. 0.15 for 15% (values > 1 are auto-treated as percent).",
            },
            "pe": {
                "type": "array", "items": {"type": "number"},
                "minItems": 3, "maxItems": 3,
                "description": "three_scenario: target PE [bull, base, bear].",
            },
            "years": {"type": "integer", "default": 3, "description": "three_scenario horizon."},
        },
        "required": ["command"],
    }
    is_readonly = True
    deterministic = True  # pure computation; identical args -> identical result
    repeatable = True  # loop.py dedups non-repeatable tools by name; users call
                       # different sub-commands / params in one session.

    def execute(self, **kwargs: Any) -> str:
        """Dispatch to the requested sub-command and return a JSON envelope.

        Args:
            **kwargs: ``command`` plus the inputs for that sub-command.

        Returns:
            JSON string — ``status="ok"`` with the verdict on success,
            ``status="error"`` with a message otherwise.
        """
        command = str(kwargs.get("command") or "").strip()
        try:
            if command == "verify_market_cap":
                for key in ("price", "shares", "reported_cap"):
                    if kwargs.get(key) is None:
                        return _err(f"{key} is required for verify_market_cap")
                result: dict[str, Any] = verify_market_cap(
                    kwargs["price"], kwargs["shares"], kwargs["reported_cap"],
                    currency=str(kwargs.get("currency") or ""),
                )
            elif command == "verify_valuation":
                if kwargs.get("price") is None:
                    return _err("price is required for verify_valuation")
                result = verify_valuation(
                    kwargs["price"], kwargs.get("eps"), kwargs.get("bvps"),
                    kwargs.get("fcf_per_share"), kwargs.get("dividend"),
                    kwargs.get("revenue_per_share"),
                )
            elif command == "cross_validate":
                if not kwargs.get("field") or not kwargs.get("source_values"):
                    return _err("field and source_values are required for cross_validate")
                result = cross_validate(
                    str(kwargs["field"]), kwargs["source_values"],
                    unit=str(kwargs.get("unit") or ""),
                    tolerance_pct=2.0 if kwargs.get("tolerance_pct") is None else float(kwargs["tolerance_pct"]),
                )
            elif command == "benford":
                vals = kwargs.get("values")
                if not isinstance(vals, list) or not vals:
                    return _err("values (non-empty list) is required for benford")
                result = benford_check(vals)
            elif command == "calc":
                if not kwargs.get("expr"):
                    return _err("expr is required for calc")
                result = exact_calc(str(kwargs["expr"]))
            elif command == "three_scenario":
                for key in ("price", "eps", "shares", "growth", "pe"):
                    if kwargs.get(key) is None:
                        return _err(f"{key} is required for three_scenario")
                growth = kwargs["growth"]
                pe = kwargs["pe"]
                if not isinstance(growth, list) or len(growth) != 3:
                    return _err("growth must be a list of 3 numbers [bull, base, bear]")
                if not isinstance(pe, list) or len(pe) != 3:
                    return _err("pe must be a list of 3 numbers [bull, base, bear]")
                result = three_scenario_valuation(
                    kwargs["price"], kwargs["eps"], kwargs["shares"],
                    growth[0], growth[1], growth[2],
                    pe[0], pe[1], pe[2],
                    years=3 if kwargs.get("years") is None else int(kwargs["years"]),
                    currency=str(kwargs.get("currency") or ""),
                )
            else:
                return _err(f"unknown command: {command}")
        except Exception as exc:  # noqa: BLE001 - surface a clean tool error
            return json.dumps(
                {"status": "error", "command": command, "error": str(exc)},
                ensure_ascii=False,
            )
        try:
            # allow_nan=False: a finite input can still overflow float() to inf,
            # and NaN / Infinity are not valid JSON.
            return json.dumps(
                {"status": "ok", "command": command, **result},
                ensure_ascii=False, allow_nan=False,
            )
        except ValueError:
            return json.dumps(
                {"status": "error", "command": command,
                 "error": "result is not representable as a finite number"},
                ensure_ascii=False,
            )