Initial commit: fx_quant_engine and options_quant_engine scaffold

README.md

@@ -0,0 +1,193 @@
+# fx_quant_engine
+
+A professional, modular, explainable, and production-ready starter repository for an FX quant signal engine focused on India-first constraints with global extensibility.
+
+## What This Engine Does
+
+- Ingests FX/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 FX 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
+
+## Asset Universe
+
+Primary INR pairs:
+
+- USDINR
+- EURINR
+- GBPINR
+- JPYINR
+
+Secondary G10 pairs:
+
+- EURUSD
+- GBPUSD
+- USDJPY
+- AUDUSD
+- USDCAD
+- USDCHF
+
+## Repository Structure
+
+- fx_quant_engine/ingestion: adapters + fallback router
+- fx_quant_engine/preprocessing: data cleaning/alignment
+- fx_quant_engine/features: registry + modular feature pipeline
+- fx_quant_engine/regime: explainable regime detection
+- fx_quant_engine/models: model scoring and extension points
+- fx_quant_engine/signals: directional/RV signal + confidence engine
+- fx_quant_engine/risk: risk overlays and action mapping
+- fx_quant_engine/evaluation: signal quality diagnostics
+- fx_quant_engine/backtest: no-lookahead pair/portfolio simulation
+- fx_quant_engine/outputs: machine-readable + trader-readable payloads
+- fx_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 wiring uses strict vendor-specific parsers with schema validation and supports:
+
+- FXE_HTTP_TIMEOUT_SEC
+- FXE_HTTP_MAX_ATTEMPTS
+- FXE_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
+
+Router safeguards include adapter-level circuit breakers and source cooldown windows.
+
+## 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 generation uses:
+
+- explicit hedge ratio estimation from aligned log prices
+- spread z-score component
+- pair-level momentum and carry differentials
+- risk-overlayed RV signal output with `hedge_ratio` and `spread_zscore`
+
+## Release Workflow
+
+Automated release workflow is available in `.github/workflows/release.yml`.
+
+- triggers on version tags like `v0.1.0`
+- builds wheel + source distribution
+- validates artifacts via twine
+- publishes GitHub release assets with retention policy
+
+## 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 API integration can be added by replacing adapter internals while preserving interfaces.
+- Mock pathways are included for deterministic testing and offline development.