Metadata-Version: 2.4
Name: optionxray
Version: 0.1.0
Summary: Option pricing and explanation engine with Black-Scholes analytics
Author: OptionXRay Contributors
License: MIT License
        
        Copyright (c) 2026 OptionXRay Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/optionxray/optionxray
Project-URL: Repository, https://github.com/optionxray/optionxray
Project-URL: Issues, https://github.com/optionxray/optionxray/issues
Keywords: options,derivatives,black-scholes,greeks,finance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: pandas>=1.5
Requires-Dist: scipy>=1.9
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# OptionXRay

OptionXRay is a production-ready Python package for pricing vanilla European options and explaining **why** the market price is what it is. It combines Black–Scholes pricing with implied volatility, Greeks, scenario analysis, and a plain-English report.

## Why options trade where they trade

Option prices are driven by the probability-weighted payoff of the option, discounted back to today. In practice, markets quote **implied volatility** rather than price: traders back out the volatility that makes a model price match the market price, then use that volatility as a quoting language across strikes and maturities.

Key drivers of price include:
- **Spot price**: higher spot makes calls more valuable and puts less valuable.
- **Volatility**: higher volatility increases the chance of large moves, usually raising both call and put prices.
- **Time**: more time generally increases option value because more paths can end in-the-money.
- **Rates and dividends**: the discounted value of the strike and the carry on the underlying.

## Intrinsic vs extrinsic value

Intrinsic value is the immediate payoff if exercised today (e.g., `max(S-K, 0)` for a call). Extrinsic value (time value) is everything beyond intrinsic value and reflects volatility, time, and rates. This package decomposes both.

## What the Greeks mean

- **Delta**: sensitivity to spot.
- **Gamma**: curvature of delta; higher gamma means delta changes quickly.
- **Vega**: sensitivity to volatility.
- **Theta**: sensitivity to time decay.
- **Rho**: sensitivity to interest rates.

Greeks tell you which drivers matter most in the current state of the world, and OptionXRay highlights the largest ones.

## Why Black–Scholes is used

Black–Scholes is not a perfect model, but it is a standard quoting language. Market participants use it to quote implied volatility surfaces so that pricing and risk can be compared across strikes and maturities.

## Installation

```bash
pip install optionxray
```

## Quickstart

```python
from optionxray import Market, Option, XRay

option = Option(spot=100, strike=105, maturity=0.5, rate=0.01, dividend=0.0, option_type="call")
market = Market(market_price=4.2)

scenarios = [
    {"name": "Spot +2%", "dS_pct": 0.02},
    {"name": "Vol +3 pts", "dvol_abs": 0.03},
    {"name": "Rates +50bp", "dr_abs": 0.005},
    {"name": "Time +10d", "dT_days": 10},
]

xray = XRay(option, market)
result = xray.run(scenarios=scenarios)

print(result.summary_text)
print(result.scenarios_df)
```

Example output (truncated):

```
OptionXRay Report
=
Option details:
- spot: 100
- strike: 105
- maturity: 0.5
- rate: 0.01
- dividend: 0.0
- type: call

Theoretical price (BS): 4.1876
Market price: 4.2000
Implied volatility: 24.91%
Intrinsic value: 0.0000
Extrinsic value: 4.1876

Key drivers (largest Greeks):
- vega increases price by 12.0810 per unit move
- delta increases price by 0.4295 per unit move
- theta decreases price by 4.2601 per unit move

Scenario highlights:
- Vol +3 pts: increase of 0.3662 (price 4.5538)
- Spot +2%: increase of 0.8453 (price 5.0329)
- Time +10d: decrease of -0.1064 (price 4.0812)
```

## API Overview

### Functional API

```python
from optionxray.bs import price_bs
from optionxray.iv import implied_vol_bs
from optionxray.greeks import greeks_bs
from optionxray.instruments import Option

option = Option(spot=100, strike=100, maturity=1.0, rate=0.02, dividend=0.01, option_type="call")
price = price_bs(option, vol=0.2)
ivs = implied_vol_bs(option, market_price=price)
print(ivs.implied_vol)
print(greeks_bs(option, vol=0.2))
```

### Scenario format

Each scenario is a dict with keys:
- `name` (required)
- `dS_pct` or `dS_abs`
- `dvol_abs` (vol points) or `dvol_pct`
- `dr_abs` (absolute rate change)
- `dq_abs` (absolute dividend yield change)
- `dT_days` (time passes forward)

## Development

Run tests with:

```bash
pytest
```

## License

MIT
