mirror of
https://github.com/QuantEngines/fx_quant_engine.git
synced 2026-07-27 18:37:47 +00:00
Pramit Dutta
194 lines
4.3 KiB
Markdown
194 lines
4.3 KiB
Markdown
# 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.
|