Document model architecture and validated weights

README.md

@@ -0,0 +1,51 @@
+---
+tags:
+- trajectory-forecasting
+- spatiotemporal-transformer
+- pytorch
+---
+
+# Spatiotemporal Decoder for Fortnite Duo Replays
+
+This is an experimental 60-second team-centroid movement forecast model trained on supported Fortnite duo server replays. It is a custom PyTorch architecture, not a Transformers `from_pretrained` model. The matching parser, tensorizer, encoder, decoder, training, and evaluation source are distributed in the companion public source release under `github-spatiotemporal-decoder`.
+
+## Architecture and data
+
+Five-second replay snapshots become 256-dimensional team states. Two spatial attention layers model living teams at each tick; four causal temporal layers use observed ticks. A four-layer parallel decoder predicts 12 five-second horizons and five Gaussian route modes. Targets are current-centroid-relative coordinates on a fixed 32 x 32 engineered model grid.
+
+Training used 1,150 accepted pilot sessions: 920 train, 115 validation, and 115 reserved test. Every accepted session has data warnings and incomplete tournament provenance. The reserved decoder-test split was not evaluated.
+
+## Files
+
+| File | Purpose | SHA-256 |
+| --- | --- | --- |
+| [`encoder_state.pt`](encoder_state.pt) | Frozen encoder tensor dictionary, 124 tensors | `b4c66614d08dbf1c4e4ad6b2cafb78a939d87e17a270dc9801bcac78329d80ee` |
+| [`decoder_state.pt`](decoder_state.pt) | Decoder and congestion tensor dictionary, 135 tensors | `7c89d654d6c356ffcb5696452b8ede3afd20f9c7d327002fe36e929930eb4126` |
+| [`best.pt`](best.pt) | Original epoch-20 decoder training checkpoint, including optimizer state | `7e210adfb5453511dd4cda35c1db968245921f8e08848fa51dfb035eaa07adc6` |
+
+The tensor-only exports have been reloaded with PyTorch's `weights_only=True` mode and match the tensor-state digests embedded in the original encoder and decoder checkpoints. [`model_weights.json`](model_weights.json) records the source checkpoint and state hashes.
+
+```python
+import torch
+from huggingface_hub import hf_hub_download
+
+repo = "BiLSTM/SpatioTemporalDecoder"
+encoder_state = torch.load(
+    hf_hub_download(repo, "encoder_state.pt"),
+    map_location="cpu",
+    weights_only=True,
+)
+decoder_state = torch.load(
+    hf_hub_download(repo, "decoder_state.pt"),
+    map_location="cpu",
+    weights_only=True,
+)
+```
+
+The dictionaries require the matching source code and model configuration to run inference. Load the encoder dictionary into `SpatiotemporalEncoder` with strict state loading; load the decoder dictionary through `load_downstream_state` after constructing the matching `ParallelTrajectoryModel`. The original `best.pt` is a Python pickle based training checkpoint and should be loaded only from a trusted source.
+
+## Measured validation result
+
+The epoch-20 checkpoint was selected by lowest validation route-mixture negative log-likelihood, 7.0043 across 3,680 queries and 42,265 valid future points. Its highest-probability route mean had 75.128 m average displacement error and 127.725 m final displacement error at 60 seconds on the 115-session validation split. Static-position baselines measured 80.124 m and 143.711 m respectively. The loss was still decreasing at the configured 20-epoch endpoint.
+
+These are development-validation measurements. They do not establish new-tournament generalization, optimal rotations, or production readiness. The raw replays and private decoded corpus are not included.