# Retail World Model

A transformer-based world model for retail sales prediction, trained on the Favorita store sales dataset.

## Architecture

- **Encoder**: T5 Encoder processes historical retail time-series
- **Latent Dynamics**: LSTM-based world model that imagines future states
- **Decoder**: Predicts future sales with probabilistic forecasting (mean + variance)
- **Fine-tuning**: LoRA adapters on encoder attention layers

## Features

- **Context Window**: 60 days of historical sales data
- **Prediction Horizon**: 14 days of future sales forecasts
- **Inputs**: Sales history, promotion flags, day-of-week, month, product family
- **Output**: Probabilistic predictions with 90% confidence intervals

## Usage

### Training
```bash
python train_v4.py
```

### Inference
```bash
python inference.py --checkpoint /path/to/model --history history.csv --output predictions.csv
```

## Dataset

- **Source**: [t4tiana/store-sales-time-series-forecasting](https://huggingface.co/datasets/t4tiana/store-sales-time-series-forecasting)
- **Stores**: 54 Favorita stores in Ecuador
- **Product Families**: 33 product categories
- **Records**: ~3M daily sales records (2013-2017)

## Model

- **Base**: T5 Encoder (tiny)
- **Parameters**: ~30M base + LoRA adapters
- **Loss**: Negative log-likelihood (probabilistic forecasting)

## References

- Chronos-2: Universal Time Series Forecasting (Amazon Science)
- iTransformer: Inverted Transformers for Time Series (NeurIPS 2023)
- TabFormer: Tabular Transformers for Sequential Data (IBM Research)