braidio.relevance

How well a still relates to the words spoken over it — the scorer seam.

A picture track used to be placed with no recorded reason and no check, so an off-topic still could not be explained, caught or tuned (thorwhalen/braidio#85: a Dylan portrait over a sentence that no longer mentioned Dylan, a Beach Boys frame under a tag naming a different concert). video_panels.plan now scores every placement against its anchor_text through a scorer, and this module is where scorers live.

A scorer has the shape of illustration’s reranking Scorer — (query, items) -> scores — with the anchor text as the query and still bodies (plain dicts) as the items, one score in [0, 1] per still. Batch by design, so a model-backed scorer (illustration’s SigLIP rerank, its VLM judge) embeds the text once per span, not once per candidate.

The default, lexical_relevance(), needs nothing installed: the share of a still’s naming words (subject, title, key) that the anchor text actually says. It is deliberately literal — it cannot see that a studio console suits “Tom Wilson booked a rhythm section” — so a low score means *the words do not name this picture*, which is the question a disclaimer or a decorative role has to answer, not a verdict that the picture is bad.

Examples

>>> dylan = {"key": "dylan-1965", "subject": "Bob Dylan, 1965"}
>>> said = "the same day as the sessions for Bob Dylan's Like a Rolling Stone"
>>> round(lexical_relevance(said, [dylan])[0], 2)
0.67
>>> lexical_relevance("overdubbed electric guitar onto the tape", [dylan])
[0.0]
>>> resolve_scorer("lexical") is lexical_relevance
True

Module Attributes

RelevanceScorer	(anchor_text, still_bodies) -> one score in [0, 1] per still.
RELEVANCE_SCORERS	Registered scorers by id.

Functions

lexical_relevance(anchor_text, stills)	Per still: the best share of a naming field's words that anchor_text says.
register_relevance_scorer(name, scorer)	Make scorer addressable by name (e.g. an illustration rerank adapter).
resolve_scorer(spec)	A scorer from a registered name, a callable, or None (the default).
scorer_id(spec)	The id a panel records for spec: its registered name, else its qualname.

braidio.relevance.RELEVANCE_SCORERS: dict[str, Callable[[str, Sequence[Mapping]], Sequence[float]]] = {'lexical': <function lexical_relevance>}

Registered scorers by id. The id is what a panel records in scorer.

braidio.relevance.RelevanceScorer

(anchor_text, still_bodies) -> one score in [0, 1] per still.

alias of Callable[[str, Sequence[Mapping]], Sequence[float]]

braidio.relevance.lexical_relevance(anchor_text, stills)

Per still: the best share of a naming field’s words that anchor_text says.

The maximum over NAMING_FIELDS, so a long Commons title does not dilute a short, exact subject.

Return type:

list[float]

>>> beach = {"key": "central-park-decay",
...          "subject": "The Beach Boys in Central Park, 1971",
...          "title": "Beach Boys Good Vibrations from Central Park 1971"}
>>> lexical_relevance("half a million people all getting the joke", [beach])
[0.0]

braidio.relevance.register_relevance_scorer(name, scorer)

Make scorer addressable by name (e.g. an illustration rerank adapter).

Return type:

None

>>> register_relevance_scorer("lexical", lexical_relevance)  # idempotent

braidio.relevance.resolve_scorer(spec)

A scorer from a registered name, a callable, or None (the default).

Return type:

Callable[[str, Sequence[Mapping]], Sequence[float]]

braidio.relevance.scorer_id(spec)

The id a panel records for spec: its registered name, else its qualname.

Return type:

str

>>> scorer_id(None), scorer_id(lexical_relevance)
('lexical', 'lexical')