"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Agent tool for deterministic multi-leg option payoff analysis."""
from __future__ import annotations
import json
import math
from typing import Any
import numpy as np
from backtest.options_payoff import OptionLeg, expiry_payoff, scenario_grid
from src.agent.tools import BaseTool
_MAX_LEGS = 20
_MIN_SPOT_POINTS = 21
_MAX_SPOT_POINTS = 501
_DEFAULT_SPOT_POINTS = 121
_MAX_IV_SCENARIOS = 9
class OptionsPayoffTool(BaseTool):
"""Analyze expiry payoff and spot/IV scenarios for an option strategy."""
name = "options_payoff"
description = (
"Analyze a European multi-leg option strategy using deterministic "
"piecewise-linear expiry math and Black-Scholes spot/IV scenarios. "
"Returns entry debit/credit and commission, analytic breakevens, "
"bounded or unbounded max profit/loss, an expiry payoff curve, and a "
"scenario P&L matrix. Research only; does not place orders."
)
repeatable = True
parameters = {
"type": "object",
"properties": {
"legs": {
"type": "array",
"minItems": 1,
"maxItems": _MAX_LEGS,
"description": (
"Signed option legs. Positive qty is long; negative qty is "
"short. Omit premium to price that leg with Black-Scholes."
),
"items": {
"type": "object",
"properties": {
"option_type": {"type": "string", "enum": ["call", "put"]},
"strike": {"type": "number", "exclusiveMinimum": 0},
"qty": {"type": "integer"},
"premium": {
"type": "number",
"minimum": 0,
"description": "Optional per-share entry premium.",
},
},
"required": ["option_type", "strike", "qty"],
},
},
"entry_spot": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Underlying spot at entry.",
},
"expiry_days": {
"type": "number",
"minimum": 0,
"description": "Calendar days remaining to expiry.",
},
"risk_free_rate": {
"type": "number",
"default": 0.05,
"description": "Annual continuously compounded risk-free rate.",
},
"volatility": {
"type": "number",
"exclusiveMinimum": 0,
"default": 0.3,
"description": "Annualized entry volatility, e.g. 0.3 for 30%.",
},
"multiplier": {
"type": "number",
"exclusiveMinimum": 0,
"default": 1.0,
"description": "Currency multiplier per option price unit.",
},
"commission_rate": {
"type": "number",
"minimum": 0,
"exclusiveMaximum": 1,
"default": 0.001,
"description": "Entry commission fraction, aligned with the backtest engine.",
},
"spot_min": {
"type": "number",
"minimum": 0,
"description": "Optional lower chart/scenario spot bound.",
},
"spot_max": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Optional upper chart/scenario spot bound.",
},
"spot_points": {
"type": "integer",
"minimum": _MIN_SPOT_POINTS,
"maximum": _MAX_SPOT_POINTS,
"default": _DEFAULT_SPOT_POINTS,
},
"scenario_iv_values": {
"type": "array",
"minItems": 1,
"maxItems": _MAX_IV_SCENARIOS,
"items": {"type": "number", "exclusiveMinimum": 0},
"description": (
"Optional annualized IV scenarios. Defaults to 50%, 75%, 100%, 125%, and 150% of entry volatility."
),
},
},
"required": ["legs", "entry_spot", "expiry_days"],
}
def execute(self, **kwargs: Any) -> str:
"""Run payoff and scenario analysis.
Args:
**kwargs: Inputs described by :attr:`parameters`.
Returns:
JSON envelope with summary, expiry curve, scenario grid, and model
limitations. Invalid inputs return a JSON error envelope.
"""
try:
legs = _coerce_legs(kwargs.get("legs"))
entry_spot = _required_float(kwargs, "entry_spot")
expiry_days = _required_float(kwargs, "expiry_days")
rate = _optional_float(kwargs, "risk_free_rate", 0.05)
volatility = _optional_float(kwargs, "volatility", 0.3)
multiplier = _optional_float(kwargs, "multiplier", 1.0)
commission_rate = _optional_float(kwargs, "commission_rate", 0.001)
spot_points = _spot_points(kwargs.get("spot_points"))
spot_min, spot_max = _spot_bounds(kwargs, legs, entry_spot)
iv_values = _scenario_ivs(kwargs.get("scenario_iv_values"), volatility)
spots = np.linspace(spot_min, spot_max, spot_points)
time_to_expiry = expiry_days / 365.0
report = expiry_payoff(
legs,
spots,
entry_spot=entry_spot,
time_to_expiry=time_to_expiry,
rate=rate,
iv=volatility,
multiplier=multiplier,
commission_rate=commission_rate,
)
scenarios = scenario_grid(
legs,
spots,
iv_values,
entry_spot=entry_spot,
time_to_expiry=time_to_expiry,
rate=rate,
entry_iv=volatility,
multiplier=multiplier,
commission_rate=commission_rate,
)
except (KeyError, TypeError, ValueError, OverflowError) as exc:
return _error(str(exc))
payload = {
"status": "ok",
"tool": self.name,
"inputs": {
"legs": [
{
"option_type": leg.option_type,
"strike": leg.strike,
"qty": leg.qty,
"premium": leg.premium,
}
for leg in legs
],
"entry_spot": entry_spot,
"expiry_days": expiry_days,
"risk_free_rate": rate,
"volatility": volatility,
"multiplier": multiplier,
"commission_rate": commission_rate,
},
"summary": {
"net_premium": _rounded(report.net_premium),
"entry_commission": _rounded(report.entry_commission),
"entry_cost": _rounded(report.entry_cost),
"entry_side": (
"flat" if abs(report.entry_cost) <= 1e-12 else "debit" if report.entry_cost > 0 else "credit"
),
"breakevens": [_rounded(value) for value in report.breakevens],
"breakeven_intervals": [
{
"start": _rounded(start),
"end": None if end is None else _rounded(end),
}
for start, end in report.breakeven_intervals
],
"max_profit": (None if report.profit_unbounded else _rounded(report.max_profit)),
"max_loss": (None if report.loss_unbounded else _rounded(report.max_loss)),
"profit_unbounded": report.profit_unbounded,
"loss_unbounded": report.loss_unbounded,
},
"expiry_curve": {
"spot": _rounded_array(report.spot_grid),
"pnl": _rounded_array(report.payoff),
},
"scenario_grid": {
"iv_values": _rounded_array(iv_values),
"spot": _rounded_array(report.spot_grid),
"pnl": [_rounded_array(row) for row in np.asarray(scenarios, dtype=float)],
},
"limitations": [
"European Black-Scholes marks with constant rate and volatility per scenario.",
"No dividends, early exercise, assignment, slippage, or margin model.",
"Scenario P&L is mark-to-market and does not deduct a hypothetical exit commission.",
],
}
try:
return json.dumps(payload, ensure_ascii=False, allow_nan=False)
except ValueError as exc:
# Extreme finite inputs (e.g. a ~1e308 multiplier) overflow to inf
# in the results; report that instead of raising out of execute().
return _error(f"non-serializable numeric result: {exc}")
def _coerce_legs(raw: Any) -> list[OptionLeg]:
"""Parse and validate raw JSON-style leg objects."""
if not isinstance(raw, list) or not raw:
raise ValueError("legs must be a non-empty array")
if len(raw) > _MAX_LEGS:
raise ValueError(f"legs may contain at most {_MAX_LEGS} entries")
legs: list[OptionLeg] = []
for index, item in enumerate(raw):
if not isinstance(item, dict):
raise ValueError(f"legs[{index}] must be an object")
option_type = str(item.get("option_type") or "").strip().lower()
try:
strike = float(item["strike"])
raw_qty = item["qty"]
qty_number = float(raw_qty)
except (KeyError, TypeError, ValueError, OverflowError) as exc:
raise ValueError(f"legs[{index}] has invalid strike or qty: {exc}") from exc
if isinstance(raw_qty, bool) or not qty_number.is_integer():
raise ValueError(f"legs[{index}].qty must be a non-zero integer")
qty = int(qty_number)
raw_premium = item.get("premium")
try:
premium = None if raw_premium is None else float(raw_premium)
except (TypeError, ValueError, OverflowError) as exc:
raise ValueError(f"legs[{index}].premium must be numeric or null") from exc
legs.append(OptionLeg(option_type, strike, qty, premium))
return legs
def _required_float(kwargs: dict[str, Any], name: str) -> float:
"""Read a required finite float."""
if name not in kwargs or kwargs[name] is None or kwargs[name] == "":
raise ValueError(f"{name} is required")
try:
value = float(kwargs[name])
except (TypeError, ValueError, OverflowError) as exc:
raise ValueError(f"{name} must be numeric") from exc
if not math.isfinite(value):
raise ValueError(f"{name} must be finite")
return value
def _optional_float(kwargs: dict[str, Any], name: str, default: float) -> float:
"""Read an optional finite float, treating null and empty text as omitted."""
raw = kwargs.get(name)
if raw is None or raw == "":
return default
try:
value = float(raw)
except (TypeError, ValueError, OverflowError) as exc:
raise ValueError(f"{name} must be numeric") from exc
if not math.isfinite(value):
raise ValueError(f"{name} must be finite")
return value
def _spot_points(raw: Any) -> int:
"""Validate the bounded display-grid size."""
if raw is None or raw == "":
return _DEFAULT_SPOT_POINTS
if isinstance(raw, bool):
raise ValueError("spot_points must be an integer")
try:
numeric = float(raw)
except (TypeError, ValueError, OverflowError) as exc:
raise ValueError("spot_points must be an integer") from exc
if not math.isfinite(numeric) or not numeric.is_integer():
raise ValueError("spot_points must be an integer")
points = int(numeric)
if not _MIN_SPOT_POINTS <= points <= _MAX_SPOT_POINTS:
raise ValueError(f"spot_points must be between {_MIN_SPOT_POINTS} and {_MAX_SPOT_POINTS}")
return points
def _spot_bounds(kwargs: dict[str, Any], legs: list[OptionLeg], entry_spot: float) -> tuple[float, float]:
"""Resolve explicit chart bounds or safe defaults covering every strike."""
reference = [entry_spot, *(leg.strike for leg in legs)]
default_min = max(min(reference) * 0.5, 0.0)
default_max = max(reference) * 1.5
spot_min = _optional_float(kwargs, "spot_min", default_min)
spot_max = _optional_float(kwargs, "spot_max", default_max)
if spot_min < 0:
raise ValueError("spot_min must be non-negative")
if spot_max <= spot_min:
raise ValueError("spot_max must be greater than spot_min")
return spot_min, spot_max
def _scenario_ivs(raw: Any, entry_iv: float) -> np.ndarray:
"""Resolve bounded explicit IV scenarios or the skill's five defaults."""
if raw is None:
values = [
entry_iv * 0.5,
entry_iv * 0.75,
entry_iv,
entry_iv * 1.25,
entry_iv * 1.5,
]
else:
if not isinstance(raw, list) or not raw:
raise ValueError("scenario_iv_values must be a non-empty array")
if len(raw) > _MAX_IV_SCENARIOS:
raise ValueError(f"scenario_iv_values may contain at most {_MAX_IV_SCENARIOS} entries")
try:
values = [float(value) for value in raw]
except (TypeError, ValueError, OverflowError) as exc:
raise ValueError("scenario_iv_values must contain numbers") from exc
array = np.asarray(values, dtype=float)
if not np.isfinite(array).all() or (array <= 0).any():
raise ValueError("scenario_iv_values must contain positive finite values")
return array
def _rounded(value: float) -> float:
"""Round a finite scalar for stable, compact JSON."""
return round(float(value), 6)
def _rounded_array(values: np.ndarray) -> list[float]:
"""Round a numeric array for stable, compact JSON."""
return [round(float(value), 6) for value in np.asarray(values).tolist()]
def _error(message: str) -> str:
"""Build a stable error envelope."""
return json.dumps(
{"status": "error", "tool": "options_payoff", "error": message},
ensure_ascii=False,
)