WatchlistXplore

Browse, filter, and vibe-search your IMDb watchlist. Enriches each title with TMDB poster images, keywords, and overviews, then lets you run natural-language LLM queries like "slow-burn psychological thriller" against your filtered list.

Live demo: watchlistxplore.vercel.app

---

Features

• Hard filters: media type, genre (union or intersection), keywords, year range, runtime, IMDb rating, director, cast, sort order
• LLM semantic search: describe a vibe and get up to 5 ranked picks with reasoning (works on filtered lists ≤ 150 items)
• Multiple LLM providers: Gemini, OpenAI, Anthropic, OpenRouter, local Ollama, or any OpenAI-compatible endpoint
• Search history: past queries and results saved locally, reloadable
• Detail drawer: full metadata, keywords, genres, TMDB poster, IMDb link
• Dark mode (default, system-detected)
• Fully static — no database, no auth

---

Quick Start

1. Export your IMDb watchlist

1. Log into imdb.com → Watchlist
2. Click the kebab menu (⋮) → Export
3. Save the downloaded CSV

2. Get a TMDB API key

Create a free account at themoviedb.org → Settings → API → Create → Developer. Copy the Read Access Token (the long JWT starting with eyJ…).

Create enrich/.env:

TMDB_API_KEY=your_read_access_token_here

3. Enrich the data

npm install
node enrich/enrich.mjs /path/to/your/WATCHLIST.csv

This fetches TMDB metadata (~2 API calls per title) and writes public/watchlist.json. Expect ~1 min per 100 titles.

4. Run locally

npm run dev

Open http://localhost:5173. Filters, cards, and the detail drawer work fully offline. LLM search requires a Vercel deployment (see below) or a temporary local workaround (see SETUP.md).

---

Deploy to Vercel

1. Push this repo to GitHub
2. vercel.com → New Project → import repo → Deploy (auto-detects Vite)
3. In Settings → Environment Variables, add at least one LLM provider:

Provider	Variables needed
Gemini	GEMINI_API_KEY, optionally GEMINI_MODEL (default: gemini-2.0-flash)
OpenAI	OPENAI_API_KEY, optionally OPENAI_MODEL (default: gpt-4o-mini)
Anthropic	ANTHROPIC_API_KEY, optionally ANTHROPIC_MODEL (default: claude-haiku-4-5-20251001)
OpenRouter	OPENROUTER_API_KEY, optionally OPENROUTER_MODEL (default: google/gemma-3-12b-it:free)
Local / Ollama	LLM_LOCAL_URL (e.g. http://your-host:11434), optionally LLM_LOCAL_MODEL, LLM_LOCAL_API_KEY
Generic OpenAI-compat	LLM_API_KEY + LLM_ENDPOINT + LLM_MODEL

Multiple providers can be set; the server picks the first available in priority order: local → gemini → openai → anthropic → openrouter → generic.

Update your watchlist

public/watchlist.json is gitignored in this template (it contains personal data). To deploy your own watchlist to Vercel:

# Option A — commit your data to your own fork (simplest):
# Remove "public/watchlist.json" from .gitignore, then:
git add public/watchlist.json
git commit -m "update watchlist"
git push   # Vercel redeploys automatically

# Option B — force-add without editing .gitignore:
git add -f public/watchlist.json
git commit -m "update watchlist"
git push

---

AI Search

The gear icon (⚙) in the header opens AI settings. Toggle which fields the LLM sees per item — more fields give better results but increase token usage. Defaults: title, year, genres, keywords, overview (truncated to 150 chars).

AI search only activates when your filtered list is ≤ 150 items. Narrow with the sidebar filters first.

---

Tech Stack

• Frontend: React 19 + TypeScript + Vite, Tailwind CSS v4, ShadCN + Base UI components
• LLM proxy: Vercel serverless function (api/search.ts) — keeps API keys server-side
• Enrichment: Node.js ESM script (enrich/enrich.mjs) + TMDB API
• Data: static public/watchlist.json — no database

---

Development

npm run dev          # dev server
npm run build        # production build → dist/
npm run lint         # ESLint
npm run test         # run tests (vitest)

See SETUP.md for detailed setup and FAQ. See SPECS.md for architecture and codebase guide.