English · 中文

_{Keywords: anime recommender · AI anime recommendation · taste profile · 动漫推荐 · 追番推荐 · AI 推荐动漫 · 口味画像 · Jellyfin · AniList · TMDB · Bangumi · Infuse · 夸克网盘 / Quark · self-hosted · AI agent · LLM · Claude / OpenClaw skill · anime watchlist}

anime-taste

Learn your anime taste from what you've actually watched, then auto-recommend anime you'll like — driven by an AI agent.

anime-taste reads your watch history (e.g. from Jellyfin), enriches every show with fine-grained AniList tags, and lets an AI agent build a personal taste model of you. It then scores a catalog of anime against that model and surfaces the best titles you haven't seen yet — pushed to you on a schedule, on demand, or the moment you finish a series. It's the recommendation brain; pair it with a downloader like quark-tracker to actually fetch the picks.

catalog (.docx/.csv/.json)  ──►  TMDB match  ──►  AniList fine tags  ──┐
your watch history (Jellyfin/file)  ──────────────────────────────────┤
your taste model  (an AI builds this from your history) ──────────────┤
                                                                       ▼
                                          ranked, de-duplicated, watched-excluded picks
                                          → WeChat / Telegram / Bark / webhook / stdout

🎁 Batteries included. This repo ships a ready-to-use catalog of 2,344 anime (Chinese title + Quark 网盘 share link), already matched to TMDB and tagged with AniList genres/tags/scores — so python3 src/recommend.py returns real recommendations the moment you clone, no catalog-building required. See Bundled catalog.

What it can do

• Builds a taste model of you, not a genre average. An AI agent runs taste-data, sees which AniList tags dominate the shows you finished vs dropped, asks you a few calibrating questions, and writes a taste_profile.json — clusters of tags with weights, hard dislikes, a quality gate, and a recency penalty. You sign off on it.
• Recommends only what you haven't watched. Everything in your library (and a blocklist) is excluded automatically; sequels can be skipped so you don't get "Season 3" of a show you never started.
• On-demand, by genre, in any language. "recommend me some healing anime" / "推荐几部机战番" → it maps the genre word to AniList tags and ranks by your taste.
• Find a title in your catalog by name or Japanese original name (fuzzy).
• Weekly auto-picks — a balanced mix across your taste clusters, on a cron.
• Finish-triggered picks — when you complete a series that has actually ended (checked against TMDB), it pushes similar shows.
• Numbered replies — picks are delivered numbered; reply with the numbers you want and hand those links to your downloader; say "block 3" to never see one again.
• Pluggable delivery — print to stdout, run any sender command (with a stitched poster grid image), or POST to a webhook (ServerChan / Bark / …).
• Packaged as an AI skill — skills/anime-taste/SKILL.md tells an agent (Claude Code, OpenClaw, Cursor, …) exactly how to drive the whole thing.

Bundled catalog

catalog/catalog.json is a catalog of 2,344 anime, each a Chinese title + a Quark (夸克网盘) share link; catalog/catalog_enriched.json is that same list already matched to TMDB and tagged with AniList genres/tags/scores. config.json's defaults point at it, so you can recommend immediately:

python3 src/recommend.py        # ranks all 2,344 against the example taste profile, no setup

Source & credit. The raw title→link list is parsed from a community-shared collection doc on WPS/kdocs: https://www.kdocs.cn/l/cnOBXUamMBJJ (compiled and maintained by its original author — all credit for assembling the collection is theirs; this project only parsed the table). The Quark links point to third-party网盘 shares whose availability this project does not control. If you maintain that doc and want it re-credited or removed, open an issue. To use your own collection instead, drop a .docx/.csv/.json of name + link in and re-run the pipeline (it regenerates catalog/).

How every title got tagged

Recommendations are only as good as each show's tags, so getting all 2,344 titles tagged took three escalating methods. The provenance of each entry is recorded in its al_source field:

1. TMDB match (~1,400 titles, the base pass) — each Chinese title is searched on TMDB (zh-CN) for canonical metadata, a rating, the year, a poster, and — crucially — the Japanese original name, the key the next step depends on.
2. AniList by original name (+681) — that Japanese name is looked up on AniList, which has the most fine-grained anime tags anywhere (Isekai, Iyashikei, Overpowered MC, Time Manipulation…). A first pass plus a cleaned-name re-pass (anilist_refill) covered most of the long tail. AniList search by Chinese name basically fails — which is the whole reason for the TMDB → original-name hop.
3. LLM + web research (+192) — the stubborn remainder (brand-new 2025–26 shows not yet on AniList, messy sequel/alias names, Chinese-original donghua) were classified by an AI reading MAL / AniList / Bangumi / Wikipedia / Moegirl and emitting the same al_genres / al_tags / al_score shape (al_source: llm_web_*).

Result: 100% of the 2,344 are tagged (2,333 with fine AniList-style tags), so every one is rankable by your taste. Re-running the pipeline on your own catalog reproduces steps 1–2 automatically; step 3 is where an AI agent earns its keep.

Why

Generic recommenders push the popular thing, or the average-of-a-genre thing. They don't know that you'll forgive a "torture" plot for a great romance arc but bounce off a dumb power-fantasy, that ecchi is a plus for you but gore is an instant no, or that you watch shows with weak art slower. That nuance lives in your watch history + a short conversation. anime-taste captures it as an explicit, editable weight model — and because an AI builds and tunes it, you get a recommender that argues its picks in your own terms, and that you can correct in plain language ("stop recommending tragedies").

Prerequisites

You need the three things the pipeline joins together:

1. A watch history — either a Jellyfin server the tool can reach (it pulls watched/in-progress status via the API), or a hand-written watched.json (see examples/watched.sample.json; minimum is name + played/pct per show). Infuse/Plex users can export to the simple watched.json form.
2. A catalog of anime to recommend from — optional: a 2,344-anime catalog already ships (see Bundled catalog). To use your own: a list of name + link, where link is whatever your downloader consumes (a Quark/网盘 share link, a magnet, an id…), supplied as a Word table exported from an online sheet (.docx), a .csv (name,link), or a .json. anime-taste treats the link as opaque and just carries it through.
3. A free TMDB API key — used to resolve each title to canonical metadata and its Japanese original name, which is the key to AniList's tags. (AniList itself needs no key.)

And, to get the "AI builds your taste" experience, an AI agent with shell access to run the scripts (Claude Code / OpenClaw / Cursor / …). You can run everything by hand and write taste_profile.json yourself, but the agent is the point.

Environment

• Python 3.8+ — standard library only for the core. Pillow is optional, just for the stitched poster-grid image in notifications (pip install Pillow).
• No database, no service. Everything is plain JSON files on disk; scripts are one-shot and safe to cron.
• Network: api.themoviedb.org must be reachable for the TMDB enrich step — on mainland-China home ISPs it's blocked, so run that one step on a server/NAS/VPS. graphql.anilist.co is reachable from most networks.
• OS: Linux / macOS / Windows. Tested with Python 3.12.

Install

git clone https://github.com/Fanxiaoyao66/anime-taste.git
cd anime-taste
python3 src/recommend.py                  # works immediately on the bundled 2,344-anime catalog

To make it yours: cp config.example.json config.json, fill in your TMDB key / taste source / delivery, optionally pip install Pillow (poster grid), then either let an AI agent take over (recommended — see the skill) or run the pipeline yourself:

# 1) (only if using your OWN catalog) ingest it -> catalog/  (path: paths.catalog_source)
python3 src/parse_catalog.py

# 2) enrich  (run enrich_tmdb where TMDB is reachable, e.g. your NAS)
python3 src/enrich_tmdb.py
python3 src/enrich_anilist.py

# 3) pull watch history (skip if you wrote watched.json yourself)
python3 src/jf_pull.py

# 4) build your taste model  ← the AI's job; see skills/anime-taste/SKILL.md
python3 src/anime_taste.py taste-data        # tag fingerprint of what you've watched
#   ...agent analyzes + asks a few questions + writes taste_profile.json...
cp taste_profile.example.json taste_profile.json   # (or let the agent write it)

# 5) recommend
python3 src/recommend.py --top 15            # inspect the ranking, per cluster
python3 src/anime_taste.py recommend 6       # deliver picks
python3 src/anime_taste.py recommend healing # on-demand by genre
python3 src/anime_taste.py find "Frieren"    # locate a title in your catalog

One-command AI deploy

Have an agent with shell/SSH access set it up. Paste this:

Set up "anime-taste" (https://github.com/Fanxiaoyao66/anime-taste) for me:
1. git clone it, cp config.example.json config.json.
2. Ask me for: my Jellyfin URL+login (or that I'll provide watched.json), my TMDB API
   key, where my anime catalog file is, and how I want picks delivered.
3. Run parse_catalog + enrich_tmdb (on a host that can reach TMDB) + enrich_anilist + jf_pull.
4. Run `anime_taste.py taste-data`, analyze my tags, ask me 4–5 calibration questions,
   then write taste_profile.json and show me the top picks per cluster to confirm.
5. Once I approve, set up a weekly cron and tell me how to ask for on-demand recs.

The skill at skills/anime-taste/SKILL.md contains the full agent playbook.

How the score works (short version)

Each enriched title gets a score = Σ(taste-cluster tag weights) + global prefs + negative tags + genre weights + a quality bonus (from AniList/TMDB rating) + a recency penalty. The cluster contributing the most becomes the title's bucket (used for the weekly mix and the emoji/label in messages). It's deliberately simple, explicit, and fully driven by your taste_profile.json — no opaque model, so the AI (and you) can read and tune every number.

Privacy

Your catalog, watch history, taste model, and credentials never leave your machine and are git-ignored by default (config.json, taste_profile.json, data/, any *.docx). Only TMDB/AniList lookups go out, keyed by anime titles — nothing about you.

Companion project

• quark-tracker — give it a Quark share link and it downloads + TMDB-renames the episodes into your media library. anime-taste picks what to watch; quark-tracker fetches it.

License

AGPL-3.0. If you run a modified version as a network service, you must release your changes.