Search TMDB, store canonical matches, and return their local title IDs.

Append one immutable evidence event and return its event ID.

Return the audience's latest profile and relevant immutable evidence.

Candidate calls are cheap. Read every candidate against the ask and the user's evidence, then requery with different seed_titles, genre filters, or exclude_title_ids if the pool is off target. Any returned title_id can be a seed; use resolve_title for seeds named in the user's words. Use exclude_seed_title_ids to avoid user-positive seeds used in an earlier call. Larger limits pull more seeds and deeper pages; min_vote_average and min_vote_count adjust the score floors. Property arguments add a discover route to the same pool. On general calls, ALS candidates come from the user's overall movie taste vector, not from one seed. Set allow_repeats only to include titles the user has seen or rated; titles marked not_interested remain excluded. Use detail="full" only when the complete metadata and evidence records are needed. Record only final picks.

Record only final picks. Candidate calls are cheap: read every candidate against the ask and the user's evidence, and requery with different seed_titles, genre filters, or exclude_title_ids when needed. Any returned title_id can be a seed, and resolve_title turns titles from the user's words into seed IDs.

Return recent runs; shortlisted explanations are null by construction.

Record a reaction and optionally link it to a recommendation run.

Find titles by era, genre, rating, language, or keywords.

Use this when similarity search cannot express the user's request. Results can be passed to get_candidates as seed titles. Seen, rated, and not_interested titles are excluded unless allow_repeats applies; not_interested stays excluded. When sorting by vote_average.desc without min_vote_count, the default floor is 1000 votes for movies and 500 for TV. Calls are cheap and paging is normal.