README.md

---
title: Forex Crypto Prediction
emoji: 📈
colorFrom: blue
colorTo: green
sdk: gradio
app_file: app.py
pinned: false
python_version: "3.11"
---

# 📈 Forex & Crypto Prediction Dashboard

Multi-timeframe forex & crypto price prediction with **ARIMA**,
**Auto-ARIMA**, **ARIMA-GARCH**, **Moirai** (Salesforce) and **TimesFM**
(Google) — each model's accuracy is backtested and reported **separately**,
plus a candle-by-candle correct/incorrect verification log. Pure Python,
built for a free/low CPU-only Hugging Face Space (2 vCPU / 16GB RAM / ~50GB
storage).

**Educational / research project — not financial advice.** Forex and crypto
trading carries substantial risk of loss. Nothing this app outputs is a
recommendation to trade.

## What's inside

- **Live + historical data**, free, no API key — [yfinance](https://github.com/ranaroussi/yfinance)
  (Yahoo Finance). Live means polling the same free source on a timer, since
  Yahoo has no free websocket feed.
- **Any symbol** — a dropdown of popular forex pairs (`EURUSD=X`, `GBPUSD=X`, ...)
  and crypto pairs (`BTC-USD`, `ETH-USD`, ...) that also accepts any custom
  yfinance-valid ticker you type in.
- **Any timeframe** — 1m, 5m, 10m, 15m, 30m, 1h, 4h, 1d out of the box.
  Timeframes Yahoo doesn't serve natively (like 10m) are built by resampling
  a smaller native interval, so you're not limited to Yahoo's fixed list.
- **5 forecasting models**, one shared interface (`models/base_model.py`):
  - **ARIMA** (`statsmodels`) — fast, classical, always available. Order
    (p,d,q) is found with a brute-force AIC grid search.
  - **Auto-ARIMA** (`pmdarima`) — same idea as ARIMA, but the order is found
    with pmdarima's stepwise search (the Python port of R's
    `auto.arima()`) instead of a brute-force grid.
  - **ARIMA-GARCH** (`statsmodels` + `arch`) — ARIMA models the conditional
    mean of returns, GARCH(1,1) models the conditional variance (volatility
    clustering) on top of it. Forecasted volatility is kept on the model
    instance (`last_volatility_forecast`) for anyone who wants to build
    confidence bands later.
  - **Moirai** (`uni2ts`) — Salesforce's pretrained time-series foundation model.
  - **TimesFM 2.5** (`timesfm`) — Google's pretrained time-series foundation model.
- **Top 5 technical indicators** (hand-implemented on pandas, no extra
  dependency): RSI, MACD, Bollinger Bands, SMA/EMA, Stochastic Oscillator.
  These are shown for chart analysis — they're separate from, and not mixed
  into, the 5 models' backtested accuracy.
- **Walk-forward backtesting** with a **separate** accuracy card per model
  (correct / incorrect / accuracy % / MAE / RMSE) — numbers are never
  averaged together across models — plus a per-candle log of every
  prediction vs. what actually happened, so you can verify exactly how many
  candles each model got right or wrong.
- **Live tab**: polls for the newest candle, predicts the next one, and once
  that candle closes, checks whether the prediction was right — with a
  running accuracy tally. `live_runner.py` does the same thing unattended
  from the command line, logging to CSV.

## Project layout

```
config.py              symbols, timeframes, model checkpoints
app.py                 Gradio dashboard (entry point for the Space)
live_runner.py         standalone CLI for unattended live logging
data/
  historical.py        yfinance fetch + resampling + 7-day-chunked 1m fetch
  live.py               polling loop helper
indicators/
  indicators.py         RSI, MACD, Bollinger Bands, SMA/EMA, Stochastic
models/
  base_model.py          shared interface all 5 models implement
  arima_model.py          ARIMA (statsmodels), cached order search
  auto_arima_model.py     Auto-ARIMA (pmdarima), cached stepwise search
  arima_garch_model.py    ARIMA-GARCH (statsmodels + arch), mean + volatility
  moirai_model.py         Moirai (uni2ts + GluonTS)
  timesfm_model.py        TimesFM 2.5 (timesfm[torch])
  registry.py             lazy-loading model factory
backtest/
  backtester.py           walk-forward loop + per-model accuracy summary
utils/
  helpers.py               small shared utilities
requirements.txt
```

## Running locally

```bash
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
python app.py
```

Open the local URL Gradio prints (usually `http://127.0.0.1:7860`).

## Deploying to Hugging Face Spaces

1. Create a new Space → SDK: **Gradio** → hardware: **2 vCPU / 16GB RAM**
   (the free CPU tier) is enough for all 5 models at their default (small)
   checkpoints.
2. Upload every file in this project, keeping the folder structure
   (`data/`, `models/`, etc.) intact — Spaces builds from the repo root.
3. The YAML block at the top of this README is what Spaces reads to
   configure the app (`sdk: gradio`, `app_file: app.py`). No changes needed
   unless you want a different title/emoji/colors.
4. Push. The Space installs `requirements.txt` and launches `app.py`
   automatically. First launch is normal Python-only (ARIMA works
   immediately); Moirai/TimesFM download their pretrained weights
   on-demand the first time you actually use them from the UI.

## Models — what to expect on CPU-only hardware

| Model | Package | Approx. size | Notes |
|---|---|---|---|
| ARIMA | `statsmodels` | tiny | Fastest by far. Order (p,d,q) is searched once per backtest run (brute-force AIC grid) and reused, not re-searched every candle. |
| Auto-ARIMA | `pmdarima` | tiny | Same speed idea as ARIMA — stepwise order search runs once and is reused. Stepwise search is usually quicker than ARIMA's brute-force grid, but each individual fit is a bit heavier than plain ARIMA. |
| ARIMA-GARCH | `statsmodels` + `arch` | tiny | Two fits per prediction (ARIMA for the mean, GARCH for the volatility), so a little slower than plain ARIMA — still fast next to the foundation models. |
| Moirai (`moirai-1.1-R-small`) | `uni2ts` | small (~14M params) | Zero-shot foundation model, no training needed. |
| TimesFM 2.5 (`timesfm-2.5-200m`) | `timesfm[torch]` | ~800MB download, ~4GB RAM | Zero-shot foundation model, no training needed. |

Both foundation models are **zero-shot** — they were pretrained elsewhere and
just run inference here, no training step in this project. They're slower
per-prediction than ARIMA on CPU, which matters most in the **Backtest** tab
(one model call per candle). Use the **Step** slider there to skip candles
(e.g. step=5 or 10) and keep Moirai/TimesFM backtests fast on 2 vCPUs.
Checkpoints are configurable in `config.py` if you later move to GPU hardware
and want the bigger `base`/`large` variants.

## How accuracy is measured

For each candle in a backtest (or each live prediction), the model forecasts
the next close; we compare **predicted direction** (up/down vs. the current
close) to what **actually** happened once that candle closes. That's one
verified candle: correct or incorrect. A model's accuracy % is
`correct / (correct + incorrect)` over the whole run — and each model's
numbers live in their own card/tab, never averaged with another model's.
MAE/RMSE (predicted price vs. actual price) are reported alongside as a
secondary, continuous-error view.

## Known limitations (please read before relying on this for anything real)

- **Yahoo/yfinance history limits** (enforced by Yahoo, not this project):
  1-minute candles ≈ last 7–30 days only; other intraday intervals ≈ last 60
  days; hourly ≈ last 730 days; daily+ is full history. The app tells you if
  a request falls outside what's available rather than failing silently.
- **"Live" is polling, not push.** Free forex/crypto data has no public
  websocket firehose, so "live" here means re-fetching on a timer — fine for
  candle-close-level decisions, not for tick-by-tick/HFT use.
- **"All symbols"** means any symbol yfinance/Yahoo covers — there's no
  finite master list to ship, so the app takes any ticker you type in rather
  than pretending to enumerate everything.
- **Small foundation-model checkpoints** were chosen to fit 2 vCPU/16GB
  comfortably. Bigger checkpoints (`base`/`large`) may forecast better but
  need more RAM/CPU time — swap them in `config.py` if your hardware allows.
- This was built and syntax-checked without live internet access in the
  build environment, so package APIs were verified against each project's
  current documentation but not executed end-to-end here. Test on your own
  machine or Space before trusting it, and check each library's docs/repo if
  an API has moved since (`uni2ts` and `timesfm` are active research
  projects that occasionally make breaking changes; `pmdarima` and `arch`
  are more stable but worth a version check too).

## Disclaimer

This project is for education and research. It does not constitute
financial advice, and past backtested accuracy is not a promise of future
performance. Forex and crypto markets are volatile and you can lose money
trading them — always do your own research and consider consulting a
licensed financial advisor before trading real capital.