README.md

---
license: mit
tags:
  - emflow
  - time-series
  - forecasting
  - energy
library_name: emflow
---

# emflow submission — example predictor

A **reference submission** for the [`emflow`](https://github.com/rebase-energy/emflow)
`swedish-temperatures:ar` benchmark. This is what a model submission should look
like: a single `submission.py` that defines an `emflow.Predictor` and exposes it as
a module-level `model`.

> 📌 For interns: copy `submission.py`, rename `ExamplePredictor`, and replace the
> `train` / `predict` bodies with your own model. Keep the same contract.

## The contract

`submission.py` just needs a module-level `emflow.Predictor` instance:

```python
model = MyModel()          # a FRESH, UNTRAINED model
```

(You can instead expose a `get_model() -> emflow.Predictor` factory — the verifier
accepts either form.)

Your `emflow.Predictor` subclass implements:

- **`train(self, train_df)`** — fit on the wide temperature DataFrame (hourly UTC
  index, one column per station). Use only what's passed.
- **`predict(self, input_df)`** — return a DataFrame/Series whose entry at the
  **last timestamp** of `input_df` is your 1-step-ahead forecast for that hour.
  Use only past lags; the value at the last timestamp is intentionally `NaN`.

## How it's scored (leak-proof)

The evaluator **trains your model itself** on the official pre-2026 split, then
scores it with **strict walk-forward** on the held-out 2026 hours: to forecast
hour `t`, the model sees only the series strictly before `t`. You never see the
test targets and cannot train on them, so the score can't be inflated by leakage.

This example model — a least-squares AR on the last 3 hours — scores
**MAE ≈ 0.29 °C**, comfortably beating the persistence baseline (≈ 0.31 °C).

## Verify it

```bash
# from a clone of emflow, with the submissions extra installed
uv sync --extra submissions

# straight from this repo on the Hub (pin a commit for reproducibility)
python scripts/verify_submission.py hf://rebase-energy/emflow-submission-example/submission.py \
    --revision <commit-sha>
```

Or locally: drop `submission.py` into `submissions/` and run
`python scripts/verify_submission.py submissions/submission.py`.