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

• src/fx_quant_engine/ingestion: adapters + fallback router
• src/fx_quant_engine/preprocessing: data cleaning/alignment
• src/fx_quant_engine/features: registry + modular feature pipeline
• src/fx_quant_engine/regime: explainable regime detection
• src/fx_quant_engine/models: model scoring and extension points
• src/fx_quant_engine/signals: directional/RV signal + confidence engine
• src/fx_quant_engine/risk: risk overlays and action mapping
• src/fx_quant_engine/evaluation: signal quality diagnostics
• src/fx_quant_engine/backtest: no-lookahead pair/portfolio simulation
• src/fx_quant_engine/outputs: machine-readable + trader-readable payloads
• src/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:

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.
2. Install package and dev dependencies:

pip install -e '.[dev]'

1. Run tests:

pytest

1. Run engine example:

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.