Build Your First Recommendation System: Movies & Products

Look closely at your favorite apps and you’ll notice that “recommendation” rarely appears as a single feature. It shows up as multiple surfaces, each with a slightly different job. A movie app might have Top Picks (personalized), Trending (popularity), and More Like This (similarity). A shopping app might have Frequently bought together (basket association), You may also like (personalized ranking), and Related items (item similarity). Music apps do the same with Daily Mix, Radio, and Discover.

In all cases, the system is outputting a ranked list of items, usually with a reason label (“Because you watched…”) that is part product design and part trust-building. The key detail is that the list is time-sensitive and context-sensitive: recommendations for the home screen may differ from recommendations on an item detail page. In this course, you’ll focus on two outputs that are common and practical to build with basic data: (1) a popularity-based list that can power “Trending Now”, and (2) an item-to-item ‘more like this’ list that can power “Customers also bought” or “If you liked X, try Y.”

Common mistake: assuming “recommendation” means mind-reading. In practice, the system is making a probabilistic guess given partial evidence, and it’s constrained by inventory, business rules, and latency. A beginner-friendly recommender can still be valuable if it is stable, explainable, and improves over showing random items.

At the most basic level, a recommender is built from three concepts: users, items, and interactions. A user can be a person, an account, or even an anonymous session. An item can be a movie, product, song, article, or restaurant. An interaction is any measurable signal connecting a user to an item—rating it, watching it, clicking it, adding it to cart, or purchasing it.

The simplest dataset shape you’ll see is a table with columns like: user_id, item_id, timestamp, and optionally rating or event_type. This is sometimes called an “interaction log.” From this log you can build a user–item matrix: rows are users, columns are items, cells contain an interaction value (a rating, a 1 for click, or a count). Most real-world matrices are extremely sparse—most users touch only a tiny fraction of items—so recommendation is partly about learning from sparse evidence.

Engineering judgment starts here: define what counts as an interaction and how you’ll represent it. For movies, a rating is naturally numeric. For shopping, clicks and purchases are different signals and may need different weights. Another practical decision is identity: do you merge interactions across devices, and how do you handle new users with no history (the “cold start” problem)? In this course, you’ll keep identity simple and focus on the core mechanics: load a dataset, clean obvious issues (missing IDs, duplicates, impossible ratings), and understand basic distributions (how many interactions per user, how many per item). These checks prevent silent failure where a model appears to run but learns nonsense from messy data.

Recommendation data usually comes in two flavors: explicit feedback (ratings) and implicit feedback (behavioral signals like views, clicks, carts, and purchases). Ratings are easy to interpret—5 means “loved it”—but they are often scarce because users don’t rate everything. Implicit feedback is abundant, but ambiguous: a click can mean interest, curiosity, or even accidental tapping.

These differences affect modeling and evaluation. With ratings, you can frame a problem like “predict the rating a user would give an item,” but in practice many systems still convert ratings into a ranking task: “rank items by predicted preference.” With implicit feedback, you typically predict the probability of interaction (click/purchase) or rank items by likelihood of engagement. You also have to choose negatives carefully: not clicking does not necessarily mean dislike; it may simply mean the user never saw the item.

• Ratings (explicit): clean meaning, low volume, prone to selection bias (only motivated users rate).
• Views/clicks (implicit): high volume, noisy meaning, requires careful negative sampling or evaluation framing.
• Carts/purchases: stronger intent, still influenced by price, stock, and context.

Common mistake: mixing signal types without a plan. If you treat clicks and purchases identically, you may optimize for shallow engagement rather than satisfaction. In this course, you’ll start with the simplest workable representation: one interaction per user–item pair (e.g., a rating, or a binary “interacted”). That simplicity keeps the first system understandable, and it sets you up to add nuance later (weights by event type, recency, and session context).

Two baseline forces drive many recommendation lists: popularity (what’s broadly liked or frequently interacted with) and personalization (what’s likely for this user). Popularity is surprisingly hard to beat as a first baseline because it captures strong signals: social proof, marketing pushes, and general quality. It is also robust for new users and new sessions, because it does not require user history.

Personalization, on the other hand, aims to adapt to individual taste. A practical stepping-stone to personalization is item-to-item similarity, the “more like this” approach. If many users who interacted with Item A also interacted with Item B, then B is a reasonable suggestion when someone shows interest in A. This method often works well on item detail pages and is easier to explain than user-embedding models: “people who liked this also liked that.”

In this chapter’s mindset, popularity is not “dumb”—it’s your sanity check. Before you try anything clever, you should be able to produce a popularity list and confirm it looks reasonable (no broken IDs, no empty titles, no items with one accidental click). Then you build an item-to-item recommender and compare it against popularity. Common mistake: declaring success because the personalized list looks “cool.” You need a baseline and simple metrics so you can measure improvement rather than rely on intuition.

Practical outcome: you’ll implement both approaches in notebooks. Popularity will be a few lines of grouping and sorting. Item-to-item will use co-occurrence or cosine similarity over item interaction vectors. Both are fast, interpretable, and good foundations for learning the full pipeline.

Recommenders shape what people see, so they come with predictable risks. Popularity bias is the tendency to over-recommend already popular items, starving niche items of exposure. This can become self-reinforcing: popular items get shown more, get clicked more, and become even more popular. Even item-to-item similarity can amplify this if popular items co-occur with everything.

Filter bubbles happen when personalization narrows a user’s options too aggressively, showing more of the same and reducing discovery. “More like this” is particularly bubble-prone if you never inject diversity. A practical mitigation is to mix recommendation sources (some popularity, some similar, some exploratory) or to add lightweight diversity rules (don’t recommend ten nearly identical items).

Privacy is a core engineering concern: interaction logs can reveal sensitive preferences. Beginner projects often ignore this, but you should still practice good habits: minimize data you load, avoid storing raw identifiers in exported artifacts, and be careful when sharing notebooks or screenshots. Another common mistake is training or evaluating on data that includes future information (data leakage), which can make your system look far better than it would be in real use.

• Watch for leakage: split data by time when possible (train on past, evaluate on future).
• Watch for bias: compare performance for heavy vs light users, popular vs long-tail items.
• Handle privacy: keep datasets local, remove direct identifiers, document what you store.

You won’t solve these risks fully in a first course, but you will learn to spot them and avoid the easiest traps—especially leakage and uncritical reliance on popularity.

This course is structured like a real recommendation project, but scaled to be beginner-friendly and notebook-first. The goal is not to build the most advanced model; it’s to build a complete, correct pipeline you can trust. Here is the project map you’ll follow repeatedly: data → model → evaluation → deployment mindset.

Data: You will set up a Python environment (typical stack: Python 3, Jupyter, pandas, numpy, scikit-learn) and run your first notebook end-to-end. You’ll load ratings or interaction logs, inspect the schema, remove obvious bad rows (missing IDs, duplicates), and compute basic summaries: number of users, number of items, sparsity, and most-interacted items. These checks are not busywork—they prevent subtle bugs like training on empty interactions or mixing string/int IDs.

Models: You’ll build two recommenders. First, a popularity baseline that ranks items by average rating (for explicit data) or interaction count / weighted count (for implicit data), with simple smoothing to avoid “one rating = top item.” Second, an item-to-item similarity model that produces “more like this” suggestions using co-occurrence or cosine similarity on item vectors.

Evaluation: You’ll use beginner-safe ranking metrics (for example: Precision@K, Recall@K, and simple hit rate) computed on a held-out set. You’ll also do qualitative checks: do recommendations include the same item the user already consumed, are there duplicates, are the titles valid, and do results change sensibly when the input item changes? Common mistake: evaluating on the same data you trained on, which inflates results and hides flaws.

Success criteria: by the end of the build, you should be able to (1) generate a stable popularity Top-N list, (2) generate a “more like this” list for a given movie/product, (3) show that item-to-item beats popularity on at least one simple metric for users with history, and (4) explain—in plain language—what data your system uses and what kinds of errors it will make (cold start, popularity bias, and limited diversity).

Section 2.1: Setting up Python in the easiest way

Your goal is to run code reliably, not to become a package manager expert. The easiest beginner-friendly setup is a managed distribution plus notebooks. Two practical choices are: (1) Anaconda/Miniconda on your machine, or (2) a hosted notebook like Google Colab. If you want the smallest friction, start with Colab; if you want local files and repeatability, use Miniconda.

For a local setup, install Miniconda, then create an isolated environment for this course so dependencies don’t clash with other projects. A typical workflow is: create an environment, install key packages, then launch Jupyter. You’ll want at least: python, pandas for tables, numpy for numeric work, and optionally matplotlib/seaborn for quick plots. In a starter notebook, begin by importing these libraries and printing their versions—this sounds trivial, but it prevents hours of “it works on my machine” confusion later.

Common mistakes at this stage are almost always environment-related: installing packages into the wrong environment, opening Jupyter from a different interpreter than the one you installed packages into, or mixing pip/conda in ways that cause version conflicts. A simple discipline helps: activate the environment first, then run Jupyter from the same terminal session. Also, keep your data files in a predictable folder (for example, a data/ directory next to the notebook) so relative paths work when you move the project.

• Create a project folder: recsys-first/
• Add subfolders: notebooks/, data/, outputs/
• Run a starter notebook that imports pandas and reads a CSV

Once your notebook can load a file and display a small table, you’re ready for the real work: understanding what’s in the dataset and what “clean” should look like.

Section 2.2: Files, tables, and columns (CSV basics)

Most beginner recommendation datasets arrive as CSV files because they’re simple, portable, and easy to inspect. A CSV is just a table: rows are records, columns are fields. In ratings data, each row is typically “one user rated one movie at one time.” That makes it an interaction log. In product settings, the interaction might be a click, add-to-cart, purchase, or view.

Load your file using pandas.read_csv and immediately do three checks: df.shape (how many rows/columns), df.head() (sample records), and df.dtypes (data types). Then look at missing values with something like df.isna().sum(). These aren’t “busywork”; they’re how you catch silent problems like ratings being read as strings, timestamps missing, or unexpected extra columns.

You’ll often have two tables: an interactions table (ratings.csv) and an item metadata table (movies.csv). The metadata file is how you turn an internal ID like movieId=1 into a human-meaningful title and genre. Join the two tables using the shared key (movieId). Be careful to choose the correct join: a left join from ratings to movies will keep all interactions even if some metadata is missing; an inner join will drop interactions that don’t match, which can shrink your dataset without you noticing.

• Inspect: rows, columns, dtypes, and missingness.
• Confirm keys: userId, movieId, and a numeric signal (rating or event).
• Join metadata only after validating both tables separately.

Engineering judgement tip: decide early what “one row” means. If your dataset includes multiple ratings by the same user for the same movie, is that a real scenario (re-rating) or accidental duplication? Your baseline will behave very differently depending on that decision.

Section 2.3: Cleaning data: missing values and duplicates

Cleaning is not glamorous, but recommendation systems amplify data issues: one bad record can push a niche item to the top if your counting logic is naive. Start by defining what “valid” means for each column. For example: userId and movieId should be present and integer-like; rating should be numeric and within the expected range (often 0.5–5.0); timestamp should be present if you plan recency rules.

Handle missing values deliberately. If a rating is missing, you can’t use that row for a ratings-based popularity model; drop it or impute only if you truly understand the implication. If metadata like genre is missing, you might still keep the interaction, but you won’t be able to do genre filtering for that item. In that case, keep the row but mark genre as “Unknown” to avoid crashes and to make later diagnostics easier.

Duplicates require careful thought. There are two common patterns: exact duplicate rows (same user, same movie, same rating, same timestamp) and repeated interactions (same user and movie but different timestamp or rating). Exact duplicates are usually safe to drop. Repeated interactions may be meaningful—users can update ratings—so you need a policy. A practical beginner policy is: keep the most recent rating per (userId, movieId) pair. That gives you a single, tidy “latest preference” table.

• Drop rows missing critical keys: userId, itemId.
• Coerce types: convert ratings to float and timestamps to datetime.
• Remove exact duplicates; for re-ratings, keep the latest record.
• Validate ranges: clamp or drop ratings outside expected bounds.

Common mistake: cleaning after modeling. If you compute “most popular” before deduplicating re-ratings, you may overcount extremely active users and bias popularity. Clean first, then model. A tidy table you trust is the foundation for everything that follows, including evaluation.

Section 2.4: Baseline model: most popular items

A popularity recommender is the simplest thing that can work: recommend the items that many people like. In a ratings dataset, you can define “popular” in multiple ways. Two beginner-safe definitions are: (1) highest average rating, and (2) highest number of ratings. Each has a flaw on its own: average rating favors items with very few votes (one friend loved it, so it’s “perfect”), while count favors blockbusters even if people rate them as mediocre. The practical baseline is a blend: require a minimum count, then sort by average rating (or use a weighted score).

Implement it with a group-by on movieId and compute count and mean of ratings. Then filter to items with count above a threshold (start with 50 for larger datasets, or 5–10 for tiny datasets), and sort by mean rating descending. Finally, join to the movies metadata to display titles and genres, and return the top-N list.

Testing this baseline is not about math sophistication; it’s about sanity. Print the top 10 recommendations and check if they look plausible. If you see items with only 1–2 ratings at the top, your minimum count filter is too low or missing. If you see obvious junk or missing titles, your join keys may be wrong or metadata is incomplete.

• Compute per-item: rating_count, rating_mean.
• Filter: rating_count >= min_count.
• Rank: sort by rating_mean (optionally break ties by count).
• Return: top-N with title/genre for readability.

This model is also a useful “fallback recommender” in real systems: when you know nothing about a new user, popularity is often a strong default—especially when paired with the filtering rules in the next section.

Section 2.5: Simple business rules: recency and minimum counts

In production, recommendation quality is rarely just “the best algorithm.” Simple business rules can dramatically improve perceived relevance, especially for beginners. Two of the highest-impact rules are minimum counts (confidence) and recency (freshness). You already used minimum counts to avoid being fooled by one-off ratings; now you’ll make it explicit and adjustable.

Minimum counts is a trust lever: higher thresholds reduce noise but can exclude niche items; lower thresholds increase variety but risk surfacing items with unreliable scores. Choose a threshold appropriate to your dataset size and product goals. If your dataset has only a few thousand ratings total, a minimum count of 50 will produce an empty list; start small and increase until the top-N list looks stable across reruns.

Recency matters because user taste and catalogs change. Even in a movies dataset, recency can approximate “what’s trending now.” If you have timestamps, convert them to dates and filter interactions to a time window (for example, last 365 days). Then compute popularity within that window. This gives you “popular recently” rather than “popular forever.” Be careful: a tight window can create sparse data; combine recency with a lower minimum count to avoid returning nothing.

Finally, add category filtering to match context. With movies, filter by genre (e.g., Comedy) by selecting items whose genre string contains a label. With products, filter by category or availability. This is not “cheating”; it’s aligning recommendations with user intent (“I’m browsing sci-fi right now”).

• Rule 1: Minimum count to ensure statistical reliability.
• Rule 2: Recency window to reflect trends and freshness.
• Rule 3: Genre/category filter to respect context and browsing mode.

These rules turn a naive baseline into something that can be meaningfully compared against smarter models later. They also teach a key lesson: recommender systems are socio-technical; product constraints and user experience matter as much as metrics.

Section 2.6: Quick sanity checks: does the output make sense?

Before you think about advanced evaluation, you should learn to distrust your first result. Sanity checks are quick tests that catch common bugs: mis-joins, wrong sort order, counting duplicates, leaking future data, or accidentally recommending items that shouldn’t be recommendable.

Start with readability. Your output should include item IDs and human names (titles), plus the score components you used (mean rating, count, and optionally the date window). If you can’t explain why an item is ranked #1, you’re not ready to iterate. Next, check for obvious anomalies: missing titles, duplicate titles, or the same item appearing multiple times. If you see duplicates, your table may have multiple metadata rows per itemId or you may have merged incorrectly.

Then do a few “spot checks” by slicing the data. If you apply a genre filter (e.g., Horror), confirm that every returned item actually contains that genre. If you apply recency, print the min/max timestamp in the filtered interactions to confirm the window is working. If you apply minimum counts, verify the lowest count in your top-N is at least the threshold.

• Display columns: title, genres, rating_mean, rating_count (and window start/end if using recency).
• Confirm sorting: highest score at the top, ties broken consistently.
• Check constraints: genre filter truly applied; counts meet thresholds; no missing titles.

One more practical check: stability. Run the notebook twice. If results change without data changing, you may have nondeterministic steps (like sampling) or you may be reading different files than you think. A baseline recommender should be deterministic. Once your outputs pass these checks, you have a baseline you can trust—and a solid foundation for adding item-to-item similarity and user-personalized methods in the next chapters.

Similarity recommendations are the digital version of a helpful friend. If you say, “I loved The Matrix,” your friend doesn’t respond with “Everyone loves Avengers.” They respond with “Try Blade Runner” or “If you liked the sci‑fi action vibe, you might enjoy John Wick.” The core idea is: items can be similar because the same people tend to interact with them.

In item-to-item collaborative filtering, we don’t need to know the genre, cast, or product attributes. We look only at user behavior: who watched what, who bought what, who rated what. If many users who liked Item A also liked Item B, then A and B are probably related in a meaningful way. This works for movies, products, articles, and even learning resources.

Practically, you’ll build a “neighbors” list for each item: the top most similar items. Then the recommendation becomes a simple lookup: “because you liked X” → show the nearest neighbors of X. This is also explainable in UI copy and easy to debug: if a recommendation looks off, you can inspect which neighbor relationship produced it.

Common mistakes at this stage are conceptual. People confuse “similar items” with “popular items.” Popularity is global; similarity is conditional. Another mistake is assuming similarity means identical. Good neighbors are usually related, not duplicates. Your job is to pick the right similarity measure and apply guardrails so that the neighbors feel relevant and not repetitive.

To compute item similarity from behavior, you need a user-item table: rows are users, columns are items, and each cell contains an interaction signal. In a movie ratings dataset, the signal might be a 1–5 rating. In an e-commerce dataset, it might be “purchased” (1) or “not purchased” (0). In many real systems, it’s implicit feedback such as clicks, views, add-to-cart, or watch time.

You can build this table in pandas using a pivot:

• user_item = df.pivot_table(index='user_id', columns='item_id', values='rating', fill_value=0)

Using fill_value=0 is a practical trick, not a claim that “0 is a real rating.” It means “no interaction observed.” This leads to a sparse table: most cells are zero because each user interacts with only a tiny fraction of all items. Sparse data is normal; recommendations exist specifically because the table is mostly empty.

Two engineering judgments matter here. First, choose a signal that makes sense. If you have ratings, consider filtering out low ratings or converting ratings to “liked” vs “not liked,” depending on your use case. Second, reduce noise: drop users with too few interactions and items with too few interactions. If an item has only one rating, any similarity computed from it will be unstable and can create random-looking neighbors.

Finally, consider whether to center ratings (subtract a user’s average) to reduce user bias. Some users rate everything high; others rate everything low. Mean-centering can help, but it also adds complexity. For a first recommender, start with a straightforward pivot table, then iterate once you can see results.

Once you have the user-item table, each item becomes a vector: a column of numbers representing how users interacted with that item. Similarity is then a way to compare two vectors. Cosine similarity is popular because it focuses on direction rather than magnitude. Intuitively: do the same users tend to like both items, even if one item has more interactions overall?

Picture two items as arrows pointing in a high-dimensional space (one dimension per user). If two arrows point in the same direction, the cosine of the angle between them is close to 1, meaning “very similar.” If they are unrelated, the angle is closer to 90 degrees and the cosine is near 0. Negative values can happen with centered data, but with nonnegative implicit feedback, cosine usually lands between 0 and 1.

In code, you typically transpose the matrix so items are rows:

• item_user = user_item.T
• from sklearn.metrics.pairwise import cosine_similarity
• sim = cosine_similarity(item_user)

This produces an item-by-item similarity table. However, computing a full similarity matrix can be expensive if you have many items. For learning datasets with a few thousand items, it’s fine. For large catalogs, you’ll later switch to approximate neighbors or compute similarities only for top candidates.

Common mistakes: (1) forgetting to remove the item itself (every item is perfectly similar to itself), (2) trusting similarities based on tiny overlap (two users rated both items, so cosine looks high), and (3) mixing scales (ratings vs implicit clicks) without thinking through what “similar” should mean. A simple fix for (2) is to require a minimum number of co-ratings/co-interactions before accepting a neighbor relationship.

With an item similarity table in hand, generating “because you liked X” recommendations is mostly sorting. For a given item_id, you find its similarity scores to all other items, sort descending, and return the top N items.

A practical workflow looks like this:

• Build user_item (users × items).
• Compute cosine similarity between item vectors.
• Store as a DataFrame sim_df indexed by item_id with columns item_id.
• For a query item, fetch the row, drop itself, sort, and take top N.

You’ll get the best results when you also return metadata (movie titles, product names). That means joining recommended item_ids back to an items table. When debugging, always print the query item name and the neighbor names. It’s the fastest way to see if the model “gets it.”

Nearest neighbors can also be computed without the full matrix using sklearn.neighbors.NearestNeighbors(metric='cosine'). This is often faster and more memory-friendly, and it maps directly to the mental model: “find the k closest items.” Whichever approach you pick, keep the interface consistent: input an item_id, output a ranked list.

To test, pick a few anchor items you personally understand (popular movies, well-known products). If “more like this” returns nonsense, the issue is usually upstream: sparse data, unfiltered noise, or missing preprocessing. This is where you compare to the popularity baseline: popularity will always look “reasonable,” so your similarity model must be better on personalization and thematic relevance, not just on global appeal.

A similarity recommender is easy to make and easy to break. The fastest way to produce bad recommendations is to forget about user context. Even in an item-to-item widget (“because you liked X”), you often want to avoid items the user has already seen or purchased, especially if you’re building a “next thing to try” experience.

Two common guardrails:

• Seen-item filtering: if you know the current user, remove items they have already interacted with from the neighbor list. This prevents recommending the same movie they watched yesterday.
• Minimum support: require a minimum number of interactions per item and/or a minimum overlap count between items before trusting similarity.

Edge cases matter in production-like notebooks too. What if the item_id is unknown (not in the matrix)? What if the item exists but has too few interactions, so its similarity row is mostly zeros? What if there are fewer than N valid neighbors after filtering? A robust recommender returns a sensible fallback rather than crashing.

A practical fallback is your popularity baseline: if similarity can’t produce confident neighbors, return the top popular items in the same category (if you have categories) or globally. This is not “cheating”—it’s layered engineering. Many real systems use multiple strategies and pick the best available output.

Also watch for “near-duplicate” problems: sequels, different editions, or the same product in multiple sizes might dominate the neighbor list. Sometimes that’s good (users want the next book in a series), but sometimes it feels repetitive. If needed, add a simple rule to diversify: limit one item per franchise/brand or apply a cap per creator. Start simple, and add complexity only when you see the failure mode.

Item-to-item similarity can be surprisingly fast if you design it with constraints. The expensive step is building neighbors; serving recommendations is cheap once neighbors are cached. Your performance goal in this chapter is: compute similarities once, reuse many times.

Start with “smaller data” tricks that preserve learning value:

• Filter the catalog: keep items with at least min_item_interactions (e.g., 20) and users with at least min_user_interactions (e.g., 10). This reduces noise and speeds computation.
• Use sparse matrices: convert the pivot table to a SciPy sparse matrix before running neighbors if the dataset is big. Sparse representations avoid storing all those zeros.
• Limit neighbors: store only the top K neighbors per item (e.g., K=50). Most applications never need the full similarity row.

Caching is the simplest “speed up” win. After you compute neighbors, save them (pickle, parquet, or a simple CSV of item_id → neighbor list). Then your recommend(item_id) function becomes a lookup plus light filtering. This mirrors real-world architecture: offline batch job builds similarity; online service serves results.

Finally, be intentional about evaluation and comparison. When you test with a few users, check two things: (1) qualitative relevance (“do these neighbors make sense?”) and (2) simple metrics like hit-rate@K on a tiny holdout split. Compare against the popularity baseline to confirm you gained personalization rather than just rediscovering globally popular items. If similarity underperforms, it’s often because the data is too sparse or because you didn’t filter low-support items—fix the data first, then tune the model.

By the end of this chapter, you should have a reusable function—recommend(item_id) → list—backed by a cached neighbor table, plus a small set of rules that keep outputs stable, fast, and reasonable.

Section 4.1: What personalization means (and what it doesn’t)

Personalization means the system changes its recommendations based on information about a specific user: their ratings, clicks, purchases, watch history, skips, or searches. In a movie app, personalization might shift you away from “top 10 in your country” toward more documentaries because you watched several recently. In an ecommerce store, it might show you accessories that people like you bought after buying a laptop.

What personalization doesn’t mean: it doesn’t guarantee “perfect taste prediction,” and it doesn’t remove the need for strong baselines. In fact, most production systems always keep a popularity component for safety and freshness—especially for new users (cold start), new items, and users with sparse data.

A useful way to think about it is: personalization is a ranking problem. You still need candidates (a set of items you might recommend), and then you sort them for the user. User-based recommendation provides a way to generate and score candidates using other users’ behavior. But you must still apply practical constraints: filter out items the user already consumed, handle duplicates, enforce business rules (availability, region, age rating), and ensure the list is not monotonous.

• Common mistake: Treating any user overlap as meaningful similarity. If two users both watched one blockbuster, that alone shouldn’t make them “neighbors.”
• Common mistake: Over-personalizing with tiny histories. With 1–2 interactions, user-based methods can produce unstable, overly confident results.
• Practical outcome: You’ll aim for “better than popularity” while keeping sensible fallback behavior when data is thin.

In this chapter’s workflow, you’ll explicitly decide what counts as “user signal” (ratings vs implicit events), how much history is required before personalization activates, and how to blend personalization with global signals so the system stays robust.

Section 4.2: User-based similarity in simple steps

User-based collaborative filtering starts with a straightforward idea: if two users behave similarly, items liked by one are candidates for the other. The simplest implementation looks like: (1) represent each user by the items they interacted with, (2) compute similarity between users, (3) pick the top neighbors, and (4) recommend items those neighbors liked that the target user hasn’t seen.

For implicit data (clicks, purchases), a practical representation is a binary vector: 1 if the user interacted with the item, 0 otherwise. For explicit ratings, you can use the rating value, but be careful: different people use rating scales differently (one user gives mostly 3–4, another gives mostly 4–5). A beginner-safe improvement is to mean-center ratings per user (subtract the user’s average) before computing similarity.

Similarity choices you can implement quickly:

• Jaccard similarity (implicit): overlap / union of items. Good when you only know “did interact.”
• Cosine similarity (implicit or centered ratings): compares direction of vectors; commonly used and easy to compute.
• Pearson correlation (ratings): measures correlated preference patterns; can be noisy with few overlaps.

A practical, simple pipeline in pandas is:

• Build a user–item interaction table (sparse matrix conceptually; a DataFrame pivot can work for small data).
• Compute similarity between a target user and all other users (only on co-rated/co-interacted items when possible).
• Keep the top K neighbors (for example, 20–100 depending on data size).
• Collect candidate items from neighbors that the target user hasn’t interacted with.

Engineering judgment matters here. Similarity becomes unreliable when users share very few items. A common safeguard is a minimum overlap threshold (e.g., require at least 3 or 5 co-rated items). Another safeguard is to shrink similarity by overlap count (neighbors with 2 shared items shouldn’t dominate neighbors with 20 shared items).

Practical outcome: by the end of this step, you should have a candidate set per user that feels “socially plausible”—items appear because similar people engaged with them, not because they are globally popular.

Section 4.3: Scoring candidates: combining counts and similarity

Candidate generation answers “what could we recommend?” Scoring answers “in what order?” A user-based system becomes useful when you convert neighbor behavior into a single score per candidate item. The most beginner-friendly scoring is a weighted sum: each neighbor contributes to an item’s score proportional to how similar that neighbor is to the target user.

A simple implicit-data score looks like:

• score(user, item) = Σ(similarity(user, neighbor) × interacted(neighbor, item))

For ratings, replace interacted with the neighbor’s (possibly mean-centered) rating. This produces a ranked list, but you’ll quickly notice two issues: (1) a single highly similar neighbor can cause spiky recommendations, and (2) rare items may never surface because they have too little neighbor evidence.

To make this more stable, combine multiple signals into one score. A practical recipe:

• Similarity evidence: weighted sum from neighbors (personalization strength).
• Support/count evidence: number of neighbors who interacted with the item (confidence).
• Global quality signal: item popularity or average rating (baseline safety).

One beginner-safe combined scoring approach is to normalize each component to a comparable range (for example, 0–1 with min-max scaling in your candidate set) and then compute:

• final_score = 0.6 × sim_score + 0.3 × neighbor_support + 0.1 × popularity_score

Those weights are not “correct” universally; they are a starting point you tune using offline evaluation (the metrics you learned earlier) and qualitative review. The key engineering lesson is that small global terms prevent embarrassing results (very obscure or low-quality items) while still letting personalization win when the evidence is strong.

Common mistakes include mixing raw counts with similarity sums without normalization (counts can dominate), forgetting to filter already-consumed items, and leaking future interactions into the training window when you evaluate. Practical outcome: you will have a stable, rankable score per user-item that you can debug by printing its components.

Section 4.4: Diversity and novelty (avoiding clones of one item)

A purely score-driven recommender often produces “clones”: five superhero movies in a row, or ten nearly identical phone cases. Even if each item is individually relevant, the list can feel repetitive and unhelpful. Diversity is the practice of intentionally mixing the list so users can discover adjacent interests without feeling trapped in a single niche.

Start with two simple concepts:

• Diversity: the items in the list are not too similar to each other (genre, brand, category, creator).
• Novelty: the list is not dominated by items the user would likely find anyway (only top sellers, only blockbusters).

A practical beginner technique is re-ranking: first compute your best relevance score, then apply a second pass that penalizes items too similar to those already selected. You can approximate item similarity using metadata (genre overlap, product category) or your item-to-item similarity from the previous chapter.

One simple re-ranking rule:

• Build the recommendation list iteratively.
• When choosing the next item, use adjusted_score = relevance_score − λ × max_similarity_to_selected.
• Pick the item with the best adjusted score, repeat until you have N items.

Here, λ controls how much you value variety. If λ is too high, you’ll get a scattered list that feels random; too low, you get clones. Another simple strategy is category caps (e.g., no more than 2 items per genre/brand) which is easy to explain to stakeholders and easy to implement.

Practical outcome: your recommendations will feel curated rather than purely algorithmic, while still respecting personalization. This is one of the fastest ways to improve perceived quality without changing your underlying model.

Section 4.5: Explanations users can understand

Explanations are not only for user trust; they are also a debugging tool for you. If you can’t explain why an item was recommended, you’ll struggle to fix bad recommendations. In simple recommenders, you can often generate explanations directly from the signals you already computed.

For user-based recommendations, good explanations are concrete and non-creepy. Avoid “Because we tracked you across the internet.” Prefer explanations grounded in your product’s context:

• Neighbor-based: “People with similar ratings to you liked this.”
• Item-history-based: “Because you watched Movie A and Movie B.”
• Category-based: “Popular among fans of sci-fi thrillers.”

To implement “why this was suggested,” store a few pieces of evidence per recommended item:

• The top 1–3 neighbors contributing to the item score (and their similarity values).
• The neighbor support count (how many neighbors interacted with it).
• The top 1–3 “overlap items” that made those neighbors similar (shared movies/products).

Then generate a short explanation template, for example: “Recommended because you and users similar to you both liked Inception and The Matrix.” Keep it short; users skim. Also ensure the explanation matches the reality of your data. If you used implicit data (clicks), don’t claim “liked”—say “watched” or “viewed.”

Common mistake: explanations that reveal sensitive attributes (“People your age/gender…”). Unless you have explicit consent and a strong product reason, don’t do it. Practical outcome: explanations improve user confidence and make offline evaluation failures easier to interpret (“this item scored high due to one neighbor with low overlap”).

Section 4.6: A practical decision guide for model selection

Choosing between popularity, item-to-item, and user-based methods is less about “which is best” and more about “which is safest and most effective for this context.” Each method has a sweet spot, and most real systems combine them.

• Popularity-based: Use when you have new users, very sparse data, or you need a strong baseline for trending content. It is stable, fast, and easy to explain, but not personalized.
• Item-to-item similarity: Use when you have good item interaction volume and you can anchor recommendations on a known item (a product page, “because you watched X”). It is often more stable than user-based with sparse user histories.
• User-based similarity: Use when users have enough history and your catalog is large enough that “people like you also liked” surfaces useful long-tail items. It can feel highly personal, but it is sensitive to sparse overlap and noisy neighbors.

Engineering judgment rules of thumb:

• Cold start: if a user has fewer than ~3 interactions, default to popularity plus light diversification. As history grows, gradually increase the weight of item-to-item and user-based signals.
• Catalog dynamics: if items change quickly (news, short-lived products), keep a larger popularity or recency component so recommendations stay fresh.
• Performance constraints: user-user similarity can be expensive at scale. Start with offline precomputation, approximate neighbors, or limit to active users and recent items.

A practical blended approach is: generate candidates from multiple sources (popular, item-to-item, user-based), merge them, score them with your combined scoring function, then re-rank for diversity and attach explanations. This “candidate + scoring + re-ranking” pattern is the backbone of many production recommenders because it is modular: you can improve one part without rewriting the system.

Practical outcome: you’ll know when to reach for each technique and how to combine them into a reliable first personalized recommender that you can evaluate, debug, and iterate on.

Section 5.1: Why evaluation is different for recommenders

In many ML projects, you predict one correct answer: a spam label, a price, a diagnosis. Recommenders are different: your system returns a ranked list, and there can be many acceptable answers. If you recommend any movie the user would enjoy, you did well—even if it’s not the one specific movie they watched next.

This creates two beginner pitfalls. First, evaluating with “rating prediction error” (like RMSE) can miss what you actually care about: whether the top of your list is useful. Second, your data is incomplete: users didn’t rate or click most items, but that doesn’t mean they dislike them. Treating missing interactions as negative labels is a common mistake that makes models look worse (or sometimes falsely better).

Instead, we evaluate with top‑N metrics: for each user, recommend N items and check whether the user’s “future” interactions contain any of them. This matches real product behavior: a homepage, a “Because you watched…” shelf, or a “Recommended for you” carousel. Your goal is not to predict every rating; your goal is to place good candidates near the top.

Finally, recommender evaluation must worry about system health, not only accuracy. A model that recommends the same blockbuster to everyone might look “accurate” but provides little value and can harm discovery. That’s why we also check coverage and popularity bias later in this chapter.

Section 5.2: Train/test split for interactions (time-aware idea)

Your split should mimic time. In real life, you recommend based on what you know up to today, then users interact tomorrow. So the beginner-friendly strategy is: for each user, hold out their most recent interaction(s) as “future” test data and train on the rest (“past”). This prevents data leakage, where the model accidentally learns from the very events you claim to predict.

A simple per-user time-aware split looks like this:

• Sort interactions by timestamp (or by an implied order if timestamps are missing).
• For each user, put the last 1 interaction into the test set (or last 2–5 for more stability).
• Use all earlier interactions for training.

Engineering judgment matters here. If a user has only 1 interaction, you cannot both train and test; you may drop that user from evaluation or keep them only in training. If you hold out too many interactions, your training history becomes unrealistically small and all models suffer. A practical starting point is “leave‑one‑out”: last interaction for test, rest for train.

Common mistakes:

• Random row splitting: mixing past and future creates optimistic scores.
• Item leakage: if you compute item similarity on all data (train+test), you leaked future co-occurrences.
• Cold-start confusion: if an item appears only in test, a simple model cannot recommend it. Track how often this happens; it’s a real issue, but don’t hide it.

Once you have train/test, you can evaluate any recommender as long as it can produce a ranked list for each user using only the training data.

Section 5.3: Top-N metrics explained with small examples

Top‑N evaluation asks: “Did we put something the user actually consumed in the top of the list?” Two beginner-safe metrics are hit rate and precision@k. They’re simple, interpretable, and align with ranked recommendations.

Hit rate (for a fixed N) is the fraction of users for whom at least one held‑out test item appears in the top‑N recommendations. With leave‑one‑out test data, it becomes very intuitive: if the user’s next movie is in the top‑10 list, that’s a hit.

Precision@k measures “how many of the recommended items were relevant,” averaged across users. With one held‑out item per user, precision@k is either 1/k (if the item is in the top‑k) or 0 (if not). If you hold out multiple future items per user, precision@k becomes richer because you may hit more than one.

Mini example (leave‑one‑out, k=5): User A’s test item is Inception. Your model recommends [Interstellar, Inception, Memento, Dunkirk, Tenet]. That’s a hit, and precision@5 for this user is 1/5 = 0.2. User B’s test item is not in their top‑5 list: no hit, precision@5 = 0.

Two practical details matter:

• Candidate set: In a real system you recommend from items the user hasn’t already consumed. In evaluation, make sure you exclude training items from the recommendation list.
• Ties and ordering: Popularity-based models can create ties. Use a stable tie-breaker (e.g., item_id) so results are reproducible.

As a default, evaluate at N=10 and N=20. Small k (like 5) reflects “above the fold,” while larger N reflects deeper browsing.

Section 5.4: Beyond accuracy: coverage and bias checks

If you only optimize hit rate, you can accidentally build a system that recommends the same handful of blockbuster items to everyone. This often happens with a popularity baseline, and it can also happen with similarity models if your data is dominated by a few items. That’s why we add two lightweight health checks: coverage and popularity bias.

Catalog coverage asks: “Out of all items we could recommend, how many unique items did we actually recommend across all users?” Compute it as:

• Collect all recommended items across users (e.g., top‑10 lists).
• Count unique recommended items.
• Divide by total number of items (or by the number of recommendable items in training).

Higher coverage means more diversity and discovery. Extremely low coverage (e.g., 0.5% of the catalog) is a warning sign that your system is collapsing.

Popularity bias checks whether your model over-recommends already popular items. A beginner-friendly way is to compute the average (or median) popularity rank of recommended items. For each item, define popularity as training interaction count. Then compare:

• Average popularity of items recommended by each model.
• Distribution (top 1%, top 10%, long tail) of recommended items.

Common mistake: celebrating a small accuracy gain while coverage drops sharply. In practice, teams often accept slightly lower hit rate if it improves coverage and long‑tail exposure, because it increases user discovery and reduces monotony.

Outcome: you’ll have a more realistic picture of model quality—accuracy plus whether the system behaves like a healthy recommender.

Section 5.5: Comparing baselines vs improved models

Now you’ll run an A/B-style comparison across your three models using the same split and the same metrics. “A/B-style” here means a controlled, apples-to-apples offline test: identical users, identical train/test data, identical candidate filtering. The only difference is the recommendation algorithm.

Recommended comparison set:

• Model A: Random (or naive): recommend random unseen items. This sets a sanity-check floor; if your smarter models can’t beat random, something is wrong in your pipeline.
• Model B: Popularity baseline: recommend the most interacted-with items in training, excluding items the user has already seen.
• Model C: Item-to-item similarity: for a user, take their recent or highest-rated training items, find similar items, score candidates by summed similarity, and rank.

Compute hit rate and precision@k (k=10, 20), plus catalog coverage and a popularity bias summary for each model. Put results in a small table. This is your “evaluation harness”—a reusable tool you can keep as you improve the recommender.

Engineering judgment: keep the “user history” policy consistent. If your similarity model uses the last 3 items while popularity uses all history implicitly, you may accidentally give one model an advantage. Choose one approach (e.g., use all training items per user for similarity scoring) and document it.

Typical pattern you’ll observe:

• Random has very low hit rate and high coverage.
• Popularity has decent hit rate, low coverage, high popularity bias.
• Item-to-item often improves hit rate over popularity for engaged users and improves personalization, sometimes with slightly better coverage.

If your item-to-item model performs worse than popularity, investigate: similarity matrix built from too little data, wrong normalization, leaking test data, or failing to exclude already-seen items.

Section 5.6: Turning metrics into decisions and next steps

Metrics are only useful if they lead to decisions. Your final task is to write a short evaluation report—something you could send to a teammate. Keep it simple and concrete: what you tested, what you found, and what you recommend doing next.

A clear beginner-friendly report structure:

• Setup: dataset, time-aware split method (e.g., leave‑one‑out per user), k values, and any filtering (exclude seen items).
• Results table: hit rate@10/@20, precision@10/@20, coverage@10, and a popularity-bias summary (e.g., average item popularity).
• Conclusions: which model you would ship as the current offline winner and why (accuracy vs coverage trade-off).
• Risks: cold-start users/items, low coverage, or suspiciously high metrics that could indicate leakage.
• Next steps: one or two improvements to try (e.g., normalize similarity, use weighted recent history, add simple re-ranking for diversity, or test multiple holdout interactions per user).

Be explicit about trade-offs. For example: “Item-to-item improved hit rate@10 from 0.22 to 0.28 while increasing coverage from 1.5% to 4.0%. Popularity still wins on simplicity, but personalization appears real, so we’ll proceed with item-to-item and add a diversity constraint.”

Finally, remember what offline evaluation is—and isn’t. Offline metrics are a screening tool. The real goal is user impact, which requires online testing (true A/B tests) and product considerations like latency and explainability. But with the workflow in this chapter, you can make your first recommender improvements confidently and avoid the most common evaluation traps.

Section 6.1: Organizing code: functions, inputs, and outputs

Your notebook likely mixes data loading, cleaning, modeling, evaluation, and plotting in a single linear flow. To ship a mini recommender, reorganize that flow into functions with clear inputs and outputs. The goal is not “perfect architecture”; it’s a structure that makes it hard to misuse your code and easy to test small pieces.

A practical layout is: (1) data functions (load/clean), (2) model functions (fit/build similarities), and (3) serve functions (recommend). For example, define load_interactions(path) -> DataFrame, clean_interactions(df) -> DataFrame, build_item_similarity(df) -> (item_index, sim_matrix), and recommend(item_id, item_index, sim_matrix, top_k) -> List[item_id]. When each function returns a well-defined object, you can run the same pipeline from a script, a CLI, or a small local app.

• Inputs: file paths, configuration parameters (top_k, min_interactions), and IDs (user_id or item_id).
• Outputs: clean tables, model artifacts (similarities), and simple Python types (lists, dicts) that are easy to print or serialize.

Common mistakes here include silently relying on global notebook variables, embedding file paths in the middle of logic (“../data/ratings.csv”), and returning “whatever is convenient” instead of a stable type. A good habit is to put all file locations and tunable parameters in one place (even a small config.py or a dict at the top of your script). Another good habit: validate assumptions early. If your interactions table must contain user_id, item_id, and rating (or event), check columns and raise a clear error message when something is missing. Defensive checks turn confusing failures into actionable feedback.

Finally, add basic privacy safety at this stage: avoid printing raw user-level rows in logs, and avoid writing debug CSV files that contain user IDs. If you need debugging output, prefer aggregate counts (e.g., “number of users/items, sparsity, min/max timestamp”) rather than per-user slices.

Section 6.2: Saving and loading precomputed similarities

Computing item-to-item similarities can be the slowest step, especially as you move from toy data to a product catalog. A mini product should not recompute similarities every time a user asks for recommendations. Instead, split your workflow into two phases: offline build (compute artifacts) and online recommend (load artifacts, serve results quickly).

In practice, you will store: (1) an item index mapping item IDs to matrix row indices, and (2) the similarity representation itself. For small datasets you can store a dense matrix; for anything beyond that, prefer a sparse format or store only the top-N neighbors per item.

• Dense matrix: simple but large; good for a few thousand items.
• Sparse matrix: smaller; better when most item pairs have near-zero similarity.
• Top-N neighbors: fastest to serve; store for each item a list of (neighbor_item_id, score).

A practical “first ship” approach is top-N neighbors. During offline build, for each item, compute its most similar items and write them to a JSON or Parquet file. Then serving becomes “load neighbors, filter, return.” This is also safer: you avoid accidentally exposing full user-item matrices or internal debugging tables. Your artifacts can be designed to contain only item IDs and similarity scores—no personal data.

Common mistakes: saving artifacts without versioning, mixing artifacts from different datasets, and forgetting that item IDs may change. Create a tiny version stamp that includes (a) dataset name, (b) build date, and (c) key parameters (similarity metric, minimum interactions). If someone rebuilds with a different filtering rule, the filename should change. This prevents “it runs but results look wrong” scenarios that are hard to diagnose.

When loading artifacts, validate them. Check that the neighbor lists refer to items that exist in your current catalog. If an item is missing, skip it rather than crashing. This is a good example of engineering judgment: correctness matters, but reliability and graceful behavior matter too, especially when your product catalog updates.

Section 6.3: A simple interface: CLI or minimal local app

A notebook is an interface for you; a mini product needs an interface for someone else. The simplest is a command-line interface (CLI) that accepts an item ID or a user ID and prints recommendations. This is perfect for a first version because it forces you to define clean inputs, outputs, and error messages without building a full web app.

A minimal CLI typically supports two commands: build (offline artifacts) and recommend (online serving). For example: python recommend.py build --interactions data/interactions.csv --out artifacts/ and python recommend.py recommend --item_id B001 --k 10. Your script should load artifacts from disk, look up the requested item, and print a ranked list with scores.

• Helpful output: show item titles/names, not only IDs; include scores; include a short “why” line such as “similar customers interacted with these.”
• Graceful errors: if the item is unknown, return a fallback list (popular items) and explain the fallback.
• Determinism: results should be repeatable for the same inputs and artifacts.

If you prefer a minimal local app, you can still keep it simple: a single page that takes an item name and shows “more like this.” The key is the same separation of concerns: the app calls a recommend() function; it does not rebuild similarities on each request.

This is also the right moment to add basic safety and privacy habits. Do not log raw inputs that contain personal identifiers. In a CLI, that means being cautious when you accept user_id. If you must support user-based recommendations, log only a hashed or truncated identifier, or log nothing at all. Avoid printing “users like you also bought…” if it implies sensitive inference. Your first version can focus on item-to-item suggestions, which are often easier to ship safely because they can be computed and served without exposing user-specific histories.

A common mistake is turning the CLI into a tangle of logic. Keep CLI code thin: parse arguments, call library functions, print results. Put real logic in importable modules so you can reuse it later in a web service or batch job.

Section 6.4: Working with product catalogs: categories and price

Swapping from movies to products changes your data in two important ways. First, product catalogs usually include structured metadata such as category, brand, and price. Second, interactions are often implicit (views, clicks, add-to-cart, purchases) rather than explicit star ratings. Your recommender should adapt to both.

Start by creating a clean “catalog table” with columns like item_id, title, category, and price. Then decide how these fields influence recommendations. For a first version, treat metadata as filters and guardrails, not as the main model. For example, after producing similarity-based candidates, you might filter out items that are out of stock (if you have that field) and optionally keep items within a price band.

• Category guardrail: ensure recommendations remain in the same category, or allow a small set of “neighbor categories.”
• Price guardrail: avoid recommending items 10x more expensive unless explicitly intended.
• Deduping: remove the queried item itself and near-duplicates (same title/variant) when possible.

If your interaction data is implicit, you must choose a simple weighting rule. A beginner-friendly approach is to map events to numeric weights (view=1, cart=3, purchase=5) and sum per (user_id, item_id). This produces an “interaction strength” matrix that still works with cosine similarity. The important engineering judgment is consistency: keep the mapping stable and document it, because changing weights changes the meaning of similarity.

Common mistakes: ignoring metadata entirely (leading to weird cross-category suggestions), using price as a raw numeric feature in similarity without normalization, and forgetting that categories can be messy (spelling variants, multi-label categories). Clean categories with simple rules: trim whitespace, standardize case, and decide how to handle multi-category items (pick primary category or split). The goal is not perfect taxonomy; it’s preventing obviously wrong recommendations in your demo.

Finally, remember privacy: product metadata is usually safe, but interactions can be sensitive. Keep your shipped artifacts focused on item-item neighbors and item metadata; avoid shipping per-user interaction logs.

Section 6.5: Cold start solutions: new users and new items

Cold start is what happens when you cannot recommend because you have too little data. In a mini product, you need a friendly behavior for (1) new users with no history and (2) new items with no interactions. You can handle both with simple, practical fallbacks—no complex deep learning required.

For new users, the baseline is your popularity recommender from earlier chapters. Make it context-aware: choose popular items by category or by “trending in the last N days” if you have timestamps. If you support a CLI, allow an optional --category argument so a new user can get relevant popular items immediately.

For new items, item-to-item similarity cannot help because there are no interactions. Use metadata: recommend within the same category and similar price range, or use simple text similarity on titles/descriptions if available. Even a rule like “show top sellers in the same category” is acceptable for a first version, as long as you are explicit that it is a cold-start fallback.

• Hybrid fallback logic: if item has neighbors, use them; else use category-popular; if category missing, use global popular.
• Minimum data thresholds: don’t compute neighbors for items with < X interactions; route them to fallback.
• Explainability: return a short reason string (“Popular in Electronics” or “Similar items based on co-purchases”).

Common mistakes: returning an empty list, crashing on unknown IDs, or pretending a cold-start list is personalized. The practical outcome you want is robustness: every query returns something reasonable, and the user can tell why they got those results.

Privacy also matters here. Cold start often tempts teams to use any available user attributes. For this course’s safe habits, keep personal attributes out of your first version. Don’t infer or store sensitive traits. Use session-level signals (current item, chosen category) and global aggregates (popular items) instead.

Section 6.6: Final project wrap-up and improvement roadmap

You now have the core elements of a mini recommender product: reusable functions, offline-built similarity artifacts, a simple CLI interface, and a dataset swap from movies to products with sensible guardrails. The last step is to ship deliberately: add a final checklist, run through it, and tag a “v1” you can show.

• Reproducibility: a single command builds artifacts from raw data; a second command serves recommendations.
• Environment: requirements pinned; instructions in README; data paths configurable.
• Evaluation: basic metrics computed (e.g., precision@k or hit-rate@k on a simple split) and written to a results file.
• Fallbacks: unknown item/user handled; cold start returns popular/category-popular.
• Safety & privacy: no raw user logs shipped; no debug dumps with identifiers; logs use aggregates.
• Quality guardrails: filters for duplicates, out-of-catalog items, optional category/price constraints.

As an improvement roadmap, focus on changes that deliver clear value without exploding complexity. Good next steps include: (1) better offline evaluation (time-based split, compare popularity vs similarity), (2) top-N neighbor storage for speed, (3) simple diversity controls (don’t recommend near-identical variants repeatedly), and (4) incremental updates (rebuild artifacts nightly rather than manually).

If you want to move toward a real service, you can wrap the same recommend() function in a small local API. But keep your discipline: avoid mixing training and serving, validate inputs, and keep personal data out of logs. Your “first shipped version” is not about perfect recommendations; it’s about building a system that runs predictably, is safe to share, and gives sensible outputs under real-world conditions. That’s the bridge from notebook to product—and it’s the skill that makes your work usable.