Core

entity

Core data model shared by all linking tasks.

Entity dataclass

Entity(
    id: str,
    labels: list[str | LabelWithLang],
    description: str | LabelWithLang | None = None,
    context: str | ContextWithSpan | None = None,
    properties: dict[str, str] = dict(),
)

A single entity/sense/mention participating in a linking task.

Attributes:

Name	Type	Description
id	str	An identifier for the entity.
labels	list[str | LabelWithLang]	Plain strings such as "cat", or pairs with a language such as ("cat", "en").
description	str | LabelWithLang | None	The main definition of the entity, optionally tagged with a language.
context	str | ContextWithSpan | None	An occurrence of the label in text, optionally with character offsets (text, start, end) indicating the mention.
properties	dict[str, str]	Extra key/value properties describing the entity.

context_text

context_text(entity: Entity) -> str

Extract the plain text of an entity's context, ignoring any character offsets.

Returns an empty string if the entity has no context.

Source code in src/linkingtk/core/entity.py

def context_text(entity: Entity) -> str:
    """Extract the plain text of an entity's context, ignoring any character offsets.

    Returns an empty string if the entity has no context.
    """
    if entity.context is None:
        return ""
    return entity.context if isinstance(entity.context, str) else entity.context[0]

description_text

description_text(entity: Entity) -> str

Extract the plain text of an entity's description, ignoring its language tag.

Returns an empty string if the entity has no description.

Source code in src/linkingtk/core/entity.py

def description_text(entity: Entity) -> str:
    """Extract the plain text of an entity's description, ignoring its language tag.

    Returns an empty string if the entity has no description.
    """
    if entity.description is None:
        return ""
    return entity.description if isinstance(entity.description, str) else entity.description[0]

label_texts

label_texts(entity: Entity) -> list[str]

Extract the plain text of each of an entity's labels.

Language tags are dropped; duplicates are preserved so callers can weight by how often a label occurs.

Source code in src/linkingtk/core/entity.py

def label_texts(entity: Entity) -> list[str]:
    """Extract the plain text of each of an entity's labels.

    Language tags are dropped; duplicates are preserved so callers can
    weight by how often a label occurs.
    """
    return [label[0] if isinstance(label, tuple) else label for label in entity.labels]

result

Result types returned by linking algorithms.

AlignmentResult dataclass

AlignmentResult(
    source_id: str,
    target_id: str,
    score: float = 1.0,
    alternatives: list[str] = list(),
)

A single predicted link between two entities.

Attributes:

Name	Type	Description
source_id	str	Identifier of the entity in dataset1.
target_id	str	Identifier of the matched entity in dataset2.
score	float	Confidence score assigned by the linker, higher is better.
alternatives	list[str]	Additional candidate target ids ranked after target_id, used for ranked evaluation (e.g. Hits@k, MRR).

source

Query-driven target datasets for blocking/linking against huge or external entity sets.

CachingEntitySource

CachingEntitySource(source: EntitySource)

Bases: EntitySource

Wraps an EntitySource, memoizing search/get calls.

HTTP-backed or otherwise slow/rate-limited sources benefit from this since the same query (e.g. a repeated mention text) tends to recur within a session.

Source code in src/linkingtk/core/source.py

def __init__(self, source: EntitySource) -> None:
    self._source = source
    self._search_cache: dict[tuple[str, int], list[Entity]] = {}
    self._get_cache: dict[str, Entity | None] = {}

EntitySource

Bases: ABC

A query-driven stand-in for a fully materialized list[Entity] target dataset.

Lets BlockingStrategy and BaseLinker target datasets too large, or already indexed elsewhere, to enumerate into memory -- e.g. WordNet (via wn), Wikipedia, Wikidata -- by querying per-mention instead.

get abstractmethod

get(entity_id: str) -> Entity | None

Look up a single entity by id, or None if it doesn't exist.

Source code in src/linkingtk/core/source.py

@abstractmethod
def get(self, entity_id: str) -> Entity | None:
    """Look up a single entity by id, or ``None`` if it doesn't exist."""

search abstractmethod

search(query: str, top_k: int = 10) -> list[Entity]

Return up to top_k entities matching query, best match first.

Source code in src/linkingtk/core/source.py

@abstractmethod
def search(self, query: str, top_k: int = 10) -> list[Entity]:
    """Return up to ``top_k`` entities matching ``query``, best match first."""

search_batch

search_batch(
    queries: list[str], top_k: int = 10
) -> list[list[Entity]]

Return search(query, top_k) results for each of queries, in order.

Defaults to looping over search; override this for sources with a real batch API (e.g. a local ANN index, Elasticsearch _msearch).

Source code in src/linkingtk/core/source.py

def search_batch(self, queries: list[str], top_k: int = 10) -> list[list[Entity]]:
    """Return ``search(query, top_k)`` results for each of ``queries``, in order.

    Defaults to looping over [search][linkingtk.core.source.EntitySource.search];
    override this for sources with a real batch API (e.g. a local ANN
    index, Elasticsearch ``_msearch``).
    """
    return [self.search(query, top_k) for query in queries]