Metadata-Version: 2.4
Name: qfin-derivatives
Version: 0.1.0
Summary: Python library for equity derivatives pricing, volatility, and risk analytics.
Project-URL: Homepage, https://github.com/siddharthskulkarni/derivatives
Project-URL: Issues, https://github.com/siddharthskulkarni/derivatives/issues
Author: Siddharth Kulkarni
License-Expression: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.10
Provides-Extra: data
Requires-Dist: pandas>=2.0; extra == 'data'
Requires-Dist: pyarrow>=14.0; extra == 'data'
Requires-Dist: python-dotenv>=1.0; extra == 'data'
Requires-Dist: qfin-datasets[data]>=0.1.0; extra == 'data'
Requires-Dist: requests>=2.31; extra == 'data'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: models
Requires-Dist: arch>=6.0; extra == 'models'
Provides-Extra: tableau
Requires-Dist: pandas>=2.0; extra == 'tableau'
Requires-Dist: pantab>=4.0; extra == 'tableau'
Requires-Dist: pyarrow>=14.0; extra == 'tableau'
Provides-Extra: viz
Requires-Dist: dash>=2.0; extra == 'viz'
Requires-Dist: ipykernel>=6.0; extra == 'viz'
Requires-Dist: jupyter-dash>=0.4; extra == 'viz'
Requires-Dist: matplotlib>=3.8; extra == 'viz'
Requires-Dist: pandas>=2.0; extra == 'viz'
Requires-Dist: plotly>=5.0; extra == 'viz'
Requires-Dist: seaborn>=0.13; extra == 'viz'
Description-Content-Type: text/markdown

# derivatives

Python library for **equity derivatives pricing and risk analytics**: GARCH volatility estimation, Black–Scholes pricing, Greeks, and implied-volatility surface construction. Part of the QFIN workspace alongside `fixed-income`, `equity`, and `risk`.

## Roadmap

| Phase | Scope | Status |
|-------|-------|--------|
| I | Repo skeleton, package layout, CI scripts | Done |
| II | Dataset management (via `datasets` package + domain chain builder) | Done |
| III | Models (GARCH, Black–Scholes, Greeks, IV surface) | Done |
| IV | Charts, Dash dashboards, Tableau exports | **Done** |

## Capabilities (target)

| Capability | Status |
|------------|--------|
| GARCH(1,1) volatility forecast | Implemented (`[models]` extra) |
| Black–Scholes European pricer | Implemented |
| Analytical Greeks (Δ, Γ, Θ, ν, ρ) | Implemented |
| IV surface via BS inversion | Implemented |
| Massive.com data ingest (stocks, options, Treasury yields) | Implemented (`[data]` extra, backed by [`datasets`](../datasets/)) |
| Plotly Dash risk monitor | Implemented (`[viz]` extra) |
| Tableau Hyper/CSV exports + workbook templates | Implemented (`[tableau]` extra) |

## Install

```bash
python3 -m pip install -e .
```

Optional extras:

```bash
python3 -m pip install -e '.[data]'      # datasets[data], requests, pandas, python-dotenv
python3 -m pip install -e '.[models]'    # arch (GARCH)
python3 -m pip install -e '.[viz]'       # plotly, dash, matplotlib, …
python3 -m pip install -e '.[tableau]'   # pyarrow, pantab
python3 -m pip install -e '.[dev]'       # pytest, ruff, build
python3 -m pip install -e '.[dev,data,models,viz,tableau]'
```

## Quickstart

Runnable end-to-end script (from repo root, with `.env` set):

```bash
conda activate fixed_income   # or your env with derivatives installed
cd derivatives
python3 -m pip install -e '.[data,models,viz,tableau]'

python3 scripts/quickstart.py                    # full pipeline (~12 API calls)
python3 scripts/quickstart.py --skip-options     # stock + treasury only (~2 calls)
python3 scripts/quickstart.py --serve            # + Dash risk monitor
```

```python
from datetime import date
from derivatives.data import (
    CachedDataSource,
    MassiveStockHistorySource,
    MassiveTreasuryYieldsSource,
    load_project_dotenv,
)

load_project_dotenv()
stock = CachedDataSource(MassiveStockHistorySource("SPY")).fetch(as_of=date.today())
treasury = CachedDataSource(MassiveTreasuryYieldsSource()).fetch(as_of=date.today())
print(stock.spot(), treasury.latest_point().yield_10_year)
```

Price a chain with GARCH + Black–Scholes:

```python
from derivatives import price_option_chain
from derivatives.data import MassiveOptionChainSource

chain = MassiveOptionChainSource("SPY", max_contracts=20).fetch(as_of=date.today())
result = price_option_chain(chain, stock, treasury)
print(result.garch_sigma, len(result.surface.points))
```

Ingest to Parquet:

```bash
python3 scripts/ingest_market_data.py --as-of 2026-06-06 --underlying SPY --skip-options
```

### Dash risk monitor

```python
from derivatives.dashboards import create_risk_monitor_app

app = create_risk_monitor_app(result, chain, stock)
app.run(debug=True)
```

### Tableau export

```python
from derivatives.dashboards import export_tableau_bundle

export_tableau_bundle(result, chain, stock)
# → data/processed/{as_of}/tableau/*.hyper and *.csv
```

## Project layout

```
derivatives/
├── derivatives/          # Python package
│   ├── data/             # DataSource adapters, cache, types
│   ├── models/           # GARCH, Black–Scholes, IV surface
│   ├── charts/           # Plotly figures
│   └── dashboards/       # Dash apps + Tableau exports
├── data/
│   ├── raw/              # Manual CSV fallbacks (gitignored)
│   └── processed/        # Parquet snapshots (gitignored)
├── scripts/              # ingest_market_data.py, build scripts
├── tests/
├── docs/
└── examples/             # Jupyter notebooks (Phase IV)
```

## Development

```bash
bash scripts/build_test.sh
```

Data access details: [docs/data_access.md](docs/data_access.md).
