Update README.md

README.md

@@ -1,3 +1,208 @@
----
-license: mit
----
+---
+license: mit
+library_name: keras
+tags:
+- time-series
+- finance
+- forex
+- lstm
+- tensorflow
+- economics
+metrics:
+- mean_squared_error
+- accuracy
+---
+
+# Model Card for Forex-LSTM-Predictor-Collection
+
+This repository hosts a collection of **20 specialized Long Short-Term Memory (LSTM)** neural network models designed to forecast future price movements and directional trends for major currency pairs. Each model is trained on a specific pair and timeframe tuple.
+
+## Model Details
+
+### Model Description
+
+This project explores the application of Deep Learning to financial time-series forecasting. Unlike generic models, this collection treats every currency pair and timeframe combination (e.g., `EURUSD` on `15m`) as a unique environment requiring a dedicated model.
+
+The models utilize historical **OHLCV** (Open, High, Low, Close, Volume) data to predict two simultaneous outputs:
+1.  **Price Vector:** The projected closing price for the next time step.
+2.  **Directional Probability:** A confidence score indicating the likelihood of the price moving Up or Down.
+
+*Note: These models are part of a larger full-stack research project ("FX-Predict") involving a FastAPI backend and a real-time dashboard.*
+
+- **Developed by:** Rogendo
+- **Model type:** Dual-Output LSTM (Regression + Classification)
+- **Language(s):** Python 3.12 (TensorFlow/Keras)
+- **License:** MIT
+- **Finetuned from model:** N/A (Trained from scratch)
+
+### Model Sources
+
+- **Repository:** [https://huggingface.co/rogendo/forex-lstm-models](https://huggingface.co/rogendo/forex-lstm-models)
+
+## Uses
+
+### Direct Use
+
+These models are intended for:
+*   **Algorithmic Trading Research:** Backtesting ML strategies on forex markets.
+*   **Signal Generation:** Providing baseline buy/sell signals based on price action history.
+*   **Market Analysis:** Identifying potential trend reversals via directional confidence scores.
+
+### Downstream Use
+
+The models are designed to be consumed by an inference engine (like the `model_service.py` in the FX-Predict app) which applies post-processing logic:
+*   **Risk Management:** Calculating dynamic Stop Loss/Take Profit levels using ATR (Average True Range).
+*   **Confluence checking:** Comparing predictions across timeframes (e.g., 15m vs 4h).
+
+### Out-of-Scope Use
+
+*   **Unsupervised Live Trading:** These models are Proof-of-Concept tools. They should not control real capital without a strict risk management wrapper (see Limitations).
+*   **Long-term Forecasting:** The models are optimized for the next candle ($t+1$) only.
+
+## Bias, Risks, and Limitations
+
+### The "Accuracy vs. Profitability" Paradox
+During testing, a critical discrepancy was observed:
+*   **High Directional Accuracy:** The models frequently achieved **>55% accuracy** in predicting the color of the next candle.
+*   **Low Win Rate (~40%):** Without external logic, the raw model predictions often led to losses.
+    *   *Cause:* The model predicts the *vector* correctly but not the *path*. On volatile timeframes (5m/15m), market noise often triggered standard Stop Losses before the prediction materialized.
+    *   *Mitigation:* We strongly recommend using **ATR-based dynamic stops** rather than fixed percentage stops when using these models.
+
+### Data Limitations
+*   **Data Source:** Trained on data from `yfinance` (Yahoo Finance).
+*   **Lag & Limits:** Yahoo Finance data can be delayed. Crucially, intraday data (5m/15m) is restricted to the last **60 days**. This introduces **Recency Bias**, as the model has not seen historical market regimes (e.g., the 2008 crash or 2020 volatility).
+
+### Feature Poverty
+The inputs are currently limited to raw `OHLCV`. The models lack "Macro-Awareness" (Economic Calendar events) and Order Flow data, limiting their ability to react to news events.
+
+### Recommendations
+
+Users should treat these models as **Directional Compasses**, not Crystal Balls. They work best when validated by "Market Breadcrumbs" such as:
+*   Session High/Low breaks (e.g., 9:30 AM NY Open).
+*   Key psychological levels (0.000 / 0.500).
+*   Multi-timeframe confluence.
+
+## How to Get Started with the Model
+
+You need the `.h5` model file and the corresponding `.pkl` feature scaler file to ensure data is normalized exactly as the model expects.
+
+```python
+import numpy as np
+import pickle
+import os
+from tensorflow.keras.models import load_model
+from huggingface_hub import hf_hub_download
+
+# 1. Select Pair and Interval
+PAIR = "EURUSD_X"  # Options: GBPUSD_X, USDJPY_X, etc.
+INTERVAL = "15m"   # Options: 5m, 15m, 30m, 1h, 4h
+
+# 2. Download Files
+model_path = hf_hub_download(repo_id="rogendo/forex-lstm-models", filename=f"{PAIR}_{INTERVAL}_model.h5")
+scaler_path = hf_hub_download(repo_id="rogendo/forex-lstm-models", filename=f"{PAIR}_{INTERVAL}_features.pkl")
+
+# 3. Load Model
+model = load_model(model_path)
+with open(scaler_path, 'rb') as f:
+    feature_info = pickle.load(f)
+
+print(f"Loaded {PAIR} {INTERVAL} | Lookback: {feature_info['lookback']}")
+
+# 4. Prepare Dummy Data (Replace with real OHLCV data scaled via RobustScaler)
+# Shape: (1, Lookback_Steps, 5_Features)
+dummy_input = np.random.rand(1, feature_info['lookback'], 5)
+
+# 5. Predict
+prediction = model.predict(dummy_input)
+price_change = prediction[0][0][0]
+direction_conf = prediction[1][0][0]
+
+print(f"Predicted Change: {price_change:.5f}")
+print(f"Direction Confidence: {direction_conf:.2f}")
+
+```
+
+### Training Details
+#### Training Data
+
+The models were trained on historical Forex data fetched via yfinance.
+
+Pairs: **EURUSD, GBPUSD, USDJPY, AUDUSD, USDCAD, USDCHF, NZDUSD**.
+
+Timeframes: **5m, 15m (approx 60 days history); 30m, 1h, 4h** (approx 2 years history).
+
+#### Training Procedure
+##### Preprocessing
+
+Scaling: RobustScaler (sklearn) was used to handle outliers in financial data.
+
+Windowing: Data was transformed into sequences of 15 lookback steps.
+
+##### Training Hyperparameters
+
+Optimizer: Adam (learning_rate=0.001)
+
+Loss Functions:
+
+Price: mean_squared_error
+
+Direction: binary_crossentropy
+
+Batch Size: 32
+
+Epochs: 50 (with Early Stopping patience=15)
+
+##### Evaluation 
+###### Testing Data, Factors & Metrics
+**Testing Data**
+
+Data was split 80/20 for Training/Validation. Due to the rolling window nature of time series, the validation set represents the most recent market data available at the time of training.
+
+##### Metrics
+
+RMSE (Root Mean Squared Error): Measures price prediction magnitude error.
+
+MAE (Mean Absolute Error): Average error in pips.
+
+Directional Accuracy: % of time the model correctly predicted Positive vs Negative close.
+
+##### Results
+
+
+4H, 14min Models: Showed the highest stability and profitability because price trends are cleaner.
+
+5M Models: Showed high noise. While directional accuracy remained >50%, the realizable profit was often eaten by spreads.
+
+##### Technical Specifications
+**Model Architecture**
+
+The architecture is designed to capture temporal dependencies:
+
+Input Layer: Shape (15, 5)
+
+LSTM Layer 1: 50 units, Return Sequences=True, Dropout=0.2
+
+LSTM Layer 2: 25 units, Return Sequences=False, Dropout=0.2
+
+Dense Layer: 20 units, ReLU
+
+Output 1 (Regression): 1 Unit (Price Change)
+
+Output 2 (Classification): 1 Unit (Sigmoid - Direction)
+
+##### Future Roadmap
+
+To improve the "Realizable Profitability" of these models, the following upgrades are planned:
+
+**Data Pipeline Overhaul**: Move away from yfinance to a professional provider (OANDA/Alpha Vantage) to access 2+ years of 5m data and faster api.
+
+**Feature Expansion**: Triple the input features to include:
+
+  - Rolling Technical Indicators (RSI, MACD, Bollinger Bands) as inputs (not just validators).
+
+  - Time-of-day embeddings (to learn session volatility).
+
+**Architecture**: Experiment with CNN-LSTM hybrids (to catch chart patterns) and Transformer models (TimeGPT).
+
+
+For questions regarding the implementation or the "FX-Predict" dashboard integration, please open a discussion in the Community tab.