finrix 1.0.0__tar.gz

finrix-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 carnoba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

finrix-1.0.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: finrix
+Version: 1.0.0
+Summary: FINRIX Quantitative Trading Terminal — XAUUSD macro forecast engine with Rich CLI
+Requires-Python: <3.13,>=3.11
+License-File: LICENSE
+Requires-Dist: modal==0.73.0
+Requires-Dist: neuralforecast==1.7.5
+Requires-Dist: pyfredapi==0.10.2
+Requires-Dist: transformers==4.46.3
+Requires-Dist: torch==2.5.1
+Requires-Dist: pandas==2.2.3
+Requires-Dist: numpy==2.1.3
+Requires-Dist: scikit-learn==1.5.2
+Requires-Dist: yfinance==0.2.48
+Requires-Dist: requests==2.32.3
+Requires-Dist: python-dotenv==1.0.1
+Requires-Dist: rich==13.9.4
+Requires-Dist: questionary==2.0.1
+Requires-Dist: InquirerPy==0.3.4
+Dynamic: license-file

finrix-1.0.0/README.md

@@ -0,0 +1,192 @@
+# FINRIX XAUUSD Quant Trading Terminal
+
+> **Status: Research Prototype / Quantitative Framework.** FINRIX supports
+> reproducible market research, forecasting, and backtesting. It is not
+> investment advice and does not execute live orders without a separately
+> installed and explicitly authorized broker bridge.
+
+[![CI Status](https://img.shields.io/github/actions/workflow/status/carnoba/trading-prediction/.github/workflows/ci.yml?label=CI&logo=github&color=blue)](https://github.com/carnoba/trading-prediction/actions/workflows/ci.yml)
+[![Pytest Pass](https://img.shields.io/badge/pytest-207%20passed-brightgreen.svg)](https://github.com/carnoba/trading-prediction/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-3100-rc1/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Execution: Local CPU | Modal A10G GPU](https://img.shields.io/badge/Execution-Local%20CPU%20%7C%20Modal%20A10G%20GPU-orange.svg)](macro_forecast_engine/)
+[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Zero-Trust Audit PASSED](https://img.shields.io/badge/Audit-PASSED-brightgreen.svg)](FINRIX_SECURITY_AND_QA_AUDIT_REPORT.md)
+[![14-Strategy Engine](https://img.shields.io/badge/Strategies-14-brightgreen.svg)](macro_forecast_engine/)
+
+
+
+
+
+https://github.com/user-attachments/assets/b600ad35-9752-46c7-a912-12deb9714708
+
+
+
+
+
+
+## One-Line Execution
+
+Run the full FINRIX terminal directly from command line:
+
+```bash
+finrix
+```
+
+Or launch the Rich/questionary terminal:
+
+```bash
+python app.py
+```
+
+The System Settings menu controls Modal A10G vs local CPU, default equity, and risk per trade -- all forecast actions use saved values automatically.
+
+## Core Architecture & Key Features
+
+### Dual-Path Execution Engine
+
+- **Local CPU** -- Lightweight drift & baseline execution, runs instantly on any machine
+- **Modal A10G Cloud GPU** -- NeuralForecast TFT deep learning, 100,000-path CUDA Monte Carlo, CUDA-accelerated quantile regression
+
+### Quantile Forecasting Envelope
+
+Monotonic price corridors $q_{10} \le q_{50} \le q_{90}$ with dynamic volatility decay across daily (30 business days), monthly (22 business days), and yearly (252 business days) horizons.
+
+### Dynamic Equity-Based Position Sizing
+
+Real-time dollar risk math with standardized Gold pip sizing, pip-based
+stop-loss/take-profit calculation, equity compounding, transaction-cost-aware
+trade sizing, and fractional-Kelly allocation across 14 strategies.
+
+### Genuine Trade-Based Backtesting
+
+The timemachine engine simulates signal entry, open-position tracking,
+stop-loss/take-profit exits, signal reversal, 1.5-pip spread, and slippage.
+Metrics use closed trades and the dollar equity curve rather than static
+per-bar percentage returns.
+
+### 14-Strategy Backtesting & Parameter Engine
+
+All strategies persist to `data/finrix_indicator_params.json`:
+
+| Strategy | Indicators |
+|----------|------------|
+| SMC Fair Value Gap (FVG) | FVG detection, order block breakout |
+| SMC Liquidity Order Block Breakout | SSL/BSL liquidity pool detection |
+| EMA Golden Cross / Death Cross | Fast/slow EMA crossover, trend period |
+| Triple EMA Ribbon | Fast/medium/slow EMA ribbon dynamics |
+| RSI Mean Reversion | RSI period, overbought, oversold |
+| MACD Zero-Line & Signal Line Crossover | Fast/slow/signal MACD components |
+| Bollinger Bands Squeeze & Reversal | Period, standard deviation |
+| Supertrend ATR Trend Follower | ATR period, multiplier |
+| Stochastic Oscillator | K period, D period, slowing |
+| ADX + DI Trend Classifier | ADX period, DI threshold |
+| Ichimoku Cloud Kumo Breakout | Tenkan, Kijun, Senkou B periods |
+| ATR Volatility Expansion Channel | ATR period |
+| TFT Log-Return Trend | Temporal Fusion Transformer ML |
+| Volatility Parity & Risk-Adjusted Allocation | Volatility-normalized allocation |
+
+### Macro Sentiment Analysis
+
+Live RSS headlines processed via **FinBERT** NLP model with dovish/hawkish net score cancellation math. Fallback regex-based scoring when transformer models are unavailable.
+
+## Terminal Menu Workflow Guide (Options 1-8)
+
+| Option | Description |
+|--------|-------------|
+| **1** | Instant Execution Card -- Kelly Position Sizing, dynamic Entry bounds, Dynamic SL (exact pip distance), Risk:Reward ratios |
+| **2** | Daily Price Path & Signals -- 30-day forward forecast with quantile monotonicity ($q_{10} \le q_{50} \le q_{90}$) |
+| **3** | Monthly Macro Horizon -- 22-day outlook & weekly pivots with dynamic bias calculation |
+| **4** | Yearly Regime Trend Shift -- 252-day forecast with volatility envelopes, $q_{90}$ capped at 6500 |
+| **5** | Macro News & FinBERT Sentiment -- Live RSS headline aggregation, Dovish/Hawkish score cancellation |
+| **6** | Risk & Position Sizing Calculator -- Custom market price overrides, pip distance math, zero static hardcoded outputs |
+| **7** | Historical Strategy Backtester -- All 14 strategies across 15m, 1h, 4h, 1D timeframes, dynamic lot sizing |
+| **8** | Multi-Strategy Ensemble Analyzer -- Top 5 leaderboard, dynamic header title (Local CPU vs Modal A10G), all strategies |
+
+### System Settings
+
+- Toggle execution environment (local/modal)
+- Set default account equity
+- Set default risk per trade %
+- Customize indicator parameters (all 10 groups with limits)
+- Save & apply settings persistence via `data/finrix_config.json`
+
+## Quality Assurance
+
+The repository includes a real pytest suite covering dynamic risk sizing,
+lookahead-safe trade lifecycle execution, all 14 indicator strategies,
+timeframe-specific caching, non-finite JSON coercion, and configuration
+sanitization.
+
+```text
+207 passed
+```
+
+Run the checks with:
+
+```bash
+python -m pytest -q
+python -m compileall -q app.py macro_forecast_engine
+```
+
+Finrix Screenshots:
+
+<img width="283" height="304" alt="Screenshot 2026-11-08 105821" src="https://github.com/user-attachments/assets/919fb0d2-2d04-4172-a401-9f4caab112c7" />
+<img width="282" height="281" alt="Screenshot 2026-11-08 105740" src="https://github.com/user-attachments/assets/d5558b17-58df-434c-9fda-0e8376d08090" />
+<img width="275" height="259" alt="Screenshot 2026-11-08 105707" src="https://github.com/user-attachments/assets/c11f30cd-bc4c-45fa-9ffa-6ab9fde55a88" />
+<img width="276" height="128" alt="Screenshot 2026-11-07 225107" src="https://github.com/user-attachments/assets/b0487285-9d31-4dd7-8191-e7b53a166eeb" />
+<img width="285" height="529" alt="Screenshot 2026-11-07 225031" src="https://github.com/user-attachments/assets/894637f0-90d2-4c23-9465-83352218779e" />
+
+
+
+
+## Future Roadmap
+
+- **Multi-asset expansion** -- Forex pairs, Crypto indices, Equity indices
+- **Direct MetaTrader 5 (MT5) execution bridge** & Webhook integration
+- **Automated portfolio rebalancing** with dynamic risk limits
+- **Walking-forward analysis** & rolling-origin backtesting
+- **Cluster deployment** across multiple Modal GPU workers
+
+## Repository Layout
+
+```text
+macro_forecast_engine/
+├── modal_engine.py       # Primary Modal A10G pipeline
+├── run_engine.py         # Forecast orchestration utilities
+├── data_loader.py        # Market, FRED, RSS, and sentiment ingestion
+├── execution_layer.py    # Macro-bias signal filtering utilities
+├── config.py             # Environment-backed configuration
+├── indicator_params.py   # Persistent indicator parameter JSON
+├── finrix_config.py      # Terminal settings persistence
+├── trader_execution.py   # SMC + TFT execution levels
+├── trader_risk.py        # Kelly sizing & volatility parity
+├── trader_timemachine.py # Strategy replay & confidence scoring
+├── config.py
+├── __init__.py
+.github/
+├── workflows/
+│   └── ci.yml            # GitHub Actions CI pipeline
+└── ISSUE_TEMPLATE/
+    ├── bug_report.md     # Bug report template
+    └── feature_request.md # Feature request template
+.github/PULL_REQUEST_TEMPLATE.md   # PR checklist template
+CONTRIBUTING.md    # Open-source guidelines
+FINRIX_Institutional_Project_Report.docx   # Project Report
+requirements.txt
+.env.example
+README.md (this file)
+FINRIX_SECURITY_AND_QA_AUDIT_REPORT.md
+data/
+├── finrix_config.json
+├── finrix_indicator_params.json
+├── macro_daily_forecast.json
+├── macro_month_forecast.json
+└── macro_year_forecast.json
+cache/
+gold_market_cache.csv
+```
+
+--- 
+
+MIT License. See [LICENSE](LICENSE).

finrix-1.0.0/finrix.egg-info/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: finrix
+Version: 1.0.0
+Summary: FINRIX Quantitative Trading Terminal — XAUUSD macro forecast engine with Rich CLI
+Requires-Python: <3.13,>=3.11
+License-File: LICENSE
+Requires-Dist: modal==0.73.0
+Requires-Dist: neuralforecast==1.7.5
+Requires-Dist: pyfredapi==0.10.2
+Requires-Dist: transformers==4.46.3
+Requires-Dist: torch==2.5.1
+Requires-Dist: pandas==2.2.3
+Requires-Dist: numpy==2.1.3
+Requires-Dist: scikit-learn==1.5.2
+Requires-Dist: yfinance==0.2.48
+Requires-Dist: requests==2.32.3
+Requires-Dist: python-dotenv==1.0.1
+Requires-Dist: rich==13.9.4
+Requires-Dist: questionary==2.0.1
+Requires-Dist: InquirerPy==0.3.4
+Dynamic: license-file

finrix-1.0.0/finrix.egg-info/SOURCES.txt

@@ -0,0 +1,28 @@
+LICENSE
+README.md
+pyproject.toml
+finrix.egg-info/PKG-INFO
+finrix.egg-info/SOURCES.txt
+finrix.egg-info/dependency_links.txt
+finrix.egg-info/entry_points.txt
+finrix.egg-info/requires.txt
+finrix.egg-info/top_level.txt
+macro_forecast_engine/__init__.py
+macro_forecast_engine/config.py
+macro_forecast_engine/data_fetcher.py
+macro_forecast_engine/data_loader.py
+macro_forecast_engine/data_processor.py
+macro_forecast_engine/finrix_config.py
+macro_forecast_engine/indicator_params.py
+macro_forecast_engine/json_utils.py
+macro_forecast_engine/modal_engine.py
+macro_forecast_engine/run_engine.py
+macro_forecast_engine/trader_execution.py
+macro_forecast_engine/trader_risk.py
+macro_forecast_engine/trader_timemachine.py
+tests/test_backtest.py
+tests/test_diffusion.py
+tests/test_indicators.py
+tests/test_integration.py
+tests/test_risk.py
+tests/test_security.py

finrix-1.0.0/finrix.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

finrix-1.0.0/finrix.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+finrix = app:main

finrix-1.0.0/finrix.egg-info/requires.txt

@@ -0,0 +1,14 @@
+modal==0.73.0
+neuralforecast==1.7.5
+pyfredapi==0.10.2
+transformers==4.46.3
+torch==2.5.1
+pandas==2.2.3
+numpy==2.1.3
+scikit-learn==1.5.2
+yfinance==0.2.48
+requests==2.32.3
+python-dotenv==1.0.1
+rich==13.9.4
+questionary==2.0.1
+InquirerPy==0.3.4

finrix-1.0.0/finrix.egg-info/top_level.txt

@@ -0,0 +1 @@
+macro_forecast_engine

finrix-1.0.0/macro_forecast_engine/__init__.py

@@ -0,0 +1,2 @@
+"""Macro-quant XAUUSD forecasting package."""
+

finrix-1.0.0/macro_forecast_engine/config.py

@@ -0,0 +1,28 @@
+"""Environment-backed configuration for the Modal forecast engine."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+try:
+    from dotenv import load_dotenv
+except ImportError:  # pragma: no cover
+    load_dotenv = None
+
+BASE_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = BASE_DIR.parent
+DATA_DIR = PROJECT_ROOT / "data"
+
+if load_dotenv is not None:
+    load_dotenv(PROJECT_ROOT / ".env")
+
+FRED_API_KEY = os.getenv("FRED_API_KEY", "").strip()
+FORECAST_MODE = os.getenv("FORECAST_MODE", os.getenv("FORECAST_HORIZON", "monthly")).lower()
+FINBERT_MODEL = os.getenv("FINBERT_MODEL", "ProsusAI/finbert")
+FRED_SERIES_TIPS = "DFII10"
+FRED_SERIES_2Y = "DGS2"
+
+HORIZONS = {"daily": 30, "monthly": 22, "yearly": 252}
+if FORECAST_MODE not in HORIZONS:
+    raise ValueError(f"FORECAST_MODE must be one of {', '.join(HORIZONS)}")

finrix-1.0.0/macro_forecast_engine/data_fetcher.py

@@ -0,0 +1,9 @@
+"""Compatibility exports for timeframe-aware market data ingestion."""
+
+from .data_loader import (
+    GOLD_TICKERS,
+    INTRADAY_PERIOD_LIMITS,
+    fetch_market_data,
+)
+
+__all__ = ["GOLD_TICKERS", "INTRADAY_PERIOD_LIMITS", "fetch_market_data"]

finrix-1.0.0/macro_forecast_engine/data_loader.py

@@ -0,0 +1,300 @@
+"""Institutional cross-asset and macro data ingestion helpers."""
+
+from __future__ import annotations
+
+import os
+import re
+import warnings
+from pathlib import Path
+from io import StringIO
+import xml.etree.ElementTree as ET
+from typing import Any, Iterable, Mapping, Optional
+
+import numpy as np
+import pandas as pd
+import requests
+from sklearn.preprocessing import RobustScaler
+
+try:
+    from .data_processor import add_sentiment_and_flow
+except ImportError:  # Modal may load this file as a top-level script.
+    from macro_forecast_engine.data_processor import add_sentiment_and_flow
+
+try:
+    import yfinance as yf
+except ImportError:  # pragma: no cover
+    yf = None
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+GOLD_TICKERS = ("GC=F", "XAUUSD=X")
+INTRADAY_PERIOD_LIMITS = {
+    "15m": ("60d", "15m"),
+    "1h": ("60d", "1h"),
+    "4h": ("60d", "1h"),
+    "1d": ("730d", "1d"),
+}
+
+
+def _download(ticker: str, period: str = "10y", interval: str = "1d") -> pd.DataFrame:
+    if yf is None:
+        raise RuntimeError("yfinance is required for market data ingestion")
+    frame = yf.download(ticker, period=period, interval=interval, auto_adjust=False,
+                        progress=False, threads=False)
+    if isinstance(frame.columns, pd.MultiIndex):
+        frame.columns = frame.columns.get_level_values(0)
+    if frame.empty:
+        raise ValueError(f"No data returned for {ticker}")
+    frame.index = pd.to_datetime(frame.index, utc=True).tz_localize(None)
+    frame.columns = [str(column).lower() for column in frame.columns]
+    return frame
+
+
+def _normalized_request(period: str, interval: str) -> tuple[str, str]:
+    configured = INTRADAY_PERIOD_LIMITS.get(interval.lower())
+    return configured if configured else (period, interval)
+
+
+def _cache_path(interval: str) -> Path:
+    normalized = interval.lower()
+    suffix = "1d" if normalized in {"1d", "d"} else normalized
+    safe_suffix = re.sub(r"[^a-z0-9_-]", "", suffix) or "1d"
+    return PROJECT_ROOT / "cache" / f"gold_cache_{safe_suffix}.csv"
+
+
+def _load_cached_gold(interval: str) -> pd.DataFrame:
+    cache_path = _cache_path(interval)
+    if not cache_path.exists():
+        return pd.DataFrame()
+    try:
+        cached = pd.read_csv(cache_path, index_col=0, parse_dates=True)
+        cached.index = pd.to_datetime(cached.index, utc=True).tz_localize(None)
+        if "gold_close" not in cached.columns:
+            return pd.DataFrame()
+        return cached.sort_index().dropna(subset=["gold_close"])
+    except (OSError, ValueError, TypeError):
+        return pd.DataFrame()
+
+
+def _fetch_gold(period: str, interval: str, cache_key: str | None = None) -> pd.DataFrame:
+    request_period, request_interval = _normalized_request(period, interval)
+    for ticker in GOLD_TICKERS:
+        try:
+            data = _download(ticker, request_period, request_interval)
+            if "close" not in data.columns or data["close"].dropna().empty:
+                continue
+            result = data.rename(columns={
+                "open": "gold_open", "high": "gold_high", "low": "gold_low",
+                "close": "gold_close", "volume": "gold_volume",
+            })
+            cache_path = _cache_path(cache_key or request_interval)
+            cache_path.parent.mkdir(parents=True, exist_ok=True)
+            result.to_csv(cache_path)
+            return result
+        except (RuntimeError, ValueError, requests.RequestException, OSError):
+            continue
+    cached = _load_cached_gold(cache_key or request_interval)
+    if not cached.empty:
+        return cached
+    raise ValueError("Gold market data is unavailable from GC=F, XAUUSD=X, and local cache")
+
+
+def fetch_market_data(period: str = "10y", interval: str = "1d") -> pd.DataFrame:
+    """Fetch gold, DXY, GVZ, ETF holdings/volume, and align daily factors."""
+    gold = _fetch_gold(period, interval, cache_key=interval)
+    frames: list[pd.DataFrame] = [gold]
+    request_period, request_interval = _normalized_request(period, interval)
+    for ticker, prefix in (("DX-Y.NYB", "dxy"),
+                           ("^GVZ", "gvz"), ("GLD", "gld"), ("IAU", "iau")):
+        try:
+            data = _download(ticker, request_period, request_interval)
+        except (RuntimeError, ValueError, requests.RequestException, OSError):
+            continue
+        columns = {
+            "open": f"{prefix}_open", "high": f"{prefix}_high",
+            "low": f"{prefix}_low", "close": f"{prefix}_close",
+            "volume": f"{prefix}_volume",
+        }
+        available = {source: target for source, target in columns.items() if source in data.columns}
+        frames.append(data.rename(columns=available)[list(available.values())])
+    frame = frames[0]
+    for other in frames[1:]:
+        frame = frame.join(other, how="left")
+    return frame.sort_index().ffill().dropna(subset=["gold_close"])
+
+
+def _fred_series(series_id: str, start_date: Optional[str], end_date: Optional[str],
+                 api_key: Optional[str] = None) -> pd.Series:
+    params = {"id": series_id, "cosd": start_date or "", "coed": end_date or ""}
+    url = "https://fred.stlouisfed.org/graph/fredgraph.csv"
+    api_key = (api_key or os.getenv("FRED_API_KEY", "")).strip()
+    if api_key:
+        url = "https://api.stlouisfed.org/fred/series/observations"
+        params = {"series_id": series_id, "api_key": api_key, "file_type": "json",
+                  "observation_start": start_date or "", "observation_end": end_date or ""}
+        response = requests.get(url, params=params, timeout=30)
+        response.raise_for_status()
+        data = pd.DataFrame(response.json().get("observations", []))
+        series = data.set_index("date")["value"]
+    else:
+        response = requests.get(url, params=params, timeout=30)
+        response.raise_for_status()
+        data = pd.read_csv(StringIO(response.text))
+        date_column = "DATE" if "DATE" in data.columns else "observation_date"
+        series = data.set_index(date_column)[series_id].replace(".", np.nan)
+    series.index = pd.to_datetime(series.index, utc=True).tz_localize(None)
+    return pd.to_numeric(series, errors="coerce").rename(series_id).dropna()
+
+
+def fetch_macro_data(start_date: str, end_date: str,
+                     fred_api_key: Optional[str] = None) -> pd.DataFrame:
+    """Fetch TIPS real yields and the 10Y-2Y Treasury curve spread."""
+    result = pd.DataFrame(index=pd.date_range(start_date, end_date, freq="D"))
+    for series_id, name in (("DFII10", "tips10y"), ("DGS10", "ust10y"), ("DGS2", "ust2y")):
+        try:
+            result = result.join(
+                _fred_series(series_id, start_date, end_date, api_key=fred_api_key),
+                how="left",
+            )
+        except (requests.RequestException, ValueError, KeyError):
+            result[name] = np.nan
+    if "DGS10" in result and "DGS2" in result:
+        result["curve_spread_10y2y"] = result["DGS10"] - result["DGS2"]
+    else:
+        result["curve_spread_10y2y"] = np.nan
+    return result.rename(columns={"DFII10": "tips10y"}).drop(columns=["DGS10", "DGS2"], errors="ignore")
+
+
+def fetch_cot_data() -> pd.DataFrame:
+    """Fetch current CFTC disaggregated gold positioning when available."""
+    url = "https://publicreporting.cftc.gov/resource/jun7-fc8e.json"
+    try:
+        response = requests.get(url, params={"$limit": 2000, "$q": "GOLD"}, timeout=30)
+        response.raise_for_status()
+        rows = response.json()
+        data = pd.DataFrame(rows)
+        date_col = next((c for c in ("report_date_as_yyyy_mm_dd", "report_date") if c in data), None)
+        if date_col is None:
+            return pd.DataFrame()
+        data.index = pd.to_datetime(data[date_col], errors="coerce")
+        result = pd.DataFrame(index=data.index)
+        for prefix, target in (("comm_positions", "commercial_positions"),
+                               ("noncomm_positions", "noncommercial_positions")):
+            long = next((c for c in data.columns if c.startswith(f"{prefix}_long")), None)
+            short = next((c for c in data.columns if c.startswith(f"{prefix}_short")), None)
+            if long and short:
+                result[target] = (
+                    pd.to_numeric(data[long], errors="coerce")
+                    - pd.to_numeric(data[short], errors="coerce")
+                )
+        return result.groupby(level=0).last().sort_index()
+    except (requests.RequestException, ValueError, KeyError):
+        return pd.DataFrame()
+
+
+GOLD_NEWS_FEEDS: tuple[tuple[str, str], ...] = (
+    ("forexlive_gold", "https://www.forexlive.com/feed/news"),
+    ("investing_commodities", "https://www.investing.com/rss/commodities.rss"),
+    ("marketwatch_macro", "https://feeds.marketwatch.com/marketwatch/marketpulse/"),
+)
+GOLD_MACRO_KEYWORDS = re.compile(
+    r"\b("
+    r"gold|xauusd|fomc rate|cpi|inflation|non[- ]farm payrolls?|"
+    r"dxy|yields?"
+    r")\b",
+    re.IGNORECASE,
+)
+
+
+def filter_gold_macro_headlines(headlines: Iterable[Any]) -> list[str]:
+    """Keep only headlines tied to gold macro drivers."""
+    return [text for item in headlines if (text := str(item).strip())
+            and GOLD_MACRO_KEYWORDS.search(text)]
+
+
+def fetch_live_news() -> pd.DataFrame:
+    rows: list[dict[str, Any]] = []
+    for source, feed_url in GOLD_NEWS_FEEDS:
+        try:
+            response = requests.get(feed_url, headers={"User-Agent": "macro-forecast-engine/1.0"}, timeout=30)
+            response.raise_for_status()
+            root = ET.fromstring(response.content)
+        except (requests.RequestException, ET.ParseError):
+            continue
+        for item in root.findall(".//item"):
+            title = (item.findtext("title") or "").strip()
+            date = pd.to_datetime(item.findtext("pubDate"), errors="coerce", utc=True)
+            if title and not pd.isna(date) and GOLD_MACRO_KEYWORDS.search(title):
+                rows.append({"date": date.tz_localize(None), "headline": title, "source": source})
+    result = pd.DataFrame(rows, columns=["date", "headline", "source"])
+    if result.empty:
+        return result
+    return result.drop_duplicates(subset=["headline"]).sort_values("date", ascending=False).reset_index(drop=True)
+
+
+def score_headlines(headlines: Iterable[Any], model_name: str = "ProsusAI/finbert") -> float:
+    texts = filter_gold_macro_headlines(headlines)
+    if not texts:
+        return float("nan")
+    try:
+        from transformers import pipeline
+        try:
+            classifier = pipeline("text-classification", model=model_name, top_k=None, device=0)
+        except (RuntimeError, OSError, ValueError):
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", UserWarning)
+                classifier = pipeline("text-classification", model=model_name, top_k=None, device=-1)
+        values = []
+        for output in classifier(texts, truncation=True, max_length=256):
+            labels = output if isinstance(output, list) else [output]
+            scores = {str(item["label"]).lower(): float(item["score"]) for item in labels}
+            positive = scores.get("positive", scores.get("bullish", 0.0))
+            negative = scores.get("negative", scores.get("bearish", 0.0))
+            neutral = scores.get("neutral", 0.0)
+            values.append((positive - negative) * (1.0 - 0.25 * neutral))
+        return float(np.mean(values)) if values else float("nan")
+    except (ImportError, OSError, RuntimeError, ValueError):
+        bullish = re.compile(
+            r"\b(weak dollar|dollar falls?|dxy falls?|lower yield|rate cut|"
+            r"dovish|recession|uncertainty|gold rises?)\b", re.I,
+        )
+        bearish = re.compile(
+            r"\b(strong dollar|dollar rises?|dxy rises?|higher yield|yields? rise|"
+            r"rate hike|hawkish|hot inflation|cpi rises|ppi rises|payrolls beat)\b", re.I,
+        )
+        values = []
+        for text in texts:
+            positive = len(bullish.findall(text))
+            negative = len(bearish.findall(text))
+            values.append((positive - negative) / max(1, positive + negative))
+        return float(np.mean(values)) if values else float("nan")
+
+
+def build_feature_frame(daily: pd.DataFrame, macro: Optional[pd.DataFrame] = None,
+                        cot: Optional[pd.DataFrame] = None,
+                        news: Optional[pd.DataFrame] = None) -> pd.DataFrame:
+    """Align market, macro, positioning, ETF, volatility, and NLP velocity features."""
+    frame = daily.copy().sort_index()
+    if macro is not None:
+        frame = frame.join(macro.reindex(frame.index, method="ffill"), how="left")
+    if cot is not None and not cot.empty:
+        frame = frame.join(cot.reindex(frame.index, method="ffill"), how="left")
+    sentiment = 0.0
+    if news is not None and not news.empty:
+        scored_sentiment = score_headlines(news["headline"].tolist())
+        sentiment = 0.0 if pd.isna(scored_sentiment) else float(scored_sentiment)
+    frame = add_sentiment_and_flow(frame, sentiment, cot)
+    frame["sentiment"] = sentiment
+    frame["sentiment_velocity"] = frame["sentiment"].diff().fillna(0.0)
+    for column in ("tips10y", "curve_spread_10y2y", "commercial_positions",
+                   "noncommercial_positions", "gvz_close", "gld_volume", "iau_volume"):
+        if column not in frame:
+            frame[column] = 0.0
+        frame[column] = pd.to_numeric(frame[column], errors="coerce").ffill().bfill().fillna(0.0)
+    scaled_columns = [
+        "gvz_close", "gld_volume", "iau_volume",
+        "commercial_positions", "noncommercial_positions",
+    ]
+    frame[scaled_columns] = RobustScaler().fit_transform(frame[scaled_columns])
+    frame["gold_return"] = frame["gold_close"].pct_change()
+    frame["dxy_return"] = frame["dxy_close"].pct_change()
+    return frame.replace([np.inf, -np.inf], np.nan).dropna(subset=["gold_close"])