mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
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]>
723 lines
35 KiB
HTML
723 lines
35 KiB
HTML
<!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):
|
||
"""Recommend based on similar users"""
|
||
# 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' ratings
|
||
numerator = 0
|
||
denominator = 0
|
||
for sim_user in similar_users:
|
||
if ratings[sim_user, item_id] > 0:
|
||
numerator += user_sim[user_id, sim_user] * ratings[sim_user, item_id]
|
||
denominator += user_sim[user_id, sim_user]
|
||
|
||
if denominator > 0:
|
||
predictions[item_id] = numerator / denominator
|
||
|
||
return predictions
|
||
|
||
# Item-based collaborative filtering
|
||
def item_based_cf(ratings, user_id, k=2):
|
||
"""Recommend based on similar items"""
|
||
# 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] > 0:
|
||
numerator += item_sim[item_id, sim_item] * user_ratings[sim_item]
|
||
denominator += item_sim[item_id, sim_item]
|
||
|
||
if denominator > 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"User-based predictions: {user_preds}")
|
||
print(f"Item-based predictions: {item_preds}")</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):
|
||
"""SVD-based matrix factorization"""
|
||
# 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"Top recommendations for user {user_id}: {recommended_items[:3]}")</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 = [
|
||
"smartphone with 5G camera",
|
||
"laptop with SSD storage",
|
||
"wireless headphones bluetooth",
|
||
"tablet with stylus pen",
|
||
"smartwatch fitness tracker"
|
||
]
|
||
|
||
# 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'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"Content-based recommendations: {recommended_items[:3]}")
|
||
for idx in recommended_items[:3]:
|
||
print(f" {items[idx]} (score: {similarities[idx]:.3f})")</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):
|
||
"""Weighted hybrid of CF and content-based"""
|
||
# Collaborative filtering score
|
||
cf_scores = item_based_cf(ratings, user_id)
|
||
|
||
# Content-based score
|
||
user_liked_items = np.where(ratings[user_id] > 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"Hybrid recommendations: {recommended[:3]}")</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"Recommendations: {recommendations}")</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):
|
||
"""Recommend new item to users based on content similarity"""
|
||
# 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] > 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):
|
||
"""Recommend items to new user based on stated preferences"""
|
||
# 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 = "wireless headphones with noise cancellation"
|
||
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):
|
||
"""MMR-style diversification"""
|
||
selected = []
|
||
remaining = list(candidate_items)
|
||
|
||
while len(selected) < 10 and remaining:
|
||
best_item = None
|
||
best_score = -float('inf')
|
||
|
||
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 > 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):
|
||
"""Recommend items based on current session"""
|
||
# 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):
|
||
"""Build user profile with recency weighting"""
|
||
user_profile = np.zeros(item_features.shape[1])
|
||
total_weight = 0
|
||
|
||
for interaction in user_interactions:
|
||
item_id = interaction['item_id']
|
||
timestamp = interaction['timestamp']
|
||
rating = interaction.get('rating', 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 > 0:
|
||
user_profile /= total_weight
|
||
|
||
return user_profile
|
||
|
||
# Example
|
||
interactions = [
|
||
{'item_id': 0, 'timestamp': datetime.now() - timedelta(days=5), 'rating': 5},
|
||
{'item_id': 2, 'timestamp': datetime.now() - timedelta(days=30), 'rating': 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):
|
||
"""Adjust recommendations based on context"""
|
||
# 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['time_of_day'] == 'morning':
|
||
context_boosts[context_features['category'] == 'news'] *= 1.5
|
||
elif context['time_of_day'] == 'evening':
|
||
context_boosts[context_features['category'] == 'entertainment'] *= 1.5
|
||
|
||
# Location-based
|
||
if context['location'] == 'home':
|
||
context_boosts[context_features['category'] == 'home_goods'] *= 1.3
|
||
|
||
# Device-based
|
||
if context['device'] == 'mobile':
|
||
context_boosts[context_features['mobile_friendly'] == 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):
|
||
"""Evaluate with Precision@k, Recall@k, nDCG@k"""
|
||
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) & 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 > 0 else 0
|
||
ndcgs.append(ndcg)
|
||
|
||
return {
|
||
'precision@k': np.mean(precisions),
|
||
'recall@k': np.mean(recalls),
|
||
'ndcg@k': 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'T: Use user-based CF for millions of users (doesn't scale)
|
||
❌ DON'T: Ignore implicit feedback (clicks, views, time spent)
|
||
❌ DON'T: Recommend only popular items (hurts diversity)
|
||
❌ DON'T: Deploy without offline evaluation first
|
||
❌ DON'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's history</p>
|
||
<h3>Common Mistakes</h3>
|
||
<pre><code class="lang-python"># ❌ Don'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):
|
||
"""Combine personalization with popularity"""
|
||
# 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't: Use only explicit ratings
|
||
# Most users don't rate, lose 95%+ of signals
|
||
ratings_matrix = explicit_ratings_only
|
||
|
||
# ✅ Correct: Use implicit feedback
|
||
implicit_signals = {
|
||
'click': 1,
|
||
'add_to_cart': 2,
|
||
'purchase': 5,
|
||
'review': 3
|
||
}
|
||
|
||
# Build ratings from all interactions
|
||
for interaction in user_interactions:
|
||
rating = implicit_signals.get(interaction['type'], 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't: Train on all data, no holdout
|
||
model.fit(all_interactions)
|
||
# Can'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['timestamp'] < train_cutoff]
|
||
test_data = [x for x in interactions if x['timestamp'] >= train_cutoff]
|
||
|
||
model.fit(train_data)
|
||
metrics = evaluate(model, test_data)</code></pre>
|
||
<p>❌ <strong>No evaluation</strong>: Can'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> |