# options_quant_engine

A professional, modular, explainable, and production-ready options quant engine with a clean, extensible architecture for standalone deployment.

## What This Engine Does

- Ingests market/macro/rate data from multiple pluggable adapters
- Uses configurable source priority and fallback logic per asset
- Engineers economically meaningful features through a registry-based pipeline
- Detects interpretable market regimes
- Generates directional and relative-value signals
- Separates signal strength from confidence
- Applies risk overlays and outputs action recommendations
- Supports evaluation and realistic backtest scaffolding
- Exports integration hooks for cross-engine multi-asset platforms

## Underlying Universe

Primary INR pairs:

- USDINR
- EURINR
- GBPINR
- JPYINR

Secondary G10 pairs:

- EURUSD
- GBPUSD
- USDJPY
- AUDUSD
- USDCAD
- USDCHF

## Repository Structure

- options_quant_engine/ingestion: adapters + fallback router
- options_quant_engine/preprocessing: data cleaning/alignment
- options_quant_engine/features: registry + modular feature pipeline
- options_quant_engine/regime: explainable regime detection
- options_quant_engine/models: model scoring and extension points
- options_quant_engine/signals: directional/RV signal + confidence engine
- options_quant_engine/risk: risk overlays and action mapping
- options_quant_engine/evaluation: signal quality diagnostics
- options_quant_engine/backtest: no-lookahead pair/portfolio simulation
- options_quant_engine/outputs: machine-readable + trader-readable payloads
- options_quant_engine/integration: cross-engine score exports
- config: YAML-driven behavior
- scripts: runnable examples
- tests: unit tests
- examples: sample payloads and run artifacts

## Data Adapter Architecture

Base interface:

```python
class BaseDataAdapter:
    def fetch_price_data(self, asset, start, end):
        pass

    def fetch_macro_data(self, key, start, end):
        pass

    def fetch_rate_data(self, asset, start, end):
        pass

    def health_check(self):
        pass
```

Included adapters:

- BreezeAdapter (ICICI Breeze)
- ZerodhaAdapter (optional via config)
- NSEAdapter
- RBIAdapter
- FreeFXAdapter
- MockAdapter

Live API stubs are environment-driven and include strict timeout/retry logic:

- OQE_HTTP_TIMEOUT_SEC
- OQE_HTTP_MAX_ATTEMPTS
- OQE_HTTP_BACKOFF_SEC
- BREEZE_LIVE_ENABLED, BREEZE_BASE_URL, BREEZE_API_KEY, BREEZE_API_SECRET
- ZERODHA_LIVE_ENABLED, ZERODHA_BASE_URL, ZERODHA_API_KEY, ZERODHA_ACCESS_TOKEN
- NSE_LIVE_ENABLED, NSE_BASE_URL
- RBI_LIVE_ENABLED, RBI_BASE_URL

## Config-Driven Files

- config/universe.yaml
- config/data_sources.yaml
- config/features.yaml
- config/regimes.yaml
- config/models.yaml
- config/risk.yaml
- config/output.yaml

## Quickstart

1. Create and activate a Python 3.10+ environment.
1. Install package and dev dependencies:

```bash
pip install -e .[dev]
```

1. Run tests:

```bash
pytest
```

1. Run engine example:

```bash
python scripts/run_engine.py
```

The script saves artifacts to examples/runs.

## Signal Output Schema

Each signal includes:

- direction
- signal strength
- confidence (separate module)
- regime context
- expected volatility
- key drivers
- risk flags
- recommended action
- position sizing multiplier

See examples/sample_signal.json.

## Relative Value Spread Model

Relative-value signal generation uses a true spread framework:

- explicit hedge ratio estimation from aligned log prices
- spread z-score signal component
- pair-level momentum and carry differentials
- expected spread volatility and long/short leg assignment

The output includes `hedge_ratio` and `spread_zscore` in RV payloads.

## CI

GitHub Actions workflow: `.github/workflows/ci.yml`

- ruff lint checks
- pytest execution
- sample run generation
- artifact upload of `examples/runs/*.json`

## Build Phases Coverage

Phase 1:

- repo structure
- config system
- ingestion + preprocessing
- basic features

Phase 2:

- regime detection
- signal engine
- confidence engine
- outputs

Phase 3:

- risk layer
- evaluation framework
- backtesting scaffolding

Phase 4 starter:

- model extension hooks
- integration hooks
- tests
- docs

## Notes

- No credentials are hardcoded.
- Live adapter wiring is stubbed with production-style retries/timeouts and env credentials.
- Mock pathways remain default for deterministic testing and offline development.