Build a nearest-neighbour recommendation explanation

A nearest-neighbour recommender can explain which item served as the reference and which features contributed to similarity. A faithful similarity explanation is narrower than “you will like this.”

Trace one query through the feature space

Item I4 has two binary tags: generative AI and Python. We calculate cosine similarity against the 20-item synthetic catalogue and exclude I4 itself.

The closest item is I13 with cosine approximately 1.0 because it has the same two tags. I5 scores 0.5 through the shared generative-AI tag, and I0 scores 0.5 through Python. The ordered result follows the exact feature vectors and stable tie rule.

from unsupervised_cases import neighbour_explanation_case

r = neighbour_explanation_case()
assert r['query'] == 'I4'
assert r['query_tags'] == ['genai', 'python']
assert r['neighbours'][0]['item'] == 'I13'
assert r['neighbours'][0]['shared_tags'] == ['python', 'genai']
assert abs(r['neighbours'][0]['cosine'] - 1) < 1e-12
print(r)

Run it in the unsupervised lab. The scikit-learn cosine reference defines the normalized dot product used by the explanation.

Keep the explanation faithful to the scoring path

If the production score combines content, popularity, freshness and collaborative signals, a shared-tag sentence explains only one component. Record the candidate source, feature version, model version and re-ranking steps. Avoid presenting a post-hoc story that did not affect the score.

Binary overlap can overvalue broad tags. TF-IDF or learned embeddings change the score and the explanation vocabulary. Missing metadata can make similarity look low. Tag governance and item-version history are therefore part of explainability.

User-facing text should remain modest: “similar because both include Python and generative AI.” It should not infer career goals, expertise or personal identity. Let users dismiss an explanation or correct preferences where appropriate.

Evaluate explanation fidelity separately from recommendation relevance and human usefulness. An exact mathematical explanation can be unhelpful, and a plausible sentence can be unfaithful.

Exercise: add weighted tags and a popularity re-ranker. Calculate each component's contribution to the final score and design an explanation that remains accurate after re-ranking. Add an automated test that fails if a named shared tag is absent.

NeuraPath's Data Science course connects explanations to the exact scoring computation. A transparent neighbour baseline makes fidelity testable.

Continue learning

This article is part of the Clustering, reduction and recommendations sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Implicit feedback: missing interaction is not dislike.
• Continue with Anomaly detection: validate alerts before calling them fraud.