Building a Movie Recommendation Engine with Hugging Face and Voyage AI

This guest blog post is from Arek Borucki, Machine Learning Platform & Data Engineer for Hugging Face - a collaboration platform for the machine learning community. The Hugging Face Hub works as a central place where anyone can share, explore, discover, and experiment with open-source ML. HF empowers the next generation of machine learning engineers, scientists, and end users to learn, collaborate and share their work to build an open and ethical AI future together. With the fast-growing community, some of the most used open-source ML libraries and tools, and a talented science team exploring the edge of tech, Hugging Face is at the heart of the AI revolution.

Traditional movie search relies on filtering by genre, actor, or title. But what if you could search by how you feel? Imagine typing:

"something uplifting after a rough day at work"

"a movie that will make me cry"

"I need adrenaline, can't sleep anyway"

"something to watch with grandma who hates violence"

This is mood-based semantic search: matching your emotional state to movie plot descriptions using AI embeddings.

In this tutorial, you will build a mood-based movie recommendation engine using three powerful technologies: voyage-4-nano (a state-of-the-art open-source embedding model), Hugging Face (for model and dataset hosting), and MongoDB Atlas Vector Search (for storing and querying embeddings at scale).

Why mood-based search?

Genre tags are coarse. A "drama" can be heartwarming or devastating. A "comedy" can be light escapism or dark satire. Traditional filters cannot capture these nuances.

Semantic search solves this by understanding meaning. When you search for "feel-good movie for a rainy Sunday", the system doesn't look for those exact words. It understands the intent and matches it against plot descriptions that evoke similar feelings.

Architecture overview

The system combines three components from the Hugging Face ecosystem with MongoDB:

voyage-4-nano (Hugging Face Hub): Converts text to embeddings (up to 2048 dimensions, we use 1024)

MongoDB/embedded_movies(Hugging Face Datasets): 1500+ movies with plot summaries, genres, cast

MongoDB Atlas Vector Search: Stores embeddings and performs similarity search

Understanding voyage-4-nano

voyage-4-nano is the smallest model in Voyage AI's latest embedding series, released with open-weights under the Apache 2.0 license. Voyage AI was acquired by MongoDB, and the Voyage 4 series models are now available through MongoDB Atlas. All models in the series (voyage-4-large, voyage-4, voyage-4-lite, and voyage-4-nano) produce compatible embeddings in a shared embedding space, allowing you to mix and match models within a single use case.

Although voyage-4-nano natively supports embeddings up to 2048 dimensions, we deliberately truncate them to 1024 dimensions using its Matryoshka embedding property. In practice, this provides a strong balance between semantic quality, storage efficiency, and vector search latency, while preserving stable ranking behavior.

Sentence Transformers

This tutorial uses Sentence Transformers, a Python library built on top of Hugging Face Transformers. It is specifically designed for working with embedding models and provides a simple API for generating text embeddings.

Why Sentence Transformers instead of raw Transformers? When working with embedding models, you need to handle tokenization, pooling, normalization, and prompt formatting. Sentence Transformers does all of this automatically in a single method call. The code is cleaner, there are fewer potential errors, and you get built-in features like batch processing with progress bars.

Under the hood, Sentence Transformers still uses Hugging Face Transformers to load and run the model.

Configure the development environment

Let's get started!

Create the Project Structure

Code Snippet

Install dependencies

Create the requirements.txt file:

Code Snippet

Create a Python virtual environment and install dependencies:

Code Snippet

Run MongoDB Atlas locally

Use Atlas CLI to create a local deployment with Vector Search support:

Code Snippet

Choose local when prompted. Once ready, you'll receive a connection string like:

Code Snippet

Configure environment variables

Create the .env file:

Code Snippet

I use 1024 dimensions as a balance between retrieval quality and storage efficiency. You can experiment with 2048 (max retrieval quality) or 512 (faster queries).

Implement system components

Database module

The database module manages MongoDB connections and creates the vector search index. The index must match the embedding dimensions specified in our configuration.

Code Snippet

cat <<'EOF' > src/database.py
import os
from pymongo import MongoClient
from pymongo.operations import SearchIndexModel
from dotenv import load_dotenv

load_dotenv()

class MongoManager:
    def __init__(self):
        self.client = MongoClient(os.getenv("MONGO_URI"))
        self.db = self.client[os.getenv("DB_NAME")]
        self.collection = self.db[os.getenv("COLLECTION_NAME")]
        self.embedding_dim = int(os.getenv("EMBEDDING_DIM", 1024))
    
    def get_collection(self):
        return self.collection
    
    def create_vector_index(self):
        """Creates a Vector Search index for mood-based queries"""
        search_index_model = SearchIndexModel(
            definition={
                "fields": [
                    {
                        "type": "vector",
                        "path": "plot_embedding",
                        "numDimensions": self.embedding_dim,
                        "similarity": "cosine"
                    },
                    {
                        "type": "filter",
                        "path": "genres"
                    },
                    {
                        "type": "filter", 
                        "path": "year"
                    }
                ]
            },
            name="mood_search_index",
            type="vectorSearch"
        )
        try:
            self.collection.create_search_index(model=search_index_model)
            print(f"Vector index created with {self.embedding_dim} dimensions.")
        except Exception as e:
            print(f"Index status: {e}")
EOF

AI module with voyage-4-nano

The AI module loads voyage-4-nano from Hugging Face Hub and provides methods for generating embeddings. We use the sentence-transformers library for a clean API.

Code Snippet

cat <<'EOF' > src/ai.py
import os
import torch
from sentence_transformers import SentenceTransformer
from dotenv import load_dotenv

load_dotenv()

class MoodEmbedder:
    def __init__(self):
        model_name = os.getenv("MODEL_NAME", "voyageai/voyage-4-nano")
        self.embedding_dim = int(os.getenv("EMBEDDING_DIM", 1024))
        
        print(f"Loading {model_name} from Hugging Face Hub...")
        
        # Load with GPU optimization if available
        if torch.cuda.is_available():
            self.model = SentenceTransformer(
                model_name,
                trust_remote_code=True,
                truncate_dim=self.embedding_dim,
                model_kwargs={
                    "attn_implementation": "flash_attention_2",
                    "torch_dtype": torch.bfloat16
                }
            )
            print(f"Model loaded on GPU with Flash Attention 2")
        else:
            self.model = SentenceTransformer(
                model_name,
                trust_remote_code=True,
                truncate_dim=self.embedding_dim
            )
            print(f"Model loaded on CPU")
        
        print(f"Embedding dimension: {self.embedding_dim}")

def embed_query(self, mood_description: str) -> list:
        """
        Embed a mood query. Uses query-specific prompt for better retrieval.
        Example: "something uplifting after a bad day"
        """
        if not mood_description:
            return []
        embedding = self.model.encode_query(mood_description)
        return embedding.tolist()

def embed_document(self, plot: str) -> list:
        """
        Embed a movie plot description. Uses document-specific prompt.
        """
        if not plot:
            return []
        embedding = self.model.encode_document(plot)
        return embedding.tolist()
    
    def embed_documents_batch(self, plots: list[str], batch_size: int = 32) -> list:
        """
        Embed multiple plots efficiently in batches.
        """
        embeddings = self.model.encode_document(
            plots, 
            batch_size=batch_size,
            show_progress_bar=True
        )
        return [emb.tolist() for emb in embeddings]
EOF

voyage-4-nano uses different prompts for queries and documents:

encode_query() prepends: "Represent the query for retrieving supporting documents:"

encode_document() prepends: "Represent the document for retrieval: "

This asymmetric encoding improves retrieval quality.

Data indexing module

The indexer downloads the movie dataset from Hugging Face, generates fresh embeddings with voyage-4-nano, and stores everything in MongoDB.

Code Snippet

cat <<'EOF' > src/indexer.py
import os
from datasets import load_dataset
from src.database import MongoManager
from src.ai import MoodEmbedder

def extract_year(date_str):
    """Extract year from various date formats"""
    if not date_str:
        return None
    try:
        if isinstance(date_str, dict) and '$date' in date_str:
            from datetime import datetime
            ts = date_str['$date'].get('$numberLong', 0)
            return datetime.fromtimestamp(int(ts) / 1000).year
        return int(str(date_str)[:4])
    except:
        return None

def run_indexing():
    print("=" * 60)
    print("🎬 MOOD-BASED MOVIE SEARCH - INDEXING")
    print("=" * 60)

print("\n[1/6] Connecting to MongoDB...")
    db = MongoManager()
    collection = db.get_collection()
    print("✓ Connected")

print("\n[2/6] Loading Voyage-4-nano from Hugging Face Hub...")
    embedder = MoodEmbedder()
    print("✓ Model ready")

print("\n[3/6] Downloading movie dataset from Hugging Face...")
    dataset = load_dataset("MongoDB/embedded_movies", split="train")
    print(f"✓ Downloaded {len(dataset)} movies")

# Sample for demo (use full dataset in production)
    sample_size = min(500, len(dataset))
    sample_data = dataset.shuffle(seed=42).select(range(sample_size))
    print(f"\n[4/6] Processing {sample_size} movies...")

collection.delete_many({})
    print("✓ Cleared existing data")

# Prepare documents
    movies_to_embed = []
    plots_to_embed = []
    
    for item in sample_data:
        plot = item.get("plot", "")
        if not plot or len(plot) < 50:
            continue
            
        movie = {
            "title": item.get("title", "Unknown"),
            "plot": plot,
            "genres": item.get("genres", []),
            "year": extract_year(item.get("released")),
            "runtime": item.get("runtime"),
            "cast": item.get("cast", [])[:5],
            "directors": item.get("directors", []),
            "imdb_rating": item.get("imdb", {}).get("rating") if isinstance(item.get("imdb"), dict) else None,
        }
        movies_to_embed.append(movie)
        plots_to_embed.append(plot)

print(f"  Found {len(movies_to_embed)} movies with valid plots")

print("\n[5/6] Generating embeddings with Voyage-4-nano...")
    embeddings = embedder.embed_documents_batch(plots_to_embed)
    
    for movie, embedding in zip(movies_to_embed, embeddings):
        movie["plot_embedding"] = embedding

if movies_to_embed:
        print(f"\n  Inserting {len(movies_to_embed)} movies into MongoDB...")
        collection.insert_many(movies_to_embed)
        print(f"✓ Inserted {len(movies_to_embed)} movies")

print("\n[6/6] Creating vector search index...")
    db.create_vector_index()

print("\n" + "=" * 60)
    print("✓ INDEXING COMPLETE!")
    print(f"  Movies indexed: {len(movies_to_embed)}")
    print(f"  Embedding dimensions: {embedder.embedding_dim}")
    print("=" * 60)

if __name__ == "__main__":
    run_indexing()
EOF

Search API

The FastAPI application exposes the mood-based search endpoint. Users describe their mood, and the system returns semantically matching movies.

Code Snippet

collection = db.get_collection()

class MoodSearchRequest(BaseModel):
    mood: str
    limit: int = 5
    min_rating: Optional[float] = None
    genre_filter: Optional[str] = None

@field_validator('mood')
    @classmethod
    def mood_must_not_be_empty(cls, v):
        if not v or not v.strip():
            raise ValueError('Mood description cannot be empty')
        return v.strip()

@field_validator('limit')
    @classmethod
    def limit_must_be_reasonable(cls, v):
        if v < 1 or v > 20:
            raise ValueError('Limit must be between 1 and 20')
        return v

@app.post("/search")
def search_by_mood(request: MoodSearchRequest):
    """
    Search for movies based on your current mood.
    
    Examples:
    - "I need something uplifting after a rough day"
    - "want to cry and feel cathartic"
    - "exciting adventure for movie night with friends"
    - "something calm and beautiful to fall asleep to"
    """
    
    query_embedding = embedder.embed_query(request.mood)
    
    if not query_embedding:
        raise HTTPException(status_code=400, detail="Failed to process mood description")

vector_search_stage = {
        "$vectorSearch": {
            "index": "mood_search_index",
            "path": "plot_embedding",
            "queryVector": query_embedding,
            "numCandidates": 150,
            "limit": request.limit * 2
        }
    }
    
    match_stage = {"$match": {}}
    if request.min_rating:
        match_stage["$match"]["imdb_rating"] = {"$gte": request.min_rating}
    if request.genre_filter:
        match_stage["$match"]["genres"] = request.genre_filter
    
    project_stage = {
        "$project": {
            "_id": 0,
            "title": 1,
            "plot": 1,
            "genres": 1,
            "year": 1,
            "imdb_rating": 1,
            "cast": 1,
            "directors": 1,
            "mood_match_score": {"$meta": "vectorSearchScore"}
        }
    }
    
    pipeline = [vector_search_stage]
    if match_stage["$match"]:
        pipeline.append(match_stage)
    pipeline.append(project_stage)
    pipeline.append({"$limit": request.limit})

try:
        results = list(collection.aggregate(pipeline))
        
        return {
            "mood_query": request.mood,
            "results_count": len(results),
            "movies": results
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Search failed: {str(e)}")

@app.get("/examples")
def get_example_queries():
    """Returns example mood queries to try"""
    return {
        "examples": [
            {"mood": "something uplifting after a rough day at work", "category": "Feel Good"},
            {"mood": "I want to cry and have a good emotional release", "category": "Emotional"},
            {"mood": "edge-of-seat thriller I can't pause", "category": "Exciting"},
            {"mood": "slow beautiful film to relax to", "category": "Calm"},
            {"mood": "something to watch with kids on Sunday", "category": "Family"},
            {"mood": "mind-bending movie that makes you think", "category": "Thought-provoking"},
            {"mood": "nostalgic 80s vibe adventure", "category": "Nostalgic"},
            {"mood": "dark and disturbing but artistic", "category": "Art House"},
        ]
    }

@app.get("/")
def health_check():
    return {
        "status": "ok",
        "service": "Mood-Based Movie Search API",
        "model": "voyage-4-nano",
        "embedding_dim": embedder.embedding_dim
    }
EOF

Package initialization

Code Snippet

Project structure

Your final project structure should look like this:

Code Snippet

Run and test

Index the data

First, run the indexer to download movies from Hugging Face and generate embeddings:

Code Snippet

Expected output:

Code Snippet

Start the API server

Code Snippet

Test mood-based queries

Query 1: Feel-good movie after a tough day

Code Snippet

Response:

Code Snippet

The system returned action films with themes of personal transformation and helping others. Scores around 0.65 show moderate similarity because "uplifting" is an abstract concept that does not appear directly in plot text.

Query 2: Emotional catharsis

Code Snippet

Response:

Code Snippet

The system found films with emotionally heavy themes. "Tae Guk Gi" is a war drama about brothers forced to fight against each other. "Split Decisions" deals with loss and revenge after a boxer's death. The word "tears" in "The Wedding Party" plot directly matched the query's emotional intent.

Query 3: With filters

Code Snippet

Response:

Code Snippet

With strict filters (rating >= 7.5, genre = Action), only one movie matched. Notice the significantly higher score of 0.761 compared to previous queries. The phrase "exciting adventure" directly aligns with "over-the-top action" in the plot description. This demonstrates that concrete, descriptive mood queries produce stronger semantic matches than abstract emotional ones.

Key observations

Abstract mood queries ("uplifting", "emotionally moved") score 0.62 to 0.67

Concrete descriptions ("exciting adventure") score 0.75+

Filters help find better matches even with fewer results

The system understands themes even without exact word matches

Comparing embedding dimensions

One unique advantage of voyage-4-nano's Matryoshka embeddings is the ability to experiment with different dimensions. Let's compare how dimension choice affects results.

Create a test script:

Code Snippet

cat <<'EOF' > test_dimensions.py
from sentence_transformers import SentenceTransformer
import numpy as np

model_2048 = SentenceTransformer("voyageai/voyage-4-nano", trust_remote_code=True, truncate_dim=2048)
model_512 = SentenceTransformer("voyageai/voyage-4-nano", trust_remote_code=True, truncate_dim=512)
model_256 = SentenceTransformer("voyageai/voyage-4-nano", trust_remote_code=True, truncate_dim=256)

query = "heartwarming story about friendship"
plots = [
    "Two elderly men rediscover their friendship during a road trip across America.",
    "A violent revenge thriller set in the criminal underworld.",
    "A young girl and her robot companion explore a magical forest.",
]

for dim, model in [(2048, model_2048), (512, model_512), (256, model_256)]:
    q_emb = model.encode_query(query)
    d_embs = model.encode_document(plots)
    
    similarities = np.dot(d_embs, q_emb) / (np.linalg.norm(d_embs, axis=1) * np.linalg.norm(q_emb))
    
    print(f"\n=== {dim} dimensions ===")
    for plot, sim in zip(plots, similarities):
        print(f"  {sim:.4f}: {plot[:50]}...")
EOF

Run the script:

Code Snippet

Result:

Code Snippet

In this example, all three dimension settings correctly rank the plots in the same order: the friendship story scores highest, the robot companion story is second (thematically related through companionship), and the violent thriller scores lowest.

The key differences:

Discrimination gap: With 2048 dimensions, the gap between the best match (0.4496) and worst match (0.1472) is 0.302. With 256 dimensions, the gap is larger at 0.397 (0.4139 minus 0.0168). Interestingly, lower dimensions can produce wider gaps due to more aggressive compression of the embedding space, but this doesn't necessarily mean better quality. The absolute similarity scores are lower and less reliable.

Ranking stability: In many cases, the top-ranked results will remain consistent across dimensions. However, lower dimensions will see a slight decrease in retrieval quality compared to the full 2048-dimensional vector.

When dimensions matter: If your application requires maximum accuracy and the ability to distinguish between very fine semantic nuances, higher dimensions are the best choice. However, if you have constraints around storage costs and query latency, lower dimensions may be a better fit, as they offer significant efficiency gains with only a marginal trade-off in retrieval precision.

Practical recommendation: Start with 1024 dimensions as a balanced default. Drop to 512 if storage is a concern. Use 2048 only when you need maximum precision for nuanced queries.

Next Steps

Learn more about Voyage AI.