Skip to content

API reference

This section indexes the current source code. It is not a stable public SDK. GenRec is a research repository: most models, data adapters, and trainers evolve independently, and there is no shared BaseModel, BaseDataset, DatasetFactory, or BaseTrainer.

Need Page Source
Dataset classes and sample schemas Datasets genrec/data/
Shared split and sequence contracts Sequence data contracts evaluation_protocol.py, schemas.py
Gin configuration and CLI overrides Configuration and CLI parse_config, config/
Layers, losses, and metrics Shared modules genrec/modules/
Real preprocessing entry points Processing data-module helpers and scripts/
Choosing or injecting a dataset Data routing direct construction or Gin dataset=@ClassName
Train functions and artifacts Trainers genrec/trainers/
RQ-VAE return types RQ-VAE API genrec/models/rqvae.py
TIGER tokens and generation TIGER API genrec/models/tiger.py

Model modules

There are eleven implementation modules under genrec/models. RQ-VAE and RQ-KMeans are tokenizer/quantizer components, not standalone recommenders.

Module / main class Model page
sasrec.py / SASRec SASRec
hstu.py / HSTU HSTU
rqvae.py / RqVae RQ-VAE, API
rqkmeans.py / RqKmeans RQ-KMeans
tiger.py / Tiger TIGER, API
lcrec.py / LCRec LCRec
cobra.py / Cobra COBRA
onerec.py / OneRec OneRec
rpg.py / RPGModel RPG
notellm.py / Query2Embedding NoteLLM
gram.py / GRAM GRAM

genrec.models re-exports RqVae, QuantizeForwardMode, Tiger, SASRec, HSTU, LCRec, Cobra, and GRAM. Import the other classes from their implementation modules:

from genrec.models.onerec import OneRec
from genrec.models.rpg import RPGModel
from genrec.models.notellm import Query2Embedding
from genrec.models.rqkmeans import RqKmeans

genrec.data only re-exports the shared sequence named tuples and cycle; dataset classes should also be imported from their concrete modules.

Cross-model contracts that actually exist

  • A dataset follows PyTorch's __len__/__getitem__ protocol; its item schema must match the selected trainer's collator.
  • Trainer entry points call parse_config() and accept one Gin file, --split, and repeatable --gin bindings.
  • Several item/SID evaluators share TopKAccumulator and SemanticIdItemMapper.
  • Most trainers write results.json through save_run_results, but checkpoint names and payloads are intentionally heterogeneous.

Do not assume that an argument supported by one trainer is supported by another. Inspect both the target @gin.configurable function and its .gin file.

Static verification

rg -n '^class |^def |^@gin.configurable' genrec/models genrec/data genrec/modules genrec/trainers
rg -n 'train\.|train_[a-z]+\.' config

See also model selection, architecture, and the implementation status.