Files
skills/public/ir-recommendation-systems.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

723 lines
35 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>ir-recommendation-systems</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/ir-recommendation-systems.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/ir-recommendation-systems">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/ir-recommendation-systems.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>ir-recommendation-systems</h1><p class="lede">Collaborative filtering, content-based filtering, hybrid recommenders, matrix factorization, and cold start solutions</p><h1>Information Retrieval: Recommendation Systems</h1>
<p><strong>Scope</strong>: Collaborative filtering (user/item-based, matrix factorization), content-based filtering, hybrid approaches, neural collaborative filtering, and cold start handling <strong>Lines</strong>: ~380 <strong>Last Updated</strong>: 2025-10-25 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<hr>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Building product, content, or user recommendations</li><li>Implementing collaborative filtering (user-user or item-item)</li><li>Using matrix factorization techniques (SVD, ALS)</li><li>Combining content features with behavioral data (hybrid)</li><li>Solving cold start problems for new users or items</li><li>Evaluating recommendation quality offline and online</li><li>Personalizing content feeds or search results</li><li>Increasing user engagement through relevant suggestions</li></ul>
<h2>Core Concepts</h2>
<h3>Concept 1: Collaborative Filtering</h3>
<p><strong>User-Based</strong>: Recommend items liked by similar users <strong>Item-Based</strong>: Recommend items similar to what user liked <strong>Matrix Factorization</strong>: Decompose user-item matrix into latent factors</p>
<pre><code class="lang-python">import numpy as np
from sklearn.metrics.pairwise import cosine_similarity
# User-Item matrix (rows=users, cols=items, values=ratings)
ratings = np.array([
[5, 3, 0, 1], # User 0
[4, 0, 0, 1], # User 1
[1, 1, 0, 5], # User 2
[1, 0, 0, 4], # User 3
[0, 1, 5, 4], # User 4
])
# User-based collaborative filtering
def user_based_cf(ratings, user_id, k=2):
&quot;&quot;&quot;Recommend based on similar users&quot;&quot;&quot;
# Compute user similarities
user_sim = cosine_similarity(ratings)
# Find k most similar users (exclude self)
similar_users = np.argsort(user_sim[user_id])[::-1][1:k+1]
# Predict ratings for unrated items
user_ratings = ratings[user_id]
predictions = np.zeros(ratings.shape[1])
for item_id in range(ratings.shape[1]):
if user_ratings[item_id] == 0: # Unrated item
# Weighted average of similar users&#x27; ratings
numerator = 0
denominator = 0
for sim_user in similar_users:
if ratings[sim_user, item_id] &gt; 0:
numerator += user_sim[user_id, sim_user] * ratings[sim_user, item_id]
denominator += user_sim[user_id, sim_user]
if denominator &gt; 0:
predictions[item_id] = numerator / denominator
return predictions
# Item-based collaborative filtering
def item_based_cf(ratings, user_id, k=2):
&quot;&quot;&quot;Recommend based on similar items&quot;&quot;&quot;
# Compute item similarities
item_sim = cosine_similarity(ratings.T)
user_ratings = ratings[user_id]
predictions = np.zeros(ratings.shape[1])
for item_id in range(ratings.shape[1]):
if user_ratings[item_id] == 0: # Unrated item
# Find k most similar items user has rated
similar_items = np.argsort(item_sim[item_id])[::-1]
numerator = 0
denominator = 0
for sim_item in similar_items:
if user_ratings[sim_item] &gt; 0:
numerator += item_sim[item_id, sim_item] * user_ratings[sim_item]
denominator += item_sim[item_id, sim_item]
if denominator &gt; 0:
predictions[item_id] = numerator / denominator
return predictions
# Test
user_id = 0
user_preds = user_based_cf(ratings, user_id, k=2)
item_preds = item_based_cf(ratings, user_id, k=2)
print(f&quot;User-based predictions: {user_preds}&quot;)
print(f&quot;Item-based predictions: {item_preds}&quot;)</code></pre>
<h3>Concept 2: Matrix Factorization</h3>
<p><strong>Decomposition</strong>: <code>R ≈ U × V^T</code></p>
<ul><li><code>R</code>: user-item ratings (m × n)</li><li><code>U</code>: user factors (m × k)</li><li><code>V</code>: item factors (n × k)</li><li><code>k</code>: latent dimensions (typically 10-200)</li></ul>
<p><strong>Algorithms</strong>:</p>
<ul><li>SVD (Singular Value Decomposition)</li><li>ALS (Alternating Least Squares)</li><li>SGD (Stochastic Gradient Descent)</li></ul>
<pre><code class="lang-python">from scipy.sparse.linalg import svds
def matrix_factorization_svd(ratings, k=2):
&quot;&quot;&quot;SVD-based matrix factorization&quot;&quot;&quot;
# Handle missing values: replace 0s with row mean
ratings_mean = np.mean(ratings, axis=1, keepdims=True)
ratings_filled = ratings.copy()
ratings_filled[ratings == 0] = np.repeat(ratings_mean, ratings.shape[1], axis=1)[ratings == 0]
# SVD
U, sigma, Vt = svds(ratings_filled, k=k)
# Reconstruct ratings
sigma = np.diag(sigma)
predicted_ratings = np.dot(np.dot(U, sigma), Vt)
return predicted_ratings, U, Vt.T
# Predict
predicted_ratings, user_factors, item_factors = matrix_factorization_svd(ratings, k=2)
# Recommend for user 0
user_id = 0
user_predictions = predicted_ratings[user_id]
unrated_items = np.where(ratings[user_id] == 0)[0]
recommended_items = sorted(unrated_items, key=lambda x: user_predictions[x], reverse=True)
print(f&quot;Top recommendations for user {user_id}: {recommended_items[:3]}&quot;)</code></pre>
<h3>Concept 3: Content-Based Filtering</h3>
<p><strong>Idea</strong>: Recommend items similar to what user liked based on item features</p>
<p><strong>Features</strong>:</p>
<ul><li>Text: TF-IDF, embeddings</li><li>Categories: one-hot encoding</li><li>Attributes: price, brand, color</li><li>Media: image embeddings, audio features</li></ul>
<pre><code class="lang-python">from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.metrics.pairwise import cosine_similarity
# Item descriptions
items = [
&quot;smartphone with 5G camera&quot;,
&quot;laptop with SSD storage&quot;,
&quot;wireless headphones bluetooth&quot;,
&quot;tablet with stylus pen&quot;,
&quot;smartwatch fitness tracker&quot;
]
# Extract TF-IDF features
vectorizer = TfidfVectorizer()
item_features = vectorizer.fit_transform(items)
# User profile: aggregate features of items user liked
user_liked_items = [0, 2] # Liked smartphone and headphones
user_profile = item_features[user_liked_items].mean(axis=0)
# Compute similarity to all items
similarities = cosine_similarity(user_profile, item_features)[0]
# Recommend items user hasn&#x27;t interacted with
recommended_indices = np.argsort(similarities)[::-1]
recommended_items = [i for i in recommended_indices if i not in user_liked_items]
print(f&quot;Content-based recommendations: {recommended_items[:3]}&quot;)
for idx in recommended_items[:3]:
print(f&quot; {items[idx]} (score: {similarities[idx]:.3f})&quot;)</code></pre>
<h3>Concept 4: Hybrid Recommenders</h3>
<p><strong>Approaches</strong>:</p>
<p><strong>Weighted</strong>: Combine CF and content-based scores</p>
<pre><code>score = α × CF_score + (1-α) × content_score</code></pre>
<p><strong>Switching</strong>: Choose method based on context</p>
<ul><li>New users → content-based</li><li>Established users → collaborative</li></ul>
<p><strong>Feature Augmentation</strong>: Add content features to CF model</p>
<p><strong>Cascade</strong>: Use one method to filter, another to rank</p>
<pre><code class="lang-python">def hybrid_recommender(user_id, ratings, item_features, alpha=0.5):
&quot;&quot;&quot;Weighted hybrid of CF and content-based&quot;&quot;&quot;
# Collaborative filtering score
cf_scores = item_based_cf(ratings, user_id)
# Content-based score
user_liked_items = np.where(ratings[user_id] &gt; 0)[0]
user_profile = item_features[user_liked_items].mean(axis=0)
content_scores = cosine_similarity(user_profile, item_features)[0]
# Normalize scores to 0-1
cf_norm = (cf_scores - cf_scores.min()) / (cf_scores.max() - cf_scores.min() + 1e-9)
content_norm = (content_scores - content_scores.min()) / (content_scores.max() - content_scores.min() + 1e-9)
# Weighted combination
hybrid_scores = alpha * cf_norm + (1 - alpha) * content_norm
# Recommend unrated items
unrated_items = np.where(ratings[user_id] == 0)[0]
recommended_items = sorted(unrated_items, key=lambda x: hybrid_scores[x], reverse=True)
return recommended_items, hybrid_scores
# Test
recommended, scores = hybrid_recommender(0, ratings, item_features, alpha=0.6)
print(f&quot;Hybrid recommendations: {recommended[:3]}&quot;)</code></pre>
<hr>
<h2>Patterns</h2>
<h3>Pattern 1: Implicit Feedback (Clicks, Views, Purchases)</h3>
<p><strong>When to use</strong>: No explicit ratings, only behavioral signals</p>
<pre><code class="lang-python"># Implicit feedback: 1 = interacted, 0 = not interacted
implicit_ratings = np.array([
[1, 1, 0, 0], # User 0 clicked items 0, 1
[1, 0, 0, 1], # User 1 clicked items 0, 3
[0, 1, 0, 1],
[0, 0, 1, 1],
])
from implicit.als import AlternatingLeastSquares
# Convert to sparse matrix (required by implicit library)
from scipy.sparse import csr_matrix
sparse_ratings = csr_matrix(implicit_ratings)
# Train ALS model
model = AlternatingLeastSquares(factors=10, iterations=20, regularization=0.01)
model.fit(sparse_ratings)
# Recommend for user
user_id = 0
recommendations = model.recommend(user_id, sparse_ratings[user_id], N=3)
print(f&quot;Recommendations: {recommendations}&quot;)</code></pre>
<h3>Pattern 2: Cold Start - Content Bootstrapping</h3>
<p><strong>Use case</strong>: New items or users with no interaction history</p>
<pre><code class="lang-python">def cold_start_item(new_item_features, item_features, ratings, top_k=5):
&quot;&quot;&quot;Recommend new item to users based on content similarity&quot;&quot;&quot;
# Find most similar existing items
similarities = cosine_similarity([new_item_features], item_features)[0]
similar_items = np.argsort(similarities)[::-1][:top_k]
# Recommend to users who liked similar items
recommended_users = []
for user_id in range(ratings.shape[0]):
user_ratings = ratings[user_id]
# Check if user liked similar items
if any(user_ratings[item_id] &gt; 0 for item_id in similar_items):
recommended_users.append(user_id)
return recommended_users
def cold_start_user(user_preferences, item_features, top_k=5):
&quot;&quot;&quot;Recommend items to new user based on stated preferences&quot;&quot;&quot;
# User provides initial preferences (e.g., survey, onboarding)
# preferences: text description or selected categories
# Convert preferences to feature vector
user_vector = vectorizer.transform([user_preferences])
# Find similar items
similarities = cosine_similarity(user_vector, item_features)[0]
recommended_items = np.argsort(similarities)[::-1][:top_k]
return recommended_items
# Example
new_user_prefs = &quot;wireless headphones with noise cancellation&quot;
recommendations = cold_start_user(new_user_prefs, item_features, top_k=3)</code></pre>
<h3>Pattern 3: Diversity and Serendipity</h3>
<p><strong>When to use</strong>: Avoid filter bubbles, increase discovery</p>
<pre><code class="lang-python">def diversified_recommendations(user_id, candidate_items, item_features, scores, diversity_weight=0.3):
&quot;&quot;&quot;MMR-style diversification&quot;&quot;&quot;
selected = []
remaining = list(candidate_items)
while len(selected) &lt; 10 and remaining:
best_item = None
best_score = -float(&#x27;inf&#x27;)
for item in remaining:
# Relevance score
relevance = scores[item]
# Diversity penalty: similarity to selected items
if selected:
similarities = cosine_similarity(
item_features[item].reshape(1, -1),
item_features[selected]
)[0]
diversity_penalty = max(similarities)
else:
diversity_penalty = 0
# MMR score
mmr = relevance - diversity_weight * diversity_penalty
if mmr &gt; best_score:
best_score = mmr
best_item = item
selected.append(best_item)
remaining.remove(best_item)
return selected</code></pre>
<h3>Pattern 4: Session-Based Recommendations</h3>
<p><strong>Use case</strong>: Recommend based on current session (e.g., shopping cart)</p>
<pre><code class="lang-python">def session_based_recommendations(session_items, item_similarity_matrix, top_k=5):
&quot;&quot;&quot;Recommend items based on current session&quot;&quot;&quot;
# Aggregate item similarities for session
session_scores = np.zeros(item_similarity_matrix.shape[0])
for item_id in session_items:
# Add similarity scores from this item
session_scores += item_similarity_matrix[item_id]
# Remove already selected items
session_scores[session_items] = -np.inf
# Top-k recommendations
recommended_items = np.argsort(session_scores)[::-1][:top_k]
return recommended_items
# Example: User has items [0, 2] in cart
cart_items = [0, 2]
session_recs = session_based_recommendations(cart_items, item_sim, top_k=3)</code></pre>
<h3>Pattern 5: Temporal Dynamics (Recency Weighting)</h3>
<p><strong>When to use</strong>: User preferences change over time</p>
<pre><code class="lang-python">import numpy as np
from datetime import datetime, timedelta
def time_weighted_user_profile(user_interactions, item_features, decay_days=30):
&quot;&quot;&quot;Build user profile with recency weighting&quot;&quot;&quot;
user_profile = np.zeros(item_features.shape[1])
total_weight = 0
for interaction in user_interactions:
item_id = interaction[&#x27;item_id&#x27;]
timestamp = interaction[&#x27;timestamp&#x27;]
rating = interaction.get(&#x27;rating&#x27;, 1)
# Time decay: exponential decay based on age
days_ago = (datetime.now() - timestamp).days
weight = np.exp(-days_ago / decay_days) * rating
user_profile += weight * item_features[item_id]
total_weight += weight
if total_weight &gt; 0:
user_profile /= total_weight
return user_profile
# Example
interactions = [
{&#x27;item_id&#x27;: 0, &#x27;timestamp&#x27;: datetime.now() - timedelta(days=5), &#x27;rating&#x27;: 5},
{&#x27;item_id&#x27;: 2, &#x27;timestamp&#x27;: datetime.now() - timedelta(days=30), &#x27;rating&#x27;: 4},
]
user_profile = time_weighted_user_profile(interactions, item_features)</code></pre>
<h3>Pattern 6: Contextual Recommendations</h3>
<p><strong>Use case</strong>: Consider context (time, location, device, weather)</p>
<pre><code class="lang-python">def contextual_recommendations(user_id, context, ratings, context_features):
&quot;&quot;&quot;Adjust recommendations based on context&quot;&quot;&quot;
# Base recommendations
base_scores = item_based_cf(ratings, user_id)
# Context adjustments
context_boosts = np.ones(len(base_scores))
# Time-based: morning vs evening
if context[&#x27;time_of_day&#x27;] == &#x27;morning&#x27;:
context_boosts[context_features[&#x27;category&#x27;] == &#x27;news&#x27;] *= 1.5
elif context[&#x27;time_of_day&#x27;] == &#x27;evening&#x27;:
context_boosts[context_features[&#x27;category&#x27;] == &#x27;entertainment&#x27;] *= 1.5
# Location-based
if context[&#x27;location&#x27;] == &#x27;home&#x27;:
context_boosts[context_features[&#x27;category&#x27;] == &#x27;home_goods&#x27;] *= 1.3
# Device-based
if context[&#x27;device&#x27;] == &#x27;mobile&#x27;:
context_boosts[context_features[&#x27;mobile_friendly&#x27;] == 1] *= 1.2
# Apply boosts
adjusted_scores = base_scores * context_boosts
return np.argsort(adjusted_scores)[::-1]</code></pre>
<h3>Pattern 7: Evaluation - Offline Metrics</h3>
<p><strong>When to use</strong>: Validate recommender before deployment</p>
<pre><code class="lang-python">def evaluate_recommender(test_data, predict_fn, k=10):
&quot;&quot;&quot;Evaluate with Precision@k, Recall@k, nDCG@k&quot;&quot;&quot;
precisions = []
recalls = []
ndcgs = []
for user_id, ground_truth_items in test_data:
# Get recommendations
recommendations = predict_fn(user_id, k=k)
# Precision@k
relevant_in_top_k = len(set(recommendations) &amp; set(ground_truth_items))
precision = relevant_in_top_k / k
precisions.append(precision)
# Recall@k
recall = relevant_in_top_k / len(ground_truth_items) if ground_truth_items else 0
recalls.append(recall)
# nDCG@k (binary relevance)
dcg = sum([1 / np.log2(i + 2) for i, item in enumerate(recommendations) if item in ground_truth_items])
idcg = sum([1 / np.log2(i + 2) for i in range(min(k, len(ground_truth_items)))])
ndcg = dcg / idcg if idcg &gt; 0 else 0
ndcgs.append(ndcg)
return {
&#x27;precision@k&#x27;: np.mean(precisions),
&#x27;recall@k&#x27;: np.mean(recalls),
&#x27;ndcg@k&#x27;: np.mean(ndcgs)
}
# Example
test_data = [
(0, [2, 3]), # User 0 interacted with items 2, 3 in test set
(1, [1, 3]),
]
metrics = evaluate_recommender(test_data, lambda u, k: item_based_cf(ratings, u)[:k], k=5)
print(metrics)</code></pre>
<hr>
<h2>Quick Reference</h2>
<h3>Recommendation Approaches</h3>
<pre><code>Approach | Pros | Cons
--------------------|--------------------------------|---------------------
User-based CF | Serendipity, novel items | Scalability, sparsity
Item-based CF | Scalable, stable | Less diversity
Matrix Factorization| Scalable, handles sparsity | Cold start
Content-based | No cold start for items | Overspecialization
Hybrid | Best of both worlds | Complexity</code></pre>
<h3>Evaluation Metrics</h3>
<pre><code>Metric | Formula | Interpretation
--------------|------------------------------|----------------
Precision@k | relevant_in_top_k / k | Accuracy of top-k
Recall@k | relevant_in_top_k / total | Coverage of relevant
nDCG@k | DCG / IDCG (position aware) | Ranking quality
Hit Rate | users_with_hit / total_users | At least one relevant
Coverage | recommended_items / all_items| Catalog coverage</code></pre>
<h3>Key Guidelines</h3>
<pre><code>✅ DO: Use item-based CF for large user bases (more scalable)
✅ DO: Combine collaborative and content-based (hybrid)
✅ DO: Handle cold start with content features or popularity
✅ DO: Diversify recommendations to avoid filter bubbles
✅ DO: Weight recent interactions more heavily
✅ DO: A/B test recommendations with engagement metrics
❌ DON&#x27;T: Use user-based CF for millions of users (doesn&#x27;t scale)
❌ DON&#x27;T: Ignore implicit feedback (clicks, views, time spent)
❌ DON&#x27;T: Recommend only popular items (hurts diversity)
❌ DON&#x27;T: Deploy without offline evaluation first
❌ DON&#x27;T: Forget to filter already consumed items</code></pre>
<hr>
<h2>Anti-Patterns</h2>
<h3>Critical Violations</h3>
<pre><code class="lang-python"># ❌ NEVER: Recommend items user already consumed
def bad_recommender(user_id, scores):
return np.argsort(scores)[::-1][:10]
# Might include items user already rated/bought
# ✅ CORRECT: Filter consumed items
def good_recommender(user_id, scores, user_history):
# Exclude already consumed
scores_filtered = scores.copy()
scores_filtered[user_history] = -np.inf
recommendations = np.argsort(scores_filtered)[::-1][:10]
return recommendations</code></pre>
<p>❌ <strong>Recommending consumed items</strong>: Terrible user experience ✅ <strong>Correct approach</strong>: Always filter user&#x27;s history</p>
<h3>Common Mistakes</h3>
<pre><code class="lang-python"># ❌ Don&#x27;t: Ignore popularity bias
# Popular items dominate, long tail gets no exposure
recommendations = top_rated_items[:10]
# ✅ Correct: Balance popularity with personalization
def debiased_recommendations(user_scores, item_popularity, alpha=0.7):
&quot;&quot;&quot;Combine personalization with popularity&quot;&quot;&quot;
# Normalize
user_scores_norm = user_scores / user_scores.max()
popularity_norm = item_popularity / item_popularity.max()
# Inverse popularity weighting
scores = user_scores_norm / (popularity_norm ** alpha + 1e-9)
return np.argsort(scores)[::-1]</code></pre>
<p>❌ <strong>Popularity bias</strong>: Long tail items never recommended ✅ <strong>Better</strong>: Inverse popularity weighting or diversity constraints</p>
<pre><code class="lang-python"># ❌ Don&#x27;t: Use only explicit ratings
# Most users don&#x27;t rate, lose 95%+ of signals
ratings_matrix = explicit_ratings_only
# ✅ Correct: Use implicit feedback
implicit_signals = {
&#x27;click&#x27;: 1,
&#x27;add_to_cart&#x27;: 2,
&#x27;purchase&#x27;: 5,
&#x27;review&#x27;: 3
}
# Build ratings from all interactions
for interaction in user_interactions:
rating = implicit_signals.get(interaction[&#x27;type&#x27;], 0)
ratings_matrix[user_id, item_id] += rating</code></pre>
<p>❌ <strong>Explicit ratings only</strong>: Massive data sparsity ✅ <strong>Better</strong>: Use implicit feedback (clicks, views, purchases)</p>
<pre><code class="lang-python"># ❌ Don&#x27;t: Train on all data, no holdout
model.fit(all_interactions)
# Can&#x27;t evaluate quality, might overfit
# ✅ Correct: Temporal split for evaluation
# Train on history, test on recent interactions
train_cutoff = datetime.now() - timedelta(days=7)
train_data = [x for x in interactions if x[&#x27;timestamp&#x27;] &lt; train_cutoff]
test_data = [x for x in interactions if x[&#x27;timestamp&#x27;] &gt;= train_cutoff]
model.fit(train_data)
metrics = evaluate(model, test_data)</code></pre>
<p>❌ <strong>No evaluation</strong>: Can&#x27;t measure quality or improvements ✅ <strong>Better</strong>: Temporal split, evaluate on future interactions</p>
<hr>
<h2>Related Skills</h2>
<ul><li><code>ir-search-fundamentals.md</code> - Content-based filtering uses IR techniques (TF-IDF, embeddings)</li><li><code>ir-vector-search.md</code> - Semantic similarity for content-based recommendations</li><li><code>ir-ranking-reranking.md</code> - Ranking metrics and learning to rank for recommendations</li><li><code>ml/dspy-rag.md</code> - Retrieval patterns similar to recommendation retrieval</li><li><code>database-postgres.md</code> - Store user-item interactions efficiently</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-25 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/ir-recommendation-systems.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>