Methodology

TVKG is a semantic and graph-based search system over ~56,000 TV series sourced from TMDB. It combines vector similarity search with structural graph traversal to surface both thematically and relationally similar content.

Four search modes are available: semantic — nearest neighbours in embedding space; structural — full-text match on series titles; hybrid, which blends the semantic score with graph-structural signals like shared cast and production country; and person — full-text match on people, with their series.

Series metadata (title, years, genres, keywords, networks, countries, languages, cast, creators, directors, ratings, a short overview) comes from TMDB, one API call per show. About 230,000 shows are fetched; the graph holds the ~56,000 that have at least two user votes, while the vector index covers every show that has an overview or keywords.

The snapshot is refreshed periodically. Shows with sparse TMDB coverage may be missing keywords, cast, or dates.

Node types in the graph: Series, Person, Genre, Keyword, Network, Country, Language. Edge types: ACTED_IN, CREATED, DIRECTED, HAS_GENRE, HAS_KEYWORD, AIRED_ON, PRODUCED_IN, HAS_LANGUAGE.

Each series is represented as a 384-dimensional dense vector produced by BAAI/bge-small-en-v1.5, a lightweight bi-encoder optimised for retrieval tasks. The input to the encoder is the series title, its TMDB overview (a short one-paragraph logline), and its keyword tags. Shows with neither an overview nor keywords are not indexed.

Vectors are stored in Qdrant with scalar quantisation (INT8) and HNSW indexing (m=16, ef_construct=100). At query time the search string is embedded with the same model (using the BGE retrieval-query instruction; documents are encoded without it) and the top-k nearest neighbours are retrieved by cosine distance. Only series that are also present in the graph are returned.

The knowledge graph is stored in a property graph database. Each series node links to its cast, creators, directors, genres, keywords, networks, countries of production, and spoken languages.

The graph API exposes depth-1 and depth-2 neighbourhood traversals. Depth-2 reveals co-workers: directors who share actors, series that share creators, etc. The force-directed layout used in the 2D graph fixes the focal node at the centre; node size scales with degree.

The explore view uses Cytoscape.js with force (cola), hierarchy (dagre), circle, and concentric layouts and supports progressive graph expansion by double-clicking any series or person node.

Hybrid mode combines the cosine similarity score from vector search with a structural score computed from shared cast and shared production countries. The structural component rewards series that share a significant fraction of actors or originate from the same country or language context.

The number on a result depends on the mode. Semantic: cosine similarity, shown as a percentage. Hybrid: cosine similarity plus the bonuses, shown as a plain number that can be above 1.0 (the bonuses are added on top of the similarity); on the similar page the shared actor and country counts are shown next to it when the API returns them. Structural: full-text relevance from the database, also a plain number. Series added from the graph because few vector neighbours exist are marked as graph overlap. This keeps the ranking interpretable rather than a black-box recommendation.

Coverage: TMDB coverage is uneven. Only about half of all shows have cast listed and under a third have keywords; well-known series have rich metadata while obscure ones may have only a title and dates. Embedding quality degrades for series with a thin overview and no keywords.

Cast completeness: At most 20 cast members (ranked by episode count) and 10 directors are kept per show. Large ensemble casts are undercounted, so hybrid similarity based on shared actors underestimates overlap for such series.

Language: The encoder is an English model, but an overview falls back from Russian to English to the original language of the show, so some overviews are not in English and match less reliably. Genre names and keywords are in English.

Temporal freshness: The index is a snapshot and does not update in real time. Newly aired series will appear only after the next data refresh.

Attribution: This site uses TMDB and the TMDB APIs but is not endorsed, certified, or otherwise approved by TMDB.

Frontend: Next.js 15 (App Router) · TypeScript · Tailwind CSS · react-force-graph-2d · Cytoscape.js

Vector store: Qdrant 1.9 with scalar quantisation and HNSW indexing

Embedding service: FastAPI + BAAI/bge-small-en-v1.5 via sentence-transformers, running on the same host

Infrastructure: Self-hosted VDS behind Caddy reverse proxy, Docker Compose, no third-party managed services