# NicolasHug/Surprise

A Python scikit for building and analyzing recommender systems

Repository: https://github.com/NicolasHug/Surprise
Canonical: https://ross.abutalabs.com/products/surprise
Homepage: http://surpriselib.com
Language: Python
License: BSD-3-Clause
License Family: permissive
Topics: recommender, systems, recommendation, svd, matrix, factorization, machine-learning
Last push: 2026-05-30T17:11:41+00:00

## Health v2 (maintenance only)
Score: 70/100 (v2, computed 2026-09-02T17:46:02.011165+00:00)
- activity 85, release rhythm 35, longevity 100
- inputs: {"age_days": 3601, "days_push": 95, "days_rel": null, "gap_med": null, "n_releases_24m": 0}
- flags: no_releases
- formula: round(0.45*activity + 0.35*rhythm + 0.20*longevity); archived -> min(score, 10)

## Adoption (not part of the score)
Stars 6808, forks 1051 (observed 2026-08-28T04:09:48.735878+00:00)

## What it is
Surprise is a Python scikit for building and analyzing recommender systems that work with explicit rating data. It provides ready-to-use prediction algorithms (SVD, SVD++, NMF, neighborhood methods), built-in datasets, similarity measures, and cross-validation tools inspired by scikit-learn.

## Use cases
- build a movie recommendation engine with collaborative filtering
- run cross-validation on recommender algorithms with RMSE and MAE metrics
- train an SVD matrix factorization model on rating data
- benchmark and compare different recommendation algorithms
- prototype a custom rating prediction algorithm
- load and preprocess Movielens or custom explicit rating datasets

## When to choose
- you work with explicit rating data and want well-documented, reproducible experiments
- you need classic collaborative filtering algorithms like SVD, KNN, or NMF out of the box
- you want scikit-learn-style cross-validation and grid search for recommenders

## When to avoid
- your data is implicit feedback (clicks, views) rather than explicit ratings
- you need content-based or hybrid recommendation with item metadata
- you need a production-scale distributed recommender system

## Facets
- artifact type: library
- maturity: stable
- function: machine-learning, data-science, benchmarking
- domain: machine-learning, data-science
- platform: python, cross-platform
- tags: recommender-systems, collaborative-filtering, matrix-factorization, svd, explicit-ratings, scikit, algorithms

## Member repositories
- NicolasHug/Surprise (main) score 70

## Provenance
- Observed fields: from GitHub, fetched 2026-08-28T04:09:48.735878+00:00.
- Health v2: computed from the inputs above; adoption is never an input.
- Inferred fields (summary, facets, guidance): AI-extracted, prompt v1, taxonomy v1, on 2026-08-29T17:42:02.361839+00:00, confidence not recorded.
  - readme: https://github.com/NicolasHug/Surprise (fetched 2026-08-28T04:09:48.735878+00:00, sha 1dc64d649a3e)
  - homepage: http://surpriselib.com (fetched 2026-08-29T08:38:05.572346+00:00, sha f88f9f93b4bd)
- Data as of 2026-08-30T08:39:29.467469+00:00.