Skip to content

GenRec

GenRec is a PyTorch and Gin-config research framework for generative recommender systems. It is built for paper reproduction, auditable comparisons, and experimentation—not for production serving.

Documentation authority

The Chinese site is the canonical implementation documentation. English pages cover the main entry points; when an English page is missing, the i18n site falls back to Chinese. “Implemented,” “end-to-end verified,” and “paper result reproduced” are separate statuses; see Implementation and reproduction status.

Start here

Goal Recommended path
Run the project Getting started → Installation
Understand the code Architecture → Repository map
Choose an implemented model Model overview → model pages
Study methods not yet implemented GenRec landscape → model catalog
Run comparable experiments Evaluation system → reproducibility
Extend the repository Extension guide → contributing

What is implemented

The repository currently contains 9 recommenders and 2 semantic-ID/tokenizer components. A component is not counted as a recommender unless it performs the recommendation task after training.

Family Implementations Representation / prediction
Discriminative sequential baselines SASRec, HSTU one item ID; full-catalog ranking
RQ semantic-ID recommenders TIGER, LCRec, COBRA, OneRec multi-level codes; OneRec includes SFT, alternative CLM, and GRPO paths
Other generative / LLM routes RPG, NoteLLM, GRAM parallel code heads, dense text retrieval, or lexical IDs with multi-granularity fusion
Representation components RQ-VAE, RQ-KMeans item embedding → discrete semantic ID; not recommenders by themselves

The model catalog also documents major unimplemented directions—generative retrieval, LLM recommendation, discrete tokenizers, diffusion recommenders, hybrid systems, and recommendation reasoning/RL—with implementation status and primary references.

How the system fits together

flowchart LR
    A[Interactions and metadata] --> B[Preparation and split]
    B --> C[Model-specific Dataset / Collator]
    A --> D[Item text or pretrained embedding]
    D --> E[RQ-VAE / RQ-KMeans / OPQ]
    E --> C
    C --> F[Trainer + Gin config]
    F --> G[Checkpoint and result artifacts]
    G --> H[Item resolution, deduplication, metrics]

Models do not inherit from a common dataset, model, processor, or trainer hierarchy. Shared contracts come from CLI/Gin entry points, data fields, result artifacts, and evaluation protocol. See Training system and Data pipeline.

Minimal run

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

python scripts/prepare_amazon2014.py \
  --splits beauty --kinds reviews meta

python genrec/trainers/sasrec_trainer.py \
  config/sasrec/amazon.gin --split beauty

Models that consume semantic IDs require a matching tokenizer checkpoint first. For TIGER:

python genrec/trainers/rqvae_trainer.py \
  config/tiger/amazon/rqvae.gin --split beauty

python genrec/trainers/tiger_trainer.py \
  config/tiger/amazon/tiger.gin --split beauty

See Getting started for all pipelines and the command index for verified entry points.

Completed matrix (2026-10-22)

The snapshot contains 162 item-level cells / 54 complete three-seed rows. Values below are R@10 mean ± population standard deviation (seeds 42/43/44). See BENCHMARKS.md for all metrics, exact per-seed provenance and archived recipe comparisons. Sequence history is 50 except LCRec (20); this is not a length-matched matrix.

Leave-one-out

Model Beauty R@10 Sports R@10 Toys R@10
SASRec (CE) 0.0858 ± 0.0002 0.0497 ± 0.0005 0.0917 ± 0.0007
HSTU (CE) 0.0727 ± 0.0008 0.0384 ± 0.0011 0.0686 ± 0.0007
TIGER (matrix recipe) 0.0568 ± 0.0010 0.0342 ± 0.0017 0.0477 ± 0.0004
LCRec (4B, seq20, gb128) 0.0729 ± 0.0004 0.0399 ± 0.0005 0.0705 ± 0.0041
COBRA (optimized light) 0.0454 ± 0.0006 0.0290 ± 0.0007 0.0412 ± 0.0007
RPG (direct) 0.0732 ± 0.0007 0.0426 ± 0.0007 0.0820 ± 0.0003
NoteLLM (GCL+CSFT, I2I) 0.0693 ± 0.0004 0.0351 ± 0.0003 0.0917 ± 0.0005
OneRec SFT (3 SID) 0.0658 ± 0.0016 0.0341 ± 0.0007 0.0591 ± 0.0004
OneRec + GRPO (selected) 0.0661 ± 0.0024 0.0341 ± 0.0005 0.0604 ± 0.0013

Global temporal

Model Beauty R@10 Sports R@10 Toys R@10
SASRec (CE) 0.0166 ± 0.0010 0.0189 ± 0.0008 0.0179 ± 0.0005
HSTU (CE) 0.0163 ± 0.0006 0.0192 ± 0.0007 0.0165 ± 0.0005
TIGER (matrix recipe) 0.0206 ± 0.0013 0.0205 ± 0.0021 0.0184 ± 0.0020
LCRec (4B, seq20, gb128) 0.0208 ± 0.0025 0.0207 ± 0.0007 0.0209 ± 0.0011
COBRA (optimized light) 0.0175 ± 0.0007 0.0221 ± 0.0006 0.0190 ± 0.0007
RPG (direct) 0.0173 ± 0.0004 0.0182 ± 0.0002 0.0226 ± 0.0004
NoteLLM (GCL+CSFT, I2I) 0.0266 ± 0.0013 0.0192 ± 0.0005 0.0263 ± 0.0009
OneRec SFT (3 SID) 0.0239 ± 0.0014 0.0220 ± 0.0007 0.0208 ± 0.0003
OneRec + GRPO (selected) 0.0245 ± 0.0018 0.0223 ± 0.0004 0.0208 ± 0.0005

OneRec remains 3-code; the 4-code variant is a separate Beauty ablation. The GRPO row includes validation fallback to SFT (16/18 cells). Evaluation prompt templates are not frozen, so small SFT/GRPO differences are not evidence of RL gains. NoteLLM is I2I retrieval with the query item excluded. These rows verify repository adaptations, not parity with every original paper.

Home extension

The separate Home extension finished on 2026-10-31: 54/54 cells and 18 three-seed rows, bringing published coverage to 216 cells / 72 rows. The table uses the same item-level and population-standard-deviation convention.

Model LOO R@10 Global temporal R@10
SASRec (CE) 0.0280 ± 0.0002 0.0098 ± 0.0006
HSTU (CE) 0.0197 ± 0.0001 0.0107 ± 0.0008
TIGER (matrix recipe) 0.0194 ± 0.0004 0.0123 ± 0.0001
LCRec (4B, seq20, gb128) 0.0270 ± 0.0005 0.0102 ± 0.0008
COBRA (optimized light) 0.0152 ± 0.0003 0.0089 ± 0.0003
RPG (direct) 0.0061 ± 0.0007 0.0075 ± 0.0014
NoteLLM (GCL+CSFT, I2I) 0.0272 ± 0.0002 0.0083 ± 0.0001
OneRec SFT (3 SID) 0.0211 ± 0.0001 0.0094 ± 0.0005
OneRec + GRPO (selected) 0.0210 ± 0.0003 0.0098 ± 0.0004

All six Home GRPO selections retain SFT. RPG transfers the Beauty recipe; no Home four-code ablation was run. Raw paths, commands and source/config hashes: Home evidence.

Rules for reading results

  • A generated SID tuple is not necessarily a unique item. Resolve collisions using training-only SID→item statistics, deduplicate items, then compute headline metrics.
  • Recall/NDCG from different splits, candidate sets, negative-sampling schemes, decoding budgets, or evaluation levels are not directly comparable.
  • A source implementation does not prove that its paper configuration or result has been reproduced. Check the checkpoint, log, data fingerprint, source provenance, and metric level.
  • Historical TIGER, LCRec, and OneRec SID-tuple results may be collision-inflated. Public comparisons should use revalidated item-level artifacts.

The current snapshot and protocol notes live in BENCHMARKS.md.

Project boundary

GenRec does not promise the latency, security, multi-tenancy, online feature consistency, or rollout controls required for serving. See Inference and deployment boundaries. The project is MIT licensed; contribution requirements are in the contributing guide.