readme

README.md

@@ -1,3 +1,145 @@
 ---
 license: mit
+library_name: pytorch
+pipeline_tag: graph-ml
+datasets:
+- wzehui/Yelp-Multimodal-Recommendation
+language:
+- en
+tags:
+- POI
+- recommendation
+- recommender-system
+- GNN
+- graph-neural-network
+- LightGCN
+- contrastive-learning
+- yelp
+- arxiv:2608.16407
 ---
+
+# LLM-MGCL: Checkpoints
+
+Trained checkpoints for **LLM-MGCL**, from the paper
+[*POI Recommendation with LLM-Augmented Multi-Graph Learning and Contrastive Alignment*](https://arxiv.org/abs/2608.16407)
+(Tamer, Höpken, Wang, 2026).
+
+Code: **[GitHub](<GITHUB-URL>)**
+
+## Model
+
+LLM-MGCL extends LightGCN with two item-item views and aligns them with contrastive learning:
+
+| Graph | Edges | Edge weight |
+|---|---|---|
+| **G_UI** | user-item training interactions | star rating `(stars − 1) / 4`, clamped at 0.1 |
+| **G_SEM** | top-10 most similar items within 50 km | cosine similarity of LLM-generated photo summaries (`all-MiniLM-L6-v2`) |
+| **G_GEO** | top-10 nearest items within 50 km | `1 / (1 + distance_km)` (Haversine) |
+
+The three graphs are propagated in parallel with LightGCN (3 / 2 / 2 layers) from shared
+64-dimensional ego embeddings, and the item views are fused additively. Training uses BPR,
+L2 regularisation (1e-3) and a bidirectional InfoNCE loss between the collaborative view and the
+semantic and geographic views (λ = 0.05, τ = 0.2).
+
+## Contents
+
+All models were trained with seeds **42, 123 and 2024**, so there are 3 checkpoints per run.
+
+| Run | Description |
+|---|---|
+| LLM-MGCL | full model |
+| LLM-MGCL w/o CL | ablation: λ = 0 |
+| LLM-MGCL w/o G_SEM | ablation: semantic view removed |
+| LLM-MGCL w/o G_GEO | ablation: geographic view removed |
+| LightGCN, SGL, NGCF, GC-MC, NeuMF, MF-BPR | baselines |
+
+ItemKNN and UserKNN have no weights. The code computes them deterministically.
+
+Each `.pt` file is a dict containing `model_state` (a PyTorch `state_dict`), `model_config` and
+`seed`. These are raw PyTorch weights, not a `transformers` model. Load them with the model
+classes from the GitHub repository.
+
+## Results
+
+Yelp Multimodal Recommendation dataset, full-ranking evaluation on the test split, mean ± std over 3 seeds:
+
+| Model | Recall@20 | NDCG@20 |
+|---|---|---|
+| **LLM-MGCL** | **0.1163 ± 0.0049** | **0.0705 ± 0.0012** |
+| LightGCN | 0.0763 ± 0.0022 | <…> |
+
+For all models and metrics see Table 1 of the paper.
+
+## Usage
+
+The checkpoints only work with the graphs and id mappings produced by the repository's
+preprocessing, because user and item indices must match. Build them first, then download the
+checkpoints and evaluate:
+
+```bash
+git clone <GITHUB-URL> && cd llm-mgcl
+pip install -e .
+python scripts/build_graphs.py                       # split, id mapping, G_UI / G_SEM / G_GEO
+
+huggingface-cli download bbbur/LLM-MGCL --local-dir hf_checkpoints
+python scripts/import_colab_checkpoints.py --src hf_checkpoints
+
+python scripts/compare_models.py                     # Table 1, ablation, significance tests
+python scripts/cold_start.py                         # cold-start analysis
+```
+
+Loading a single model in Python:
+
+```python
+from huggingface_hub import hf_hub_download
+import torch
+from llm_mgcl.models import build_model
+from llm_mgcl.pipeline import load_dataset
+from llm_mgcl.utils import load_config, get_device
+
+cfg, device = load_config("configs/default.yaml"), get_device()
+ds = load_dataset(cfg, device)
+
+path = hf_hub_download("bbbur/LLM-MGCL", "<path/to/llm_mgcl_geo_seed42.pt>")
+model = build_model("llm_mgcl", ds.data.n_users, ds.data.n_items, cfg).to(device)
+model.load_state_dict(torch.load(path, map_location=device, weights_only=False)["model_state"])
+model.eval()
+
+scores = model.scorer(ds.graphs)(torch.tensor([0], device=device))   # [1, n_items]
+```
+
+## Training data
+
+[wzehui/Yelp-Multimodal-Recommendation](https://huggingface.co/datasets/wzehui/Yelp-Multimodal-Recommendation).
+Users with fewer than 3 reviews are removed. Each user's interactions are split 80 / 10 / 10 into
+train / validation / test (`random_state=42`). The models were trained with Adam (lr 1e-3),
+StepLR (step 20, γ 0.5) and batch size 2048 for up to 100 epochs. Early stopping is based on
+validation Recall@20 (evaluated every 2 epochs, patience 8 evaluations).
+
+## Limitations
+
+* The models are transductive. They only score users and items seen during training, with the
+  exact id mapping of the preprocessing.
+* They were trained and evaluated on Yelp only, and results may not transfer to other cities,
+  platforms or domains.
+* The semantic graph depends on LLM-generated photo summaries. Items without photos have no
+  semantic neighbours.
+
+## Citation
+
+```bibtex
+@article{tamer2026llmmgcl,
+  title         = {POI Recommendation with LLM-Augmented Multi-Graph Learning and Contrastive Alignment},
+  author        = {Tamer, Burak and H{\"o}pken, Wolfram and Wang, Zehui},
+  journal       = {arXiv preprint arXiv:2608.16407},
+  year          = {2026},
+  eprint        = {2608.16407},
+  archivePrefix = {arXiv},
+  primaryClass  = {cs.IR},
+  url           = {https://arxiv.org/abs/2608.16407}
+}
+```
+
+## License
+
+MIT. Use of the Yelp data is subject to Yelp's dataset terms.