Upload README.md

README.md

@@ -0,0 +1,48 @@
+# 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)