📈 Commodity Price Prediction System

A production-ready deep learning system for forecasting US commodity prices using LSTM, BiLSTM, and Transformer architectures.

Live Demo • Documentation • API Access

---

🎯 Overview

This project implements state-of-the-art time series forecasting models to predict prices for major US commodities including:

• Energy: Crude Oil (WTI), Natural Gas
• Precious Metals: Gold, Silver
• Base Metals: Copper
• Agriculture: Corn, Wheat, Soybeans

Key Features

• 🧠 Multiple Model Architectures: LSTM, BiLSTM, CNN-LSTM, Transformer, and hybrid models
• 📊 100+ Technical Features: Moving averages, RSI, MACD, Bollinger Bands, volatility measures
• 📈 Interactive Dashboard: Real-time visualization with Chart.js
• ⚡ Automated Pipeline: Daily predictions via GitHub Actions
• 🎯 Multi-Horizon Forecasts: 1-day, 5-day, and 10-day predictions

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      DATA INGESTION                             │
│  Yahoo Finance API → Raw OHLCV Data → Data Validation           │
└─────────────────────┬───────────────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                   FEATURE ENGINEERING                           │
│  Price Lags │ Returns │ Moving Averages │ Volatility │ RSI     │
│  MACD │ Bollinger Bands │ Cross-commodity │ Calendar Features   │
└─────────────────────┬───────────────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                    MODEL ENSEMBLE                               │
│  ┌─────────┐  ┌─────────┐  ┌─────────────┐  ┌──────────────┐   │
│  │  LSTM   │  │ BiLSTM  │  │ Transformer │  │ LSTM+Transf. │   │
│  └────┬────┘  └────┬────┘  └──────┬──────┘  └──────┬───────┘   │
│       └────────────┴──────────────┴─────────────────┘           │
│                           ▼                                     │
│                  Weighted Ensemble                              │
└─────────────────────┬───────────────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                      PREDICTIONS                                │
│  1-Day Forecast │ 5-Day Forecast │ 10-Day Forecast              │
│  Confidence Intervals │ Direction Probability                   │
└─────────────────────────────────────────────────────────────────┘

---

📊 Model Performance

Backtested on 2 years of out-of-sample data (2023-2025):

Model	RMSE	MAE	MAPE	Directional Accuracy
LSTM	1.847	1.423	2.31%	54.2%
BiLSTM	1.756	1.352	2.18%	55.8%
Transformer	1.892	1.478	2.45%	53.1%
Hybrid (LSTM+Transformer)	1.698	1.287	2.04%	57.3%

Results on Crude Oil WTI daily price prediction

---

🚀 Quick Start

Installation

git clone https://github.com/YOUR_USERNAME/commodity-predictor.git
cd commodity-predictor
pip install -r requirements.txt

Run Demo

# Train models and generate predictions with sample data
python demo.py

Train on Real Data

# Full training pipeline
python train.py --commodity "Crude Oil WTI" --epochs 100

---

📁 Project Structure

commodity-predictor/
├── models.py                 # Neural network architectures
├── feature_engineering.py    # Technical indicator generation
├── data_loader.py           # Data fetching and preprocessing
├── train.py                 # Training pipeline
├── demo.py                  # Demo with sample data
├── dashboard.html           # Interactive web dashboard
├── sample_data.py           # Synthetic data generator
└── requirements.txt         # Dependencies

---

🧠 Model Details

BiLSTM Architecture

class BiLSTMModel(nn.Module):
    """
    Bidirectional LSTM for capturing both forward 
    and backward temporal patterns.
    
    Architecture:
    - Input projection layer
    - 2-layer Bidirectional LSTM (hidden_size=64)
    - Dropout regularization (p=0.2)
    - Fully connected output layer
    """

Feature Engineering

The system generates 100+ features including:

Category	Features
Lag Features	1, 2, 3, 5, 7, 14, 21, 30, 60, 90 day lags
Returns	1, 5, 10, 21, 63 day returns
Moving Averages	SMA & EMA (5, 10, 20, 50, 100, 200)
Volatility	Rolling std dev (5, 10, 21, 63 day)
Momentum	RSI, MACD, Rate of Change
Bands	Bollinger Band position & width
Cross-Commodity	Gold/Silver ratio, WTI/Brent spread
Calendar	Day of week, month, seasonality encoding

---

📈 Dashboard

The interactive dashboard provides:

• Real-time price cards with prediction badges
• Historical charts with forecast overlay
• Multi-horizon forecasts (1, 5, 10 days)
• Model performance metrics

---

🔌 API Access

Predictions are available via JSON endpoint:

fetch('https://YOUR_USERNAME.github.io/commodity-predictor/predictions/sample_predictions.json')
  .then(response => response.json())
  .then(data => {
    console.log(data.predictions['Crude Oil WTI'].forecasts['1d']);
    // { price: 69.15, change_pct: 0.63 }
  });

Premium API with real-time predictions available — Contact for access

---

📚 Documentation

• Feature Engineering Guide
• Model Architecture Details
• Training Pipeline
• Deployment Options

---

🛠️ Tech Stack

• Deep Learning: PyTorch
• Data Processing: Pandas, NumPy
• Data Source: Yahoo Finance, FRED
• Visualization: Chart.js, Matplotlib
• Deployment: GitHub Actions, GitHub Pages

---

📄 License

MIT License — see LICENSE for details.

---

📬 Contact

Brian Curry — brian at vector1.ai

---

🙏 Acknowledgments

• Yahoo Finance for market data
• World Bank for historical commodity data
• Research papers on LSTM and Transformer architectures for financial forecasting