Candidate
A searcher that finds candidate entities for a suggested entity.
A CandidateSearcher actively searches for and retrieves candidates from a data source. Searchers are designed to be chained in an EscalatingEntityResolver:
Each searcher does its own search and returns candidates
If a searcher returns a confident match, resolution stops early
Otherwise, candidates are accumulated for potential LLM arbitration
Searchers should be ordered cheapest-first:
Exact ID/name lookup (instant, no LLM)
Heuristic/fuzzy search (fast, no LLM)
Vector/embedding search (moderate, no LLM)
Agentic search (expensive, uses LLM to drive search)
See also
Inheritors
Properties
Which ResolutionLevel a confident hit from this searcher counts as, for the per-level telemetry EscalatingEntityResolver logs. Each searcher declares its own tier so the counts stay accurate whatever the chain's length or order. Defaults to ResolutionLevel.HEURISTIC_MATCH; exact-lookup searchers report ResolutionLevel.EXACT_MATCH and vector search reports ResolutionLevel.EMBEDDING_MATCH.