Return the tone/structure instructions the LLM should follow when analyzing a scene.

Search the reference index for scenes similar to query.

Returns: A list of matches, ranked most similar first. Empty if the reference index isn't available (see get_retriever().unavailable_reason).

Fetch full details for a specific reference scene.

Returns: A dict with the scene's movie, slugline, characters, and full text, or None if the id doesn't exist (or the index is unavailable).

List every movie currently in the reference index.

Returns: A list of {"movie_name": ..., "imdb_id": ...} dicts, one per indexed movie. Empty if the reference index is unavailable.

Find reference scenes that strongly achieve a target mood.

Returns: A dict with: - method: "tag_matched" if target_mood closely matched a precoded mood tag, "semantic_fallback" if it didn't and results came from raw nearest-neighbor search instead, or "unavailable" if the reference index isn't available. - matched_tag / tag_similarity: the closest precoded tag and its cosine similarity to target_mood, regardless of which method was used -- lets the caller judge match confidence even on the fallback path. - results: the ranked scene matches themselves. Empty if no scenes are available or the index is unavailable.