Source code for trader.discovery.candidates

"""A symbol a theme surfaced, and the evidence for it."""

from dataclasses import dataclass

__all__ = ["Candidate"]




@dataclass(frozen=True, slots=True)
class Candidate:
    """One discovered symbol, with the provenance that will explain it later.

    `headline` and `url` are what answer "why did it buy UUUU?" three weeks
    afterwards, which is the whole reason `watchlist_events` records them.

    `recommendation_mean` (issue #44) is the analyst-scan signal that earned
    an `origin="analyst_scan"` candidate its slot — Yahoo's 1..5 scale, the
    same field `AnalystOpinion` carries — snapshotted here so
    `trader build-focus-list` can persist it onto `focus_list` without a
    second live analyst lookup. `None` for every other origin; theme search
    never sets it.
    """

    symbol: str
    theme: str
    origin: str
    headline: str | None = None
    url: str | None = None
    recommendation_mean: float | None = None