E5 S6: enriched person page (TMDB bio + birth facts + Known-for rail)

The person page now leads with a TMDB bio, lazily fetched the first time it's
opened (off the S2-linked `tmdb_person_id`) and then served from the row:

- Migration 0072: ADD-only nullable person columns on plex_people — biography,
  birthday, deathday, place_of_birth, known_for_department, also_known_as,
  known_for ([{tmdb_id, media_type, title}]), tmdb_enriched_at.
- tmdb.py: TmdbClient.fetch_person (/person/{id}+combined_credits), parse_person
  (bio + a popularity-ranked, deduped known_for), apply_person, enrich_person
  (lazy one-shot, key+id guarded, commits, 404 stamps the watermark).
- people.py person_detail: loads the full person row, lazily enriches (best-effort
  — never fails the page), serves the bio fields + resolves known_for to library
  rows by guid (in-library only, popularity order).
- FE PlexPersonView: bio/birth-facts/aka hero + a "Known for" Carousel rail above
  the existing Movies/Shows filmography; PlexPersonDetail type + i18n (en+hu).

Tests: test_plex_person_bio.py (6: parse / lazy-enrich guards / serve) + extended
PlexPersonView.dom.test.tsx + the unknown-name contract in test_plex_person.py.
Browser-E2E'd on Jim Carrey (live TMDB enrich → bio 1937 chars, born 1962-01-17
Newmarket, Known-for resolved). Gate: vitest 337, backend lane 402.
This commit is contained in:
2026-08-21 00:08:19 +02:00
parent f10915c223
commit 187b8007f8
11 changed files with 462 additions and 30 deletions
+84 -3
View File
@@ -1,5 +1,7 @@
"""Plex people: cast/crew filter-chip cards + a single person's filmography page."""
import logging
from fastapi import APIRouter, Depends
from sqlalchemy import func, or_, select
from sqlalchemy.orm import Session
@@ -14,11 +16,65 @@ from app.models import (
User,
)
from app.plex import rollup
from app.plex import tmdb as plex_tmdb
from app.plex.cards import movie_card, show_card
from app.plex.query import split_csv
from app.routes.plex._shared import _content_libs
router = APIRouter(prefix="/api/plex", tags=["plex"])
log = logging.getLogger("siftlode.plex")
def _resolve_known_for(
db: Session,
known_for: list | None,
uid: int,
movie_lib_ids: list[int],
show_lib_ids: list[int],
) -> list[dict]:
"""The person's TMDB "Known for" credits (top by popularity) that are IN our library, as cards, in
popularity order. Matched by the canonical guid `tmdb:<id>`; out-of-library credits are dropped."""
if not known_for:
return []
guids = [f"tmdb:{k['tmdb_id']}" for k in known_for if k.get("tmdb_id")]
if not guids:
return []
movies: dict[str, PlexItem] = {}
if movie_lib_ids:
for m in db.execute(
select(PlexItem).where(
PlexItem.kind == "movie",
PlexItem.library_id.in_(movie_lib_ids),
PlexItem.guid.in_(guids),
)
).scalars():
movies.setdefault(m.guid, m)
shows: dict[str, PlexShow] = {}
if show_lib_ids:
for s in db.execute(
select(PlexShow).where(
PlexShow.library_id.in_(show_lib_ids), PlexShow.guid.in_(guids)
)
).scalars():
shows.setdefault(s.guid, s)
m_states = {
s.item_id: s
for s in db.execute(
select(PlexState).where(
PlexState.user_id == uid,
PlexState.item_id.in_([m.id for m in movies.values()] or [0]),
)
).scalars()
}
show_statuses = rollup.state_map(db, uid, [s.id for s in shows.values()])
out: list[dict] = []
for k in known_for:
g = f"tmdb:{k.get('tmdb_id')}"
if g in movies:
out.append(movie_card(movies[g], m_states.get(movies[g].id)))
elif g in shows:
out.append(show_card(shows[g], show_statuses.get(shows[g].id, "new")))
return out
@router.get("/people/cards")
@@ -88,8 +144,18 @@ def person_detail(
libraries) whose cast OR directors include this name — the inverse of the cast-name → library-filter
link. The name string is the identity key (Plex cast carries no stable per-person id), so distinct
people who share a name share a page. Each section is capped at _PERSON_SECTION_MAX. An unknown name
simply returns empty sections."""
photo = db.scalar(select(PlexPerson.photo_thumb).where(PlexPerson.name == name))
simply returns empty sections.
E5 S6: the first time a page is opened, the person's TMDB bio + "Known for" credits are lazily
fetched (from the S2-linked `tmdb_person_id`) and persisted, then served from the row on every open.
"""
person = db.execute(select(PlexPerson).where(PlexPerson.name == name)).scalars().first()
# Lazy one-time bio enrich — best-effort, never fail the page if TMDB is down / the id is stale.
if person is not None and person.tmdb_person_id and person.tmdb_enriched_at is None:
try:
plex_tmdb.enrich_person(db, person)
except Exception: # noqa: BLE001 — enrichment is optional; the filmography still renders
log.warning("person bio enrich failed for %s", name, exc_info=True)
movie_lib_ids, show_lib_ids = _content_libs(db)
movies: list[dict] = []
@@ -136,4 +202,19 @@ def person_detail(
statuses = rollup.state_map(db, user.id, [s.id for s in show_rows])
shows = [show_card(sh, statuses.get(sh.id, "new")) for sh in show_rows]
return {"name": name, "photo": photo, "movies": movies, "shows": shows}
known_for = _resolve_known_for(
db, person.known_for if person else None, user.id, movie_lib_ids, show_lib_ids
)
return {
"name": name,
"photo": person.photo_thumb if person else None,
"biography": person.biography if person else None,
"birthday": person.birthday if person else None,
"deathday": person.deathday if person else None,
"place_of_birth": person.place_of_birth if person else None,
"known_for_department": person.known_for_department if person else None,
"also_known_as": (person.also_known_as if person else None) or [],
"known_for": known_for,
"movies": movies,
"shows": shows,
}