Metadata-Version: 2.4
Name: brain-options
Version: 0.1.0
Summary: Options-trading alpha generation engine (implied vol, skew, term structure, breakeven) for WorldQuant BRAIN.
Author: Xtley001
License-Expression: MIT
Project-URL: Homepage, https://github.com/Xtley001/brain-libraries
Project-URL: Repository, https://github.com/Xtley001/brain-libraries
Project-URL: Documentation, https://github.com/Xtley001/brain-libraries
Project-URL: Bug Tracker, https://github.com/Xtley001/brain-libraries/issues
Keywords: worldquant,brain,alpha,quantitative-finance,options-trading,implied-volatility,volatility-skew,algorithmic-trading,derivatives
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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 :: Investment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: brain-alpha-core>=0.1.0
Requires-Dist: brain-store>=0.1.0
Requires-Dist: brain-decorrelator>=0.1.0
Requires-Dist: requests>=2.31
Requires-Dist: numpy>=1.26
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: sim
Requires-Dist: wqb>=0.2.5; extra == "sim"
Dynamic: license-file

# brain-options

Options-trading alpha generation engine (implied vol, skew, term structure, breakeven) for WorldQuant BRAIN.

[![CI](https://img.shields.io/github/actions/workflow/status/Xtley001/brain-libraries/ci.yml?branch=main)](https://github.com/Xtley001/brain-libraries/actions)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../LICENSE)
[![PyPI](https://img.shields.io/pypi/v/brain-options)](https://pypi.org/project/brain-options/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

`brain_options` generates institutional quantitative alphas on WorldQuant BRAIN options datasets (`option8`, `option9`, ValueScore: 6.0). It codifies 30 mathematical archetypes across implied volatility surfaces, skew, term structure, and straddle breakevens into vector-neutral Fast Expressions with automated AST deduplication. For institutional literature citations and surface derivations, see the [whitepaper](./docs/whitepaper.md).

## Installation

```bash
pip install brain-options
```

## Quickstart

```python
from brain_options import OptionsAlphaEngine

engine = OptionsAlphaEngine()

# Generate 5 vector-neutral options alpha candidates
candidates = engine.generate_candidates(count=5)

for cand in candidates:
    print(f"[{cand.tags}] {cand.expression}\n")
```

## Core Options Archetypes

| Archetype | Institutional Literature | Formula Concept | ValueScore |
|---|---|---|:---:|
| **Volatility Smirk** | Xing, Zhang & Zhao (2010) | OTM Put IV minus ATM Call IV captures informed downside hedging | **6.0** |
| **Term Structure Slope** | An, Ang, Bali & Cakici (2014) | Slope between 30d and 90d implied volatility tracks event risk pricing | **6.0** |
| **Variance Risk Premium** | Sinclair (2010), Bali (2008) | Implied volatility minus realized historical volatility (IV - RV) | **6.0** |
| **Breakeven Drift** | Sinclair (2010) | Forward price divergence from straddle put breakeven levels | **6.0** |

## Architecture

```
brain_options/
├── brain_options/
│   ├── __init__.py        # Public re-exports (OptionsAlphaEngine, OptionCandidate)
│   ├── data/
│   │   └── catalog.json   # Live BRAIN options field catalog
│   ├── catalog.py         # OptionsCatalog field groupings & loader
│   ├── archetypes.py      # Quantitative options strategy descriptors
│   ├── dedup.py           # AST expression deduplicator (delegates to brain_core)
│   ├── generator.py       # Candidate generation engine
│   ├── py.typed           # PEP 561 typing marker
│   └── strategies/        # Modular strategy families (skew, surface, term_structure)
├── tests/                 # Unit tests covering catalog, engine, filter, candidate
└── docs/
    ├── API.md             # Complete API specification
    └── whitepaper.md      # Quantitative options theory & surface formulations
```

## Testing

```bash
pytest tests/ -v
```

## Security

Report vulnerabilities per [SECURITY.md](SECURITY.md).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

## License

Released under the [MIT License](../LICENSE). Maintained by [Xtley001](https://github.com/Xtley001).
