Skip to content

"Vibe-Trading: Your Personal Trading Agent"

8.5 KB
Raw Blame
"""Read-only options-chain tool backed by the shared Yahoo Finance client.

Surfaces the calls/puts ladder for a US-listed underlying (strike, bid/ask,
last price, volume, open interest, implied volatility, and the in/out-of-money
flag) for a single expiration. All HTTP routes through
:func:`backtest.loaders.yahoo_client.get_options`, which throttles per host and
reuses one session, so the agent never hits Yahoo un-spaced.
"""

from __future__ import annotations

import json
import math
from typing import Any, Dict, List, Optional

from backtest.loaders import yahoo_client
from src.agent.tools import BaseTool

# Upper bound on contracts emitted per side so a deep chain cannot blow up the
# tool payload handed back to the model.
_MAX_CONTRACTS_PER_SIDE = 60

# Yahoo contract fields we surface, mapped to our snake_case envelope keys.
_CONTRACT_FIELDS = (
    ("contractSymbol", "contract_symbol"),
    ("strike", "strike"),
    ("lastPrice", "last_price"),
    ("bid", "bid"),
    ("ask", "ask"),
    ("volume", "volume"),
    ("openInterest", "open_interest"),
    ("impliedVolatility", "implied_volatility"),
    ("inTheMoney", "in_the_money"),
    ("expiration", "expiration"),
)


class OptionsChainTool(BaseTool):
    """Fetch a US equity option chain (calls + puts) with greeks-grade fields."""

    name = "get_options_chain"
    description = (
        "Fetch the US-listed options chain (calls and puts) for one expiration "
        "via Yahoo Finance: per-contract strike, bid/ask, last price, volume, "
        "open interest, implied volatility, and in-the-money flag, plus the list "
        "of available expirations (epoch seconds). Read-only US options data. "
        'Example: get_options_chain(ticker="AAPL").'
    )
    parameters = {
        "type": "object",
        "properties": {
            "ticker": {
                "type": "string",
                "description": (
                    "US underlying symbol, e.g. 'AAPL' or 'AAPL.US' (the .US "
                    "suffix is stripped). Required."
                ),
            },
            "expiration": {
                "type": "integer",
                "description": (
                    "Optional expiration as Unix epoch seconds (one of the "
                    "values from the returned expirations list). Omit for the "
                    "nearest expiration."
                ),
            },
        },
        "required": ["ticker"],
    }

    def execute(self, **kwargs: Any) -> str:
        """Return a JSON-string envelope with the calls/puts chain.

        Args:
            **kwargs: ``ticker`` (str, required) and optional ``expiration``
                (int epoch seconds).

        Returns:
            A JSON string. On success:
            ``{"ok": true, "market": "us", "source": "yahoo", "data": {...}}``
            where ``data`` carries ``ticker``, ``expirations``, ``expiration``,
            ``calls``, ``puts``, and per-side counts. On failure:
            ``{"ok": false, "error": str}``.
        """
        ticker = str(kwargs.get("ticker") or "").strip()
        if not ticker:
            return _error("ticker is required")

        expiration = kwargs.get("expiration")
        normalized_expiration = _coerce_expiration(expiration)
        if expiration is not None and normalized_expiration is None:
            return _error("expiration must be Unix epoch seconds (integer)")

        try:
            result = yahoo_client.get_options(
                ticker, expiration=normalized_expiration
            )
        except Exception as exc:  # noqa: BLE001 - surface as error envelope
            return _error(f"yahoo options request failed: {exc}")

        # When the caller explicitly requested an expiration, validate that
        # Yahoo returned a chain for that exact expiration.  A non-matching
        # expiration returns an empty or stale chain silently, which is
        # misleading.  The tool owns the guarantee that its envelope
        # corresponds to the caller's requested expiration; the Yahoo client
        # only guarantees raw data.
        if normalized_expiration is not None:
            dates = result.get("expirationDates")
            if not isinstance(dates, list):
                return _error(
                    "malformed Yahoo response: expirationDates is not a list"
                )
            if normalized_expiration not in dates:
                return _error(
                    f"expiration {normalized_expiration} is not among the "
                    f"available dates; available: {dates[:8]}"
                    f"{'...' if len(dates) > 8 else ''}"
                )
            options = result.get("options") or []
            if not isinstance(options, list) or not options:
                # The date IS listed (checked above), so this is Yahoo
                # returning no chain block for it — not an unlisted ticker.
                return _error(
                    f"no option chain returned for expiration "
                    f"{normalized_expiration} although Yahoo lists that date; "
                    f"retry, or pick another expiration from: {dates[:8]}"
                )
            block = options[0]
            if not isinstance(block, dict):
                return _error(
                    "malformed Yahoo response: options block is not a dict"
                )
            block_date = block.get("expirationDate")
            if block_date != normalized_expiration:
                return _error(
                    f"expiration {normalized_expiration} did not match the "
                    f"returned chain (block expiration is {block_date})"
                )

        return _success(ticker, result)


def _coerce_expiration(value: Any) -> Optional[int]:
    """Coerce an epoch-second expiration to ``int``; ``None`` when absent/bad."""
    if value is None:
        return None
    if isinstance(value, bool):
        return None
    try:
        return int(value)
    except (TypeError, ValueError, OverflowError):
        return None


def _success(ticker: str, result: Dict[str, Any]) -> str:
    """Build the success envelope from a quote-chain ``result[0]`` mapping."""
    expirations = [
        epoch for epoch in (result.get("expirationDates") or []) if epoch is not None
    ]
    options = result.get("options") or []
    block = options[0] if options and isinstance(options[0], dict) else {}

    calls = _contracts(block.get("calls"))
    puts = _contracts(block.get("puts"))
    quote = result.get("quote")
    price = quote.get("regularMarketPrice") if isinstance(quote, dict) else None
    underlying_price = _positive_number(price)
    # Determine ATM from the complete ladder, before the output-row cap.
    strikes = {
        strike
        for rows in (block.get("calls"), block.get("puts"))
        if isinstance(rows, list)
        for row in rows
        if isinstance(row, dict)
        if (strike := _positive_number(row.get("strike"))) is not None
    }
    atm_strike = (
        min(strikes, key=lambda strike: (abs(strike - underlying_price), strike))
        if underlying_price is not None and strikes else None
    )

    data = {
        "ticker": ticker,
        "underlying_price": underlying_price,
        "atm_strike": atm_strike,
        "expiration": block.get("expirationDate"),
        "expirations": expirations,
        "calls_count": len(calls),
        "puts_count": len(puts),
        "calls": calls,
        "puts": puts,
    }
    return json.dumps(
        {"ok": True, "market": "us", "source": "yahoo", "data": data},
        ensure_ascii=False,
    )


def _positive_number(value: Any) -> float | None:
    """Validate a source number without guessing missing values.

    Args:
        value: The price or strike supplied by the data source.

    Returns:
        A finite positive number, or None for missing or malformed input.
    """
    if isinstance(value, bool) or not isinstance(value, (int, float)):
        return None
    return float(value) if math.isfinite(value) and value > 0 else None


def _contracts(raw: Any) -> List[Dict[str, Any]]:
    """Normalize a Yahoo calls/puts array into capped snake_case rows."""
    if not isinstance(raw, list):
        return []
    rows: List[Dict[str, Any]] = []
    for entry in raw[:_MAX_CONTRACTS_PER_SIDE]:
        if not isinstance(entry, dict):
            continue
        rows.append(
            {our_key: entry.get(yahoo_key) for yahoo_key, our_key in _CONTRACT_FIELDS}
        )
    return rows


def _error(message: str) -> str:
    """Render a failure envelope as a JSON string."""
    return json.dumps({"ok": False, "error": message}, ensure_ascii=False)