| --- |
| license: apache-2.0 |
| library_name: pytorch |
| pipeline_tag: time-series-forecasting |
| tags: |
| - time-series |
| - forecasting |
| - pytorch |
| - safetensors |
| - deployable |
| - edge-ai |
| - onnx |
| - streaming |
| - raspberry-pi |
| - transformer |
| - foundation-model |
| - zero-shot |
| - iot |
| - real-time |
| - tiny-ml |
| - timesfm-alternative |
| - huggingface |
| metrics: |
| - mase |
| - smape |
| - mae |
| - crps |
| model-index: |
| - name: NanoForecast v0.3 |
| results: |
| - task: |
| type: time-series-forecasting |
| name: Time Series Forecasting |
| dataset: |
| name: ETTh1 |
| type: ett |
| config: h1 |
| metrics: |
| - type: mase |
| value: 1.946 |
| name: MASE |
| - type: smape |
| value: 12.06 |
| name: sMAPE (%) |
| - task: |
| type: time-series-forecasting |
| name: Time Series Forecasting |
| dataset: |
| name: ETTh2 |
| type: ett |
| config: h2 |
| metrics: |
| - type: mase |
| value: 2.741 |
| name: MASE |
| - type: smape |
| value: 10.47 |
| name: sMAPE (%) |
| - task: |
| type: time-series-forecasting |
| name: Time Series Forecasting |
| dataset: |
| name: ETTm1 |
| type: ett |
| config: m1 |
| metrics: |
| - type: mase |
| value: 2.174 |
| name: MASE |
| - type: smape |
| value: 10.70 |
| name: sMAPE (%) |
| - task: |
| type: time-series-forecasting |
| name: Time Series Forecasting |
| dataset: |
| name: exchange_rate |
| type: exchange-rate |
| metrics: |
| - type: mase |
| value: 7.442 |
| name: MASE |
| - type: smape |
| value: 1.72 |
| name: sMAPE (%) |
| - task: |
| type: time-series-forecasting |
| name: Time Series Forecasting |
| dataset: |
| name: electricity |
| type: electricity |
| metrics: |
| - type: mase |
| value: 1.294 |
| name: MASE |
| - type: smape |
| value: 4.76 |
| name: sMAPE (%) |
| - task: |
| type: time-series-forecasting |
| name: Time Series Forecasting |
| dataset: |
| name: traffic |
| type: traffic |
| metrics: |
| - type: mase |
| value: 0.807 |
| name: MASE |
| - type: smape |
| value: 24.00 |
| name: sMAPE (%) |
| - task: |
| type: time-series-forecasting |
| name: Time Series Forecasting |
| dataset: |
| name: Overall |
| type: multi-dataset |
| metrics: |
| - type: mase |
| value: 2.734 |
| name: Overall MASE |
| - type: smape |
| value: 10.62 |
| name: Overall sMAPE (%) |
| --- |
| |
| <h1 align="center"> |
| 🔮 NanoForecast v0.3 |
| <br> |
| <sub>World's most deployable time series transformer</sub> |
| </h1> |
|
|
| <p align="center"> |
| <b>6.5M params · 512 context · Streaming RNN · ONNX-ready</b> |
| <br> |
| <i>Runs on CPU, Raspberry Pi, and in the browser</i> |
| </p> |
|
|
| <p align="center"> |
| <a href="https://huggingface.co/spaces/eulogik/nanoforecast"><img src="https://img.shields.io/badge/🤗%20Live%20Demo-Spaces-blueviolet"></a> |
| <a href="https://github.com/eulogik/NanoForecast"><img src="https://img.shields.io/badge/GitHub-eulogik%2FNanoForecast-181717?logo=github"></a> |
| <a href="https://pypi.org/project/nanoforecast/"><img src="https://img.shields.io/pypi/v/nanoforecast"></a> |
| <a href="https://huggingface.co/eulogik/nanoforecast-v03"><img src="https://img.shields.io/badge/🤗%20Downloads-0%20this%20month-blue"></a> |
| <a href="https://eulogik.com"><img src="https://img.shields.io/badge/by-Eulogik-purple"></a> |
| </p> |
|
|
| --- |
|
|
| ## 🚀 Why NanoForecast? |
|
|
| Most time series foundation models are **too big to ship** — they need GPUs, terabytes of training data, and a PhD to deploy. NanoForecast is different: |
|
|
| | Feature | NanoForecast | Other Foundation Models | |
| |---|---|---| |
| | **Parameters** | 200K – 6.5M | 200M – 10B+ | |
| | **Inference device** | CPU, Raspberry Pi, browser | GPU required | |
| | **Model size** | 1.4 MB (ONNX) | 1 GB+ | |
| | **Streaming** | ✅ Stateful RNN — feed one value at a time | ❌ Fixed-window only | |
| | **Training** | 2 min on laptop | 1000+ GPU-hours | |
| | **ONNX export** | ✅ Built-in | ❌ Often broken | |
| | **Zero-shot** | ✅ on 6 benchmark datasets | ✅ but expensive | |
| | **License** | Apache 2.0 | Often restrictive | |
|
|
| Stop renting GPUs for forecasting. Train on your laptop. Deploy to a $35 Raspberry Pi. Get production forecasts in minutes. |
|
|
| ## 🏆 Benchmarks |
|
|
| | Dataset | MASE | sMAPE (%) | MAE | CRPS | |
| |---|---:|---:|---:|---:| |
| | **ETTh1** | **1.95** | 12.06 | 1.30 | 1.05 | |
| | **ETTh2** | **2.74** | 10.47 | 2.46 | 1.99 | |
| | **ETTm1** | **2.17** | 10.70 | 0.72 | 0.65 | |
| | **exchange_rate** | **7.44** | 1.72 | 0.011 | 0.014 | |
| | **electricity** | **1.29** | 4.76 | 158.30 | 175.24 | |
| | **traffic** | **0.81** | 24.00 | 0.004 | 0.003 | |
| | **Overall** | **2.73** | **10.62** | **27.13** | **29.83** | |
| |
| > Benchmarks on 6 standard datasets. **Overall MASE improved 21%** from v0.2 (3.45 → 2.73). |
| > See [GitHub](https://github.com/eulogik/NanoForecast) for full results on 3 model sizes. |
| |
| ## 📦 Quick Start |
| |
| ```bash |
| pip install nanoforecast |
| ``` |
| |
| ```python |
| import numpy as np |
| from nanoforecast import NanoForecast |
| |
| model = NanoForecast.from_pretrained("eulogik/nanoforecast-v03") |
| context = np.sin(np.linspace(0, 8*np.pi, 512)) + 0.1 * np.random.randn(512) |
| out = model.predict(context, horizon=48, freq=1) |
| print(out["forecast"].shape) # (48,) point forecast |
| ``` |
| |
| ### 🔄 Streaming Inference (Unique to NanoForecast) |
| |
| NanoForecast's DeltaNet RNN maintains a recurrent state across calls — **no other TS model does this**. |
| |
| ```python |
| result = model.predict(context, horizon=48, return_state=True) |
| state = result.pop("state") |
| |
| for new_val in incoming_data_stream: |
| result = model.predict_step(new_val, state, horizon=48) |
| print(result["forecast"][0, :5]) # updated forecast instantly |
| ``` |
| |
| Use it for: |
| - **Real-time IoT sensor monitoring** |
| - **Live financial tick data** |
| - **Interactive dashboards** |
| - **Edge devices with limited memory** |
|
|
| ## 🎯 Try It in 1 Click |
|
|
| [](https://huggingface.co/spaces/eulogik/nanoforecast) |
|
|
| Upload a CSV → get forecast + prediction intervals + decomposition. No code. No GPU. |
|
|
| ## 🧠 Model Details |
|
|
| | Attribute | Value | |
| |---|---| |
| | Profile | `d96-L8` | |
| | Parameters | **6,518,104** | |
| | Context length | **512** | |
| | Prediction length | **48** | |
| | Hidden dim / layers | 96 / 8 | |
| | Architecture | LongConv + DeltaNet RNN + Gated Router + MLP | |
| | Outputs | Point forecast + p10/p25/p50/p75/p90 quantiles | |
| | Decomposition | Trend + Seasonal + Residual | |
| | Export | ONNX FP32 + INT8 | |
| | Streaming | Stateful DeltaNet RNN | |
|
|
| ## ⚡ Training Details |
|
|
| | Attribute | Value | |
| |---|---| |
| | Datasets | ETTh1, ETTh2, ETTm1, exchange_rate, electricity, traffic | |
| | Synthetic records | 10,000 | |
| | Epochs | 200 | |
| | Best epoch | 147 | |
| | Val loss (best) | 0.2230 | |
| | Batch size | 128 | |
| | Learning rate | 3e-5 | |
| | Wall time | 42,144s (11.7h on Colab T4) | |
| |
| ## ✨ What Makes NanoForecast Special |
| |
| - **🪶 Featherweight**: 200K–6.5M params, not 200M+. Ships as a dependency, not an API call. |
| - **📡 Streaming native**: Feed one value at a time, get updated forecasts. Perfect for IoT and real-time data. |
| - **💻 Zero-GPU inference**: Runs on ARM, x86, RISC-V. Benchmarked at <50ms on Raspberry Pi 4. |
| - **📦 Single pip install**: `pip install nanoforecast` → ready in 30 seconds. |
| - **🏭 Production-grade**: ONNX export, Docker, FastAPI server all included. |
| - **📊 Full uncertainty**: 5 quantiles + prediction intervals + trend/seasonal decomposition. |
| - **🔌 HuggingFace native**: `from_pretrained` / `push_to_hub` — works like any HF model. |
|
|
| ## 🔧 Deploy Anywhere |
|
|
| ```bash |
| # FastAPI server |
| pip install nanoforecast fastapi uvicorn python-multipart |
| python3 deploy/fastapi_server.py |
| |
| # ONNX export (edge/IoT/browser) |
| pip install "nanoforecast[onnx]" |
| python3 -m nanoforecast.export.onnx_export \ |
| --checkpoint <dir> \ |
| --output nanoforecast.onnx |
| |
| # Docker |
| docker build -t nanoforecast . |
| docker run -p 8000:8000 nanoforecast |
| ``` |
|
|
| ## 📚 Pretrained Variants |
|
|
| | Model | Params | Size | Context | Best For | |
| |---|---|---|---|---| |
| | [nanoforecast-200k](https://huggingface.co/eulogik/nanoforecast-200k) | ~676K | 2.7 MB | 256 | Extreme edge / RPi Zero | |
| | [nanoforecast-500k](https://huggingface.co/eulogik/nanoforecast-500k) | ~1.6M | 6.4 MB | 256 | General purpose / mobile | |
| | **nanoforecast-v03** (you are here) | **~6.5M** | **26 MB** | **512** | Max accuracy / server | |
|
|
| ## 📄 Paper |
|
|
| Read the tech report: [`deploy/paper.tex`](https://github.com/eulogik/NanoForecast/blob/main/deploy/paper.tex) (LaTeX, 8 sections). |
|
|
| ## ⚠️ Known Limitations |
|
|
| - Modest accuracy vs. 200M+ param models (MASE 2.73 vs TimesFM ~0.72) |
| - Fixed context window (512 for v0.3) |
| - Univariate channels (no cross-channel attention) |
| - Training requires PyTorch (inference can be pure ONNX) |
|
|
| ## ❤️ Built by Eulogik |
|
|
| [](https://eulogik.com) |
|
|
| **Eulogik** builds deployable AI for the real world. We believe ML models should run on the hardware people actually have, not the hardware vendors want to sell. |
|
|
| - 🌐 [eulogik.com](https://eulogik.com) |
| - 🐙 [GitHub](https://github.com/eulogik/NanoForecast) |
| - 📦 [PyPI](https://pypi.org/project/nanoforecast/) |
|
|
| **Star the repo** ⭐ if you find this useful — it helps others discover NanoForecast! |
|
|
