# 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:

```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.