Grounding
omop_graph.reasoning.grounding
Semantic Grounding Orchestration.
This module provides the high-level ground_term function, which orchestrates
the full grounding pipeline:
1. Candidate Resolution: Finding raw concepts that match the input text.
2. Hierarchy Validation: Ensuring candidates have a valid relationship path
to required parent concepts.
3. Standardization: Mapping non-standard candidates to standard OMOP concepts.
4. Semantic Ranking: Using embeddings and graph-based scoring to select the
best mapping.
GroundingConstraints
dataclass
Configuration for restricting the grounding search space.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parent_ids
|
tuple[int, ...]
|
OMOP Concept IDs that act as required ancestors for any valid result. |
required |
search_constraint
|
SearchConstraintConcept
|
Domain and Vocabulary restrictions for the initial resolution phase. |
required |
max_depth
|
int
|
Maximum allowed distance in the hierarchy between a candidate and a parent. |
6
|
predicate_kinds
|
frozenset[ClassIDEnum]
|
The types of relationships allowed during pathfinding. |
frozenset({IDENTITY})
|
find_standard_concepts(kg, candidate, parent_ids, max_depth, max_paths=3, predicate_kinds=frozenset({ClassIDEnum.IDENTITY}), lowest_cost=None)
Identify standard concepts related to a candidate that satisfy parent constraints.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
kg
|
KnowledgeGraph
|
The Knowledge Graph instance. |
required |
candidate
|
CandidateHit
|
The initial match found by a resolver. |
required |
parent_ids
|
tuple[int, ...]
|
Acceptable ancestor IDs. |
required |
max_depth
|
int
|
Maximum separation allowed. |
required |
max_paths
|
int
|
Limit on unique standard concepts per parent lookup. |
3
|
predicate_kinds
|
frozenset
|
Edge types to traverse. |
frozenset({IDENTITY})
|
lowest_cost
|
float
|
Minimum cost threshold for pathfinding. |
None
|
Returns:
| Type | Description |
|---|---|
list[StandardConcept]
|
Standard concepts associated with the candidate that hit the targets. |
ground_term(resolver_pipeline, kg, text, text_embedding, text_embedding_model, constraints, max_candidates=None, metric_type=None, index_type=None)
Ground a text string to a ranked list of standard OMOP concepts.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
resolver_pipeline
|
ResolverPipeline
|
The pipeline of search strategies to find initial candidates. |
required |
kg
|
KnowledgeGraph
|
The OMOP Knowledge Graph instance. |
required |
text
|
str
|
The input text to ground. |
required |
text_embedding
|
ndarray
|
The embedding vector for the input text. |
required |
text_embedding_model
|
str
|
The name of the embedding model used to generate |
required |
constraints
|
GroundingConstraints
|
Contextual constraints (parents, domains, etc.) to apply. |
required |
max_candidates
|
int
|
Limit for the number of candidates returned. If None, returns all candidates. |
None
|
metric_type
|
EmbeddingMetricType
|
The similarity or distance metric to use for optional embedding-based scoring. |
None
|
Returns:
| Type | Description |
|---|---|
list[StandardConceptWithScore]
|
A list of standard concepts sorted by their total score (descending). |
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
If no |