FrameLanguageLM

A language model where tokens are movies and TV series — trained on 32M viewing sequences to predict "the next film you'd love."

Model Description

• Architecture: gSASRec (2-layer transformer, d=256, gBCE loss) with compositional embeddings
• Vocabulary: ~100k titles (movies + TV series) selected by IMDb numVotes
• Training data: MovieLens 32M sequences, enriched with IMDb/TMDB metadata
• Cold-start: ID-dropout (p=0.2) enables recommendation of unseen titles via metadata-only embeddings
• Dual serving: warm checkpoint (54k items with collaborative signal) + full checkpoint (100k including cold items)

Performance

Metric	Warm (feat)	Full (feat_iddrop)
TEST NDCG@10	0.1174	0.1110
TEST Recall@10	0.2164	0.2066
TEST Recall@50	0.4630	0.4511
Cold-start NDCG@10	—	0.0846 (63.7% of warm)

Full ranking evaluation (no candidate sampling), leave-one-out temporal split. Total training cost: ~$1.25 (RTX 3090).

How to Use

# Install the CLI
pip install frame-language-lm

# Import your FilmAffinity profile (auto-downloads model on first run)
frame-language-lm import --filmaffinity export.zip

# Get your gaps — movies you'd love but haven't seen
frame-language-lm gaps --top 50

# Check if a specific title is worth watching for you
frame-language-lm worth "Stalker"

# Find similar titles
frame-language-lm similar "Mulholland Drive"

# Search the catalog with filters
frame-language-lm search --director "Park Chan-wook" --country KR

Files in this Repository

File	Size	Description
model_fp32.onnx + .data	~56 MB	Warm checkpoint (54k items with signal)
model_full_fp32.onnx + .data	~101 MB	Full checkpoint (100k items, ID-dropout)
item_embeddings.npy	~53 MB	Warm item embedding matrix
item_embeddings_full.npy	~98 MB	Full item embedding matrix
full_aux.npz	~0.2 MB	Cold-start flags (is_cold, is_movie, etc.)
catalog.sqlite	~36 MB	Complete catalog with metadata
vocab_map.json	~1 MB	Warm vocabulary mapping (tconst ↔ index)
full_vocab_map.json	~2 MB	Full vocabulary mapping
feature_vocabs.json	~2.4 MB	Compositional feature vocabularies
meta.json / meta_full.json	<1 KB each	Model configuration

Training Data & Licenses

• MovieLens 32M: F. Maxwell Harper and Joseph A. Konstan. 2015. The MovieLens Datasets: History and Context. ACM Transactions on Interactive Intelligent Systems (TiiS) 5, 4, Article 19. Non-commercial use; redistribution of transformations under same conditions.
• IMDb Non-Commercial Datasets: Personal and non-commercial use only. developer.imdb.com
• TMDB API: Metadata enrichment (country, language, budget). This product uses the TMDB API but is not endorsed, certified, or otherwise approved by TMDB.

Limitations

• Trained on MovieLens (predominantly US/English mainstream cinema) — recommendations biased toward popular Western titles
• MovieLens ends Oct 2023 — post-2023 titles are cold-start only
• Series recommendations are metadata-based (no collaborative signal) — lower quality than films
• Budget feature: only 20-40% coverage in TMDB

Ethical Considerations

• No user data is collected or transmitted — all inference runs locally
• Model cannot recover individual user viewing histories from training data
• Recommendations reflect statistical patterns in viewing behavior, not quality judgments

Data Provenance & Takedown

This model was trained on publicly available, non-commercial datasets:

Source	Data used	License	How to verify
MovieLens 32M	User viewing sequences	Custom (non-commercial, redistribution OK)	grouplens.org
IMDb Non-Commercial	Titles, genres, directors, cast, year	Custom (personal/non-commercial)	developer.imdb.com
TMDB API	Country, language, budget (compositional features)	TMDB API ToS	themoviedb.org

For convenience, this repository includes a pre-built catalog (catalog.sqlite) containing metadata derived from IMDb and TMDB. If any rights holder objects to the inclusion of this catalog, it will be removed and users can rebuild it locally using the provided scripts/build_catalog.py script. Model weights are a mathematical transformation that cannot reconstruct the original training data.

Takedown requests: if you are a rights holder and believe any artifact in this repository infringes on your terms, please contact peportmel@gmail.com. We will respond within 72 hours and can remove the affected artifact or retrain the model excluding your data source at negligible cost (~$0.30, ~90 minutes of GPU time).