Add LETTER model for Semantic ID recommender

[hieuddo]

Description

This PR integrates LETTER (Learnable Item Tokenization for Generative Recommendation) into cornac as an extension of TIGER. LETTER retains TIGER's RQ-VAE Semantic-ID and T5 generation pipeline, and it aligns the quantized content representation of each item with a fixed item embedding from a separately pretrained collaborative filtering model using an InfoNCE-style contrastive loss. The released recipe uses 32-dimensional SASRec item embeddings.

Key changes

• Implemented LETTER as an extension of TIGER
• Added the released defaults and the Beauty reproduction configuration.

Verification and tuning

The original paper uses LLaMa-7B instead of the common Sentence-T5 or OpenAI's text-embedding-large-3, so we verified both stages (codebook and seq2seq) separately.

• For the tokenizer, initial assignments and collision handling matched exactly; the first matched optimization step produced identical IDs and losses, with a maximum parameter difference of 1.86e-9. I.e., the behavior of the tokenizer from cornac and the original implementation is identical.
• For the generator, we evaluated the Cornac LETTER-TIGER implementation with both locally learned (Setence-T5) and author-provided Semantic IDs.

	R@5	N@5	R@10	N@10
TIGER - original paper	0.0454	0.0321	0.0648	0.0384
TIGER - LETTER reimplementation	0.0395	0.0262	0.0610	0.0331
LETTER-TIGER - LETTER paper	0.0431	0.0286	0.0672	0.0364
Released code + author IDs	0.0413	0.0268	0.0645	0.0343
Cornac + Sentence-T5 / RQ-VAE	0.0356	0.0241	0.0560	0.0307
Cornac + author IDs	0.0429	0.0282	0.0670	0.0360

Setting: Amazon Beauty 2014 5-core, chronological leave-last-out, and seed=42. The end-to-end run uses Sentence-T5 content embeddings and 32-dimensional item embeddings from a locally trained SASRec. The released Beauty tokenizer recipe uses cf_weight=0.1, diversity_weight=1e-4, and 10,000 RQ-VAE epochs.

With the authors' IDs, the Cornac generator is within 0.0002 to 0.0004 of all reported paper metrics, so that comparison is close and direct. The end-to-end Sentence-T5 result is not an exact paper reproduction because the authors did not release their tokenizer checkpoint, content embeddings, or SASRec checkpoint; it is included as a fully runnable reference.

Comparative context

Within the LETTER paper's experimental pipeline, LETTER-TIGER improves over its TIGER reimplementation by approximately 9–10% across the four reported Beauty metrics. However, that TIGER baseline is weaker than the result reported in the original TIGER paper. LETTER-TIGER remains below the original TIGER result on R@5, N@5, and N@10, while exceeding it on R@10.

This cross-paper comparison is not fully controlled: the original TIGER paper uses Sentence-T5 embeddings, whereas the LETTER paper uses LLaMA-7B content embeddings and a different tokenizer-training recipe. Because the LETTER authors did not release their tokenizer checkpoint, content embeddings, or SASRec checkpoint, the current reproduction validates the released implementation and generator with author-provided IDs, but cannot isolate the recommendation gain attributable to LETTER's collaborative and diversity regularization against a well-reproduced TIGER baseline.

Checklist:

• I have updated the documentation accordingly.
• I have updated README.md (if you are adding a new model).
• I have updated examples/README.md (if you are adding a new example).

[qtuantruong]

content and cf_embeddings are constructed in sorted item_ids order. Cornac’s global item indices, however, are assigned by first appearance in the interaction data. FeatureModality(..., ids=item_ids) correctly remaps the content vectors, but cf_embeddings is passed directly and is never remapped. With actual SASRec embeddings, the collaborative loss therefore aligns each item’s semantic representation with another item’s CF vector, invalidating tokenizer training and resulting metrics.

can we check if this is correct/intended alignment? Don't want it to be a hack, we might need to make some changes for better design

[hieuddo]

Thanks for catching this.

We fixed this in recom_letter.py by requiring cf_embedding_ids alongside cf_embeddings. LETTER now uses those raw IDs to remap every CF embedding row to Cornac’s global item index during fitting, matching the remapping already performed by FeatureModality for content features.

The example intentionally keeps item_ids sorted for deterministic/reproducible feature construction. Sorted order is only the external row order: the same item_ids are passed to both FeatureModality(ids=...) and LETTER(cf_embedding_ids=...), so content and CF embeddings are independently remapped to Cornac’s internal order before tokenizer training.

I also verified that the previous experiment pipeline explicitly remapped the SASRec embeddings to Cornac indices, so those runs were correctly aligned, and reproducible results still stand.

[qtuantruong]

nit: I don't think we have this test file

[hieuddo]

Just added the example file to reproduce Cornac + author IDs results on Beauty dataset; and adopted the original implementation re optimizer using Hugging Face Trainer's AdamW decay