Resolvers
omop_graph.reasoning.resolvers.resolvers
Resolver strategies for mapping text to OMOP Concepts.
This module defines a hierarchy of CandidateResolver classes. Each resolver implements
a specific strategy (Exact Match, Partial Match, Full-Text Search) to find OMOP concepts
that match a given input string.
They are designed to be used in a ResolverPipeline where high-confidence resolvers
(Exact) are tried before lower-confidence ones (Partial/Fuzzy).
CandidateHit
dataclass
A resolved candidate concept found by a resolver.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
concept_id
|
int
|
The OMOP Concept ID. |
required |
match_kind
|
LabelMatchKind
|
The kind of match of this hit. |
required |
matched_label
|
str
|
The specific text in the database (name or synonym) that matched. |
required |
CandidateResolver
Interface for resolving free text to OMOP concept_ids.
Attributes:
| Name | Type | Description |
|---|---|---|
match_kind |
LabelMatchKind
|
The kind of match that this resolver produces. |
get_matches(kg, text, constraints=None, sort=False, **kwargs)
Execute the search strategy against the Knowledge Graph.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
kg
|
KnowledgeGraph
|
The graph instance. |
required |
text
|
str
|
The input text to search for. |
required |
constraints
|
SearchConstraintConcept
|
Filters for domain/vocabulary. |
None
|
sort
|
bool
|
Whether to sort LabelMatch results by their internal relevance ranking. |
False
|
Returns:
| Type | Description |
|---|---|
Tuple[LabelMatch, ...]
|
A tuple of raw label matches. |
resolve(kg, text, constraints=None, **kwargs)
Public API to find and format candidates.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
kg
|
KnowledgeGraph
|
The graph instance. |
required |
text
|
str
|
The input text. |
required |
constraints
|
SearchConstraintConcept
|
Filters for concepts to consider in the search. Also limits the number of candidates returned
using the |
None
|
Returns:
| Type | Description |
|---|---|
Iterable[CandidateHit]
|
The formatted candidate hits. |
EmbeddingResolver
Bases: CandidateResolver
Strategy: Retrieve nearest concepts from stored concept embeddings. Currently only for synonym=False as seamntic similarity should be preserved in the primary name. Could be extended to synonym=True if needed.
ExactLabelResolver
ExactSynonymResolver
Bases: CandidateResolver
Strategy: Exact case-insensitive match on Concept_Synonym.concept_synonym_name.
FullTextResolver
Bases: CandidateResolver
Strategy: Postgres Full-Text Search (tsvector) on Concept.concept_name.
Matches irrespective of word order (e.g., "Kidney Cancer" -> "Cancer of Kidney").
FullTextSynonymResolver
Bases: CandidateResolver
Strategy: Postgres Full-Text Search (tsvector) on Concept_Synonym.concept_synonym_name.
PartialLabelResolver
Bases: CandidateResolver
Strategy: Substring match (ILIKE %term%) on Concept.concept_name.
Ranked by similarity heuristics (starts_with, length diff).
PartialSynonymResolver
Bases: CandidateResolver
Strategy: Substring match (ILIKE %term%) on Concept_Synonym.concept_synonym_name.
Inherits ranking logic from PartialLabelResolver.