flickpick

A personal movie recommender you can run in a browser, built so that AI agents can pick movies for you. It learns from your own ratings, scores the whole catalogue client-side, lets you ask for a mood ("slow-burn melancholic sci-fi, nothing gory"), and shows where a film streams and how the public rated it. A "for scientists" page compares your taste with the population's and measures how well the recommender does on your own history.

Try it in two commands

pip install "flickpick[embed]"
python -m flickpick build --sample --out ./artifacts          # a small artifact set from MovieLens ml-latest-small
python -m flickpick recommend --artifacts ./artifacts --ratings my_ratings.csv --mood "slow-burn melancholic sci-fi" --exclude-genre Horror

my_ratings.csv can be a Letterboxd, IMDb or MovieLens export, or flickpick's own format (see flickpick/data/examples/movie_ratings_various.csv). Drop --sample to build from MovieLens ml-32m (about 10,000 films; a few minutes). Drop [embed] and add --no-embeddings if you do not want mood search.

The same core exists in TypeScript (js/, npm flickpick) and runs in the browser; the web app is in web/. From a fresh clone (Node 20 or later):

cd js && npm ci && npm test && npm run build      # the TypeScript core; CLI: node dist/cli.js recommend --artifacts ../tests/fixtures/artifacts_small --ratings <csv>
cd web && npm install && npm run dev              # the web app; dev, build and test build ../js first when it is missing or stale

How it works

• Offline build (Python). MovieLens ratings train an EASE item-item model (a closed-form linear recommender that matches or beats most neural models on this kind of data), sparsified to the top neighbours per film. Each film's genres and community tags are embedded with a small sentence-embedding model. Everything is written as plain typed-array files plus JSON (docs/artifact-format.md).
• Scoring (TypeScript in the browser, or Python). Your liked films select rows of the item-item matrix; their sum is your collaborative score for every film. A mood is embedded on the fly and compared with every film by cosine. Structured filters apply, the components are rank-normalised and combined, and each result carries its reasons ("because you liked …", "close to …").
• The LLM, when you add one, parses and explains. It never ranks. The ranking is deterministic and inspectable.
• Science. Hold-out evaluation of the recommender on your own ratings with confidence intervals; agreement statistics between your scores and the population's; cross-validated fits.

The design decisions and the research behind them are in docs/architecture.md and docs/research/ (start with the synthesis).

Data and licensing

Shipped artifacts are built only from openly usable sources: MovieLens (research, non-commercial, share-alike on transformations), Wikidata (CC0) and Wikipedia (CC BY-SA) in later versions. Posters, overviews, certifications and streaming availability come live from TMDB (and JustWatch through TMDB) with your own API key, are shown for display only, are cached locally for at most six months, and are never fed to the recommender or to an LLM, because TMDB's API terms exclude ML/AI applications. This product uses the TMDB API but is not endorsed or certified by TMDB.

Your ratings stay in your browser (or in the file you point the CLI at) unless you export them.

Layout

Status

v1: Python and TypeScript cores with parity tests, CLI on both, the web app, MovieLens-only catalogue. Next: Wikidata and Wikipedia catalogue, LLM "vibe profiles", MCP server and in-app assistant, remote MCP for claude.ai connectors, int8 artifacts, a published data package.