Adapters — API Reference
OmopGraphAdapter
groundworkers.adapters.omop_graph
OmopGraphAdapter
find_equivalency_path(source_id, target_id, max_depth, allow_hierarchical_traversal=False)
Find paths restricted to identity (and optionally hierarchy) edges.
When allow_hierarchical_traversal=False only IDENTITY predicates are traversed (Maps to, Concept same_as, Concept poss_eq, etc.) — the result represents a direct cross-vocabulary equivalence with no loss of specificity.
When allow_hierarchical_traversal=True HIERARCHY predicates (Is a / Subsumes) are also allowed. A path may then step up or down the ancestry chain to find a connection, meaning the target may be an ancestor of the source — equivalence at a broader level.
within_domain is always False for equivalency paths: identity relationships are designed to cross vocabulary/domain boundaries.
get_neighbors(concept_id, max_depth, predicate_kinds, max_nodes, include_edges)
Bounded multi-hop neighborhood exploration via BFS.
Follows outgoing relationship edges from the seed concept up to max_depth hops, collecting all reachable concepts and (optionally) the edges that connect them.
ground(query, limit, domain, vocabulary_id, parent_ids=None)
Ground free text to ranked standard OMOP concepts.
Returns a dict with keys
results — ranked list of grounded concepts with scoring fields grounding_explanation — summary of which tier matched and what constraints ran
set_embedding_client(client, model_name=None)
Inject an EmbeddingClient so concept_ground can encode query strings on-the-fly.
Call this after construction (e.g. once the omop_emb adapter has resolved the default model from the registry). The embedding is computed before ground_term is called and passed as the query_embedding argument — the KG itself does not need to be rebuilt.
OmopVocabAdapter
groundworkers.adapters.omop_vocab
Direct ORM-backed vocabulary query primitives for agent-composable concept grounding.
EXTRACTION NOTE
This module is a stop-gap implementation inside groundworkers while related changes settle in omop-graph (open PRs in flight). It is deliberately written with zero groundworkers-specific dependencies so it can be extracted to omop-graph (suggested path: omop_graph/graph/search.py) or a standalone omop-search package with minimal friction.
Extraction checklist
[ ] No imports from groundworkers.* (verified — none exist) [ ] OmopVocabError: replace with the target package's exception type, or retain as a thin domain exception and re-export from the package root [ ] No MCP protocol concerns (error codes, tool names, server wiring) in here [ ] Move file; add to target package init.py exports [ ] Remove this docstring block
Context: omop_graph.reasoning.concept_handlers.concept_helpers.standardise_ids raises NotImplementedError — the navigate_to_standard method here fills that gap.
ConceptMatch
dataclass
A single candidate returned by search_exact or search_fulltext.
MappedConcept
dataclass
A standard concept that a source concept maps to.
OmopVocabAdapter
Vocabulary query primitives backed directly by omop-alchemy ORM queries.
These are the low-level operations that an agent (or a grounding pipeline) can compose to find and navigate OMOP standard concepts. They deliberately expose raw quality signals (ts_rank, standard_concept flag) rather than making quality decisions internally — that is the caller's responsibility.
Three operations
search_exact — case-insensitive exact name / synonym match search_fulltext — PostgreSQL FTS with ts_rank exposed; graceful degradation when tsvector sidecar absent navigate_to_standard — batch concept_id → standard equivalents via "Maps to" relationship edges
Raises OmopVocabError for database / query errors. Raises ValueError for invalid arguments. Never raises GroundworkersError.
fts_available
property
True when the concept_name_tsvector sidecar column is present.
navigate_to_standard(concept_ids)
Given a list of concept_ids, return their standard equivalents via IDENTITY-type ("Maps to") relationship edges.
For concept_ids that are already standard: standard_concepts = [self]. For concept_ids with no outbound "Maps to" relationship: standard_concepts = []. concept_ids not found in the vocabulary are silently omitted.
All navigation is done in two queries (one for source metadata, one batch join for mappings) regardless of the number of input ids.
This fills the gap left by omop_graph.reasoning.concept_handlers. concept_helpers.standardise_ids, which currently raises NotImplementedError.
navigate_to_value(concept_ids)
Return Maps to value related concepts for the given concept_ids.
search_exact(query, *, domain=None, vocabulary_id=None, standard_only=False, include_synonyms=True, limit=20)
Case-insensitive exact match against concept_name, and optionally concept_synonym_name.
standard_only defaults to False so the caller can inspect non-standard candidates and decide whether to navigate to their standard equivalents.
Returns name matches before synonym matches; de-duplicates by concept_id so a concept that matches both name and a synonym only appears once.
search_fulltext(query, *, domain=None, vocabulary_id=None, standard_only=False, include_synonyms=True, min_rank=0.0, limit=20)
PostgreSQL FTS match using the tsvector sidecar column (GIN-indexed).
Returns (results, fts_available). When fts_available=False the tsvector sidecar column was not detected and results is always []; the caller should fall through to another search strategy.
ts_rank is included in each result so the caller can apply its own quality threshold. Synonym FTS is included when the synonym sidecar column is also present; otherwise synonym results are silently omitted (not an error).
standard_only defaults to False — see search_exact docstring.
search_normalized(query, *, domain=None, vocabulary_id=None, standard_only=False, include_synonyms=False, normalization_profile='verbatim', remove_stop_phrases=True, limit=20)
Deterministic near-verbatim search after text normalization.
This is intentionally distinct from full-text search: both the query and the candidate text are normalized, then compared for equality.
OmopVocabError
Bases: Exception
Raised by OmopVocabAdapter for query or backend errors.
Callers (e.g. MCP tool registrations) are responsible for wrapping this into their own error representation. This class intentionally has no knowledge of GroundworkersError or any MCP protocol type.
RelatedConceptMapping
dataclass
Relationship-driven mapping result for a single source concept_id.
StandardMapping
dataclass
Navigation result for a single source concept_id.
normalize_text_for_matching(text, *, profile='verbatim', remove_stop_phrases=True)
Normalize free text into a deterministic matching form.
serialise_concept_match(match)
Serialise a ConceptMatch to a JSON-safe dict for MCP tool responses.
serialise_related_concept_mapping(mapping)
Serialise a RelatedConceptMapping to a JSON-safe dict for MCP tool responses.
serialise_standard_mapping(mapping)
Serialise a StandardMapping to a JSON-safe dict for MCP tool responses.