Ask questions about movies and TV shows in plain English. Get recommendations, details, ratings, release dates, directors, and trending/popular lists — powered by the TMDB API.
Built with Python + uv.
uv sync
# TMDB API key (required): https://www.themoviedb.org/settings/api
export TMDB_API_KEY=your_key_here
# Optional: LLM-based question parsing (falls back to keyword parser if unset).
# Uses OpenRouter free models (no cost, no Anthropic):
export OPENROUTER_API_KEY=sk-or-v1-...
# default model is nvidia/nemotron-3-super-120b-a12b:free; override with:
export OPENROUTER_MODEL=some/other-model
# Optional: add an IMDb rating + votes column (OMDb API, free at omdbapi.com):
export OMDB_API_KEY=your_key_here
# Optional: "most expected" ranking via YouTube trailer views
# (YouTube Data API v3, free key at console.cloud.google.com):
export YOUTUBE_API_KEY=AIza...Questions are parsed by an LLM when OPENROUTER_API_KEY is set (free-tier
OpenRouter by default). If no key is present — or the LLM call fails — the
built-in keyword parser takes over, so the tool always works.
"Most expected" (what are the most expected movies in 2026) ranks upcoming
titles by a composite: 60% YouTube trailer views + 40% TMDB popularity
(percentile-ranked, missing signals skipped).
Interactive REPL:
uv run tmdb-assistantSingle question (no REPL):
uv run tmdb-assistant "recommend me a thriller movie"Dev: the REPL self-reloads changed source between prompts (Reloaded N file(s)),
so edit code in one terminal and it applies on your next question — no restart.
For one-shot mode, wrap with watchfiles if you want auto-rerun.
recommend me a thriller movie
recommend me something like Inception
recommend me a tv show
what is Inception about
who directed The Godfather
rating of The Dark Knight
when was Breaking Bad released
search for Blade Runner
what is trending
popular sci-fi movies
help
quit
| Intent | Examples |
|---|---|
| Recommend by genre | recommend me a comedy show, recommend a sci-fi movie |
| Recommend similar | recommend me something like Interstellar, movies similar to Alien |
| Recommendation fallback | recommend me something, recommend a movie |
| Details / synopsis | what is The Matrix about, tell me about Dune |
| Rating | rating of The Dark Knight, how is Oppenheimer rated |
| Release date | when was Breaking Bad released |
| Director / creator | who directed Pulp Fiction |
| Search | search for Blade Runner |
| Trending / popular | what is trending, popular sci-fi movies |
src/tmdb_assistant/
├── client.py # thin TMDB v3 API wrapper (httpx)
├── intents.py # keyword-based intent + genre/media parsing (fallback)
├── llm.py # LLM-based intent parsing (OpenRouter free)
├── omdb.py # IMDb rating/votes enrichment via OMDb API
└── cli.py # REPL + result rendering (rich)