Matchers

base

Abstract interface for matching strategies.

Matcher

Bases: ABC

Turns per-source scored candidates into final AlignmentResults.

Not required to return exactly one result per source — e.g. a future hierarchical matcher could return several (broader/narrower-related) results for one source entity. Shared across linkers that produce a dict[str, list[tuple[target_id, score]]] scored candidate map (StringSimilarityLinker, FeatureClassifierLinker).

Note this only leaves room for output cardinality to change. A real broader/narrower matcher would also need relation-type/taxonomy information that match()'s current input (plain target-id/score pairs, no Entity or graph access) doesn't carry — that's a deliberately deferred, separate signature change, not something this abstraction already supports.

match abstractmethod

match(
    candidates_by_source: dict[
        str, list[tuple[str, float]]
    ],
) -> list[AlignmentResult]

Resolve scored candidates into final links.

Parameters:

Name	Type	Description	Default
candidates_by_source	dict[str, list[tuple[str, float]]]	Source id -> list of (target_id, score).	required

Returns:

Type	Description
list[AlignmentResult]	Predicted links.

Source code in src/linkingtk/matchers/base.py

@abstractmethod
def match(
    self, candidates_by_source: dict[str, list[tuple[str, float]]]
) -> list[AlignmentResult]:
    """Resolve scored candidates into final links.

    Args:
        candidates_by_source: Source id -> list of ``(target_id, score)``.

    Returns:
        Predicted links.
    """

greedy

Independent per-source argmax matching.

GreedyMatcher

Bases: Matcher

Picks each source entity's highest-scoring candidate independently.

Multiple source entities may map to the same target — there's no global one-to-one constraint. The simplest, cheapest matcher, and the default for both StringSimilarityLinker and FeatureClassifierLinker.

optimal

Globally optimal one-to-one assignment matching.

OptimalMatcher

Bases: Matcher

Finds a single globally optimal one-to-one assignment.

Uses the Hungarian algorithm (scipy.optimize.linear_sum_assignment) over a dense cost matrix — the right tradeoff at the scale this toolkit currently targets (blocking-reduced candidate sets on toy/small datasets), not thousands-of-entities KG-scale workloads (graph- embedding-based EA, a later milestone), which would need a sparse bipartite matching instead. Can outperform GreedyMatcher when two source entities' individually-best candidate is the same target — see EntMatcherLinker, which uses this matcher by default.