groundworkers 0.1.0__tar.gz → 0.2.0__tar.gz

groundworkers-0.2.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: groundworkers
+Version: 0.2.0
+Summary: Groundworkers MCP server — read-only agentive access to OMOP vocabularies, concept graphs, and embeddings.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: mcp[cli]<2,>=1
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: SQLAlchemy<3,>=2
+Requires-Dist: psycopg[binary]<4,>=3.1
+Requires-Dist: omop-graph>=1.1.0
+Requires-Dist: omop-emb>=1.0.0
+Provides-Extra: embedding-pgvector
+Requires-Dist: omop-emb[pgvector]>=1.0.0; extra == "embedding-pgvector"
+Provides-Extra: embedding-faiss
+Requires-Dist: omop-emb[faiss-cpu]>=1.0.0; extra == "embedding-faiss"
+Provides-Extra: dev
+Requires-Dist: ipython>=8.0; extra == "dev"
+Requires-Dist: tornado>=6.5.5; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mkdocs-material>=9.7.1; extra == "dev"
+Requires-Dist: mkdocstrings-python>=2.0.1; extra == "dev"
+Requires-Dist: mkdocs>=1.6.1; extra == "dev"
+Requires-Dist: requests>=2.33.0; extra == "dev"
+Requires-Dist: mkdocs-mermaid2-plugin; extra == "dev"
+
+# groundworkers
+
+`groundworkers` is a read-only OMOP vocabulary integration package. You can use it
+in two ways:
+
+- as an **MCP server** for tool consumers such as `groundcrew`, Claude Code, and
+  other MCP clients
+- as a **Python library** for applications that want to call mapping and retrieval
+  logic directly
+
+No patient-level writes. No session state. No transport-specific business logic.
+
+## When to use it
+
+Use `groundworkers` when you want:
+
+- OMOP concept lookup and hierarchy navigation
+- exact, full-text, and embedding-based concept retrieval
+- mapping-oriented evidence bundles and context assembly
+- one package that works both over MCP and in-process from Python
+
+## How it is organized
+
+```mermaid
+flowchart LR
+    Client1[Python app] --> App[build_application]
+    Client2[MCP client] --> Server[groundworkers server]
+    App --> Services[services/]
+    Server --> Tools[tools/]
+    Tools --> Services
+    Services --> Adapters[adapters/]
+    Adapters --> OG[omop-graph]
+    Adapters --> OE[omop-emb]
+    Adapters --> DB[(OMOP DB)]
+```
+
+- `adapters/` handle dependency-specific details
+- `services/` handle reusable workflow logic
+- `tools/` expose MCP-facing wrappers
+- `app.py` and `server.py` wire those pieces together
+
+## What it exposes
+
+| Group | Surface | Notes |
+|---|---|---|
+| Concept | `concept_get`, `concept_by_code`, `concept_ancestors`, `concept_descendants`, `concept_relationships`, `concept_equivalency_path`, `concept_path`, `concept_map_to_standard`, `concept_neighbors` | Backed by `OmopGraphAdapter` |
+| Resolver | `concept_ground` | Best-answer grounding pipeline |
+| Search | `concept_search_exact`, `concept_search_fulltext`, `concept_navigate_to_standard` | Low-level lexical primitives |
+| Mapping | `concept_search_normalized`, `concept_candidate_bundle`, `concept_parent_backoff`, `concept_mapping_context`, `concept_map_to_value`, `concept_resolve_mapping_expression`, `mapping_evaluate_candidates` | High-level mapping workflows |
+| Embedding | `embedding_index_status`, `embedding_neighbours`, `embedding_search`, `embedding_encode` | Backed by `OmopEmbAdapter` |
+| System | `system_status`, `system_vocabulary_catalogue` | Always registered |
+
+## Quick start
+
+### MCP server
+
+```bash
+uv venv
+uv sync --extra dev --extra embedding-tools
+uv run groundworkers --config config/groundworkers.example.yaml --describe
+uv run groundworkers --config config/groundworkers.example.yaml
+```
+
+### Direct Python use
+
+```python
+from groundworkers.app import build_application
+from groundworkers.config import AppConfig
+
+config = AppConfig.model_validate(
+    {
+        "omop_graph": {
+            "db_url": "postgresql+psycopg://user:pass@localhost:5432/omop",
+            "vocab_schema": "omop_vocab",
+        },
+        "omop_emb": {
+            "enabled": True,
+            "backend_type": "pgvector",
+            "db_url": "postgresql+psycopg://user:pass@localhost:5432/omop",
+            "default_model_name": "qwen3-embedding:0.6b",
+            "api_base": "http://localhost:11434/v1",
+            "api_key": "ollama",
+        },
+    }
+)
+
+app = build_application(config)
+mapping = app.services.mapping
+assert mapping is not None
+
+bundle = mapping.concept_candidate_bundle(
+    "type 2 diabetes",
+    domain="Condition",
+    include_normalized=True,
+    include_fulltext=True,
+    include_embedding=True,
+)
+```
+
+## Example config
+
+```yaml
+omop_graph:
+  db_url: "postgresql+psycopg://user:pass@localhost:5432/omop"
+  vocab_schema: omop_vocab
+
+omop_emb:
+  enabled: true
+  backend_type: pgvector
+  db_url: "postgresql+psycopg://user:pass@localhost:5432/omop"
+  default_model_name: qwen3-embedding:0.6b
+  api_base: "http://localhost:11434/v1"
+  api_key: "ollama"
+```
+
+## End-to-end examples
+
+### MCP consumer flow
+
+```mermaid
+sequenceDiagram
+    participant C as MCP consumer
+    participant GW as groundworkers
+    participant M as MappingService
+    participant D as OMOP dependencies
+
+    C->>GW: call tool concept_candidate_bundle
+    GW->>M: invoke tool wrapper
+    M->>D: gather lexical, graph, and embedding evidence
+    D-->>M: candidate evidence
+    M-->>GW: assembled bundle
+    GW-->>C: MCP-safe JSON result
+```
+
+Representative tool payload:
+
+```json
+{
+  "tool": "concept_candidate_bundle",
+  "arguments": {
+    "query": "type 2 diabetes",
+    "domain": "Condition",
+    "include_normalized": true,
+    "include_fulltext": true,
+    "include_embedding": true,
+    "include_standard_mappings": true
+  }
+}
+```
+
+### Direct Python flow
+
+```mermaid
+sequenceDiagram
+    participant App as Python application
+    participant S as MappingService
+    participant A as Adapters
+    participant D as OMOP dependencies
+
+    App->>S: concept_mapping_context(...)
+    S->>A: coordinate graph / vocab / emb calls
+    A->>D: execute dependency queries
+    D-->>A: raw results
+    A-->>S: adapter-shaped results
+    S-->>App: domain result
+```
+
+## If you are using it as a library
+
+Start with `build_application(config)` and `app.services.mapping` for higher-level
+mapping workflows. Drop down to `app.adapters.*` when you want lower-level,
+dependency-shaped operations.
+
+## Companion repos
+
+- [groundcrew](https://github.com/AustralianCancerDataNetwork/groundcrew) for MCP-based orchestration
+- [omop-graph](https://australiancancerdatanetwork.github.io/omop-graph/) for OMOP concept and hierarchy queries
+- [omop-emb](https://australiancancerdatanetwork.github.io/omop-emb/) for embedding index and semantic retrieval

groundworkers-0.2.0/README.md

@@ -0,0 +1,178 @@
+# groundworkers
+
+`groundworkers` is a read-only OMOP vocabulary integration package. You can use it
+in two ways:
+
+- as an **MCP server** for tool consumers such as `groundcrew`, Claude Code, and
+  other MCP clients
+- as a **Python library** for applications that want to call mapping and retrieval
+  logic directly
+
+No patient-level writes. No session state. No transport-specific business logic.
+
+## When to use it
+
+Use `groundworkers` when you want:
+
+- OMOP concept lookup and hierarchy navigation
+- exact, full-text, and embedding-based concept retrieval
+- mapping-oriented evidence bundles and context assembly
+- one package that works both over MCP and in-process from Python
+
+## How it is organized
+
+```mermaid
+flowchart LR
+    Client1[Python app] --> App[build_application]
+    Client2[MCP client] --> Server[groundworkers server]
+    App --> Services[services/]
+    Server --> Tools[tools/]
+    Tools --> Services
+    Services --> Adapters[adapters/]
+    Adapters --> OG[omop-graph]
+    Adapters --> OE[omop-emb]
+    Adapters --> DB[(OMOP DB)]
+```
+
+- `adapters/` handle dependency-specific details
+- `services/` handle reusable workflow logic
+- `tools/` expose MCP-facing wrappers
+- `app.py` and `server.py` wire those pieces together
+
+## What it exposes
+
+| Group | Surface | Notes |
+|---|---|---|
+| Concept | `concept_get`, `concept_by_code`, `concept_ancestors`, `concept_descendants`, `concept_relationships`, `concept_equivalency_path`, `concept_path`, `concept_map_to_standard`, `concept_neighbors` | Backed by `OmopGraphAdapter` |
+| Resolver | `concept_ground` | Best-answer grounding pipeline |
+| Search | `concept_search_exact`, `concept_search_fulltext`, `concept_navigate_to_standard` | Low-level lexical primitives |
+| Mapping | `concept_search_normalized`, `concept_candidate_bundle`, `concept_parent_backoff`, `concept_mapping_context`, `concept_map_to_value`, `concept_resolve_mapping_expression`, `mapping_evaluate_candidates` | High-level mapping workflows |
+| Embedding | `embedding_index_status`, `embedding_neighbours`, `embedding_search`, `embedding_encode` | Backed by `OmopEmbAdapter` |
+| System | `system_status`, `system_vocabulary_catalogue` | Always registered |
+
+## Quick start
+
+### MCP server
+
+```bash
+uv venv
+uv sync --extra dev --extra embedding-tools
+uv run groundworkers --config config/groundworkers.example.yaml --describe
+uv run groundworkers --config config/groundworkers.example.yaml
+```
+
+### Direct Python use
+
+```python
+from groundworkers.app import build_application
+from groundworkers.config import AppConfig
+
+config = AppConfig.model_validate(
+    {
+        "omop_graph": {
+            "db_url": "postgresql+psycopg://user:pass@localhost:5432/omop",
+            "vocab_schema": "omop_vocab",
+        },
+        "omop_emb": {
+            "enabled": True,
+            "backend_type": "pgvector",
+            "db_url": "postgresql+psycopg://user:pass@localhost:5432/omop",
+            "default_model_name": "qwen3-embedding:0.6b",
+            "api_base": "http://localhost:11434/v1",
+            "api_key": "ollama",
+        },
+    }
+)
+
+app = build_application(config)
+mapping = app.services.mapping
+assert mapping is not None
+
+bundle = mapping.concept_candidate_bundle(
+    "type 2 diabetes",
+    domain="Condition",
+    include_normalized=True,
+    include_fulltext=True,
+    include_embedding=True,
+)
+```
+
+## Example config
+
+```yaml
+omop_graph:
+  db_url: "postgresql+psycopg://user:pass@localhost:5432/omop"
+  vocab_schema: omop_vocab
+
+omop_emb:
+  enabled: true
+  backend_type: pgvector
+  db_url: "postgresql+psycopg://user:pass@localhost:5432/omop"
+  default_model_name: qwen3-embedding:0.6b
+  api_base: "http://localhost:11434/v1"
+  api_key: "ollama"
+```
+
+## End-to-end examples
+
+### MCP consumer flow
+
+```mermaid
+sequenceDiagram
+    participant C as MCP consumer
+    participant GW as groundworkers
+    participant M as MappingService
+    participant D as OMOP dependencies
+
+    C->>GW: call tool concept_candidate_bundle
+    GW->>M: invoke tool wrapper
+    M->>D: gather lexical, graph, and embedding evidence
+    D-->>M: candidate evidence
+    M-->>GW: assembled bundle
+    GW-->>C: MCP-safe JSON result
+```
+
+Representative tool payload:
+
+```json
+{
+  "tool": "concept_candidate_bundle",
+  "arguments": {
+    "query": "type 2 diabetes",
+    "domain": "Condition",
+    "include_normalized": true,
+    "include_fulltext": true,
+    "include_embedding": true,
+    "include_standard_mappings": true
+  }
+}
+```
+
+### Direct Python flow
+
+```mermaid
+sequenceDiagram
+    participant App as Python application
+    participant S as MappingService
+    participant A as Adapters
+    participant D as OMOP dependencies
+
+    App->>S: concept_mapping_context(...)
+    S->>A: coordinate graph / vocab / emb calls
+    A->>D: execute dependency queries
+    D-->>A: raw results
+    A-->>S: adapter-shaped results
+    S-->>App: domain result
+```
+
+## If you are using it as a library
+
+Start with `build_application(config)` and `app.services.mapping` for higher-level
+mapping workflows. Drop down to `app.adapters.*` when you want lower-level,
+dependency-shaped operations.
+
+## Companion repos
+
+- [groundcrew](https://github.com/AustralianCancerDataNetwork/groundcrew) for MCP-based orchestration
+- [omop-graph](https://australiancancerdatanetwork.github.io/omop-graph/) for OMOP concept and hierarchy queries
+- [omop-emb](https://australiancancerdatanetwork.github.io/omop-emb/) for embedding index and semantic retrieval

{groundworkers-0.1.0 → groundworkers-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "groundworkers"
-version = "0.1.0"
+version = "0.2.0"
 description = "Groundworkers MCP server — read-only agentive access to OMOP vocabularies, concept graphs, and embeddings."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -22,7 +22,17 @@ embedding-faiss = [
   "omop-emb[faiss-cpu]>=1.0.0",
 ]
 dev = [
-  "pytest>=8,<9",
+  "ipython>=8.0",
+  "tornado>=6.5.5",
+  "pytest>=9.0.3",
+  "pytest-cov>=4.0",
+  "mypy>=1.8",
+  "ruff>=0.4",
+  "mkdocs-material>=9.7.1",
+  "mkdocstrings-python>=2.0.1",
+  "mkdocs>=1.6.1",
+  "requests>=2.33.0",
+  "mkdocs-mermaid2-plugin"
 ]
 
 [project.scripts]

{groundworkers-0.1.0 → groundworkers-0.2.0}/src/groundworkers/adapters/omop_emb.py

@@ -4,7 +4,15 @@ from collections.abc import Callable
 from typing import Any
 
 import numpy as np
-from omop_emb import EmbeddingConceptFilter, EmbeddingReaderInterface
+from sqlalchemy.engine import Engine
+
+from omop_emb import (
+    EmbeddingBackend,
+    EmbeddingClient,
+    EmbeddingConceptFilter,
+    EmbeddingModelRecord,
+    EmbeddingReaderInterface,
+)
 from omop_emb.config import MetricType
 from omop_emb.embeddings.embedding_client import EmbeddingRole
 from omop_emb.interface import list_registered_models
@@ -16,11 +24,11 @@ class OmopEmbAdapter:
     def __init__(
         self,
         *,
-        backend_factory: Callable[[], object],
+        backend_factory: Callable[[], EmbeddingBackend],
         backend_type: str | None,
         default_model_name: str | None = None,
-        client_factory: Callable[[str], object] | None = None,
-        cdm_engine: object | None = None,
+        client_factory: Callable[[str], EmbeddingClient] | None = None,
+        cdm_engine: Engine | None = None,
         faiss_cache_dir: str | None = None,
     ) -> None:
         self._backend_factory = backend_factory
@@ -29,8 +37,8 @@ class OmopEmbAdapter:
         self._client_factory = client_factory
         self._cdm_engine = cdm_engine
         self._faiss_cache_dir = faiss_cache_dir
-        self._backend: object | None = None
-        self._clients: dict[str, object] = {}
+        self._backend: EmbeddingBackend | None = None
+        self._clients: dict[str, EmbeddingClient] = {}
 
     def is_available(self) -> bool:
         return self.index_status()["available"]
@@ -164,7 +172,7 @@ class OmopEmbAdapter:
             "vector": row.tolist(),
         }
 
-    def _get_backend(self) -> object:
+    def _get_backend(self) -> EmbeddingBackend:
         if self._backend is None:
             try:
                 self._backend = self._backend_factory()
@@ -172,7 +180,7 @@ class OmopEmbAdapter:
                 raise GroundworkersError("BACKEND_UNAVAIL", f"Embedding backend is unavailable: {exc}") from exc
         return self._backend
 
-    def _resolve_model_record(self, model_name: str | None) -> object:
+    def _resolve_model_record(self, model_name: str | None) -> EmbeddingModelRecord:
         backend = self._get_backend()
         requested_name = model_name or self._default_model_name
         records = list_registered_models(backend=backend, model_name=requested_name)
@@ -190,7 +198,7 @@ class OmopEmbAdapter:
             "No default embedding model is configured and multiple registered models are available",
         )
 
-    def _build_reader(self, record: object) -> EmbeddingReaderInterface:
+    def _build_reader(self, record: EmbeddingModelRecord) -> EmbeddingReaderInterface:
         return EmbeddingReaderInterface(
             model=record.model_name,
             backend=self._get_backend(),
@@ -200,7 +208,7 @@ class OmopEmbAdapter:
             faiss_cache_dir=self._faiss_cache_dir,
         )
 
-    def _get_client(self, model_name: str) -> object:
+    def _get_client(self, model_name: str) -> EmbeddingClient:
         if self._client_factory is None:
             raise GroundworkersError("BACKEND_UNAVAIL", "embedding client is not configured")
         client = self._clients.get(model_name)
@@ -231,7 +239,7 @@ class OmopEmbAdapter:
             limit=limit,
         )
 
-    def _backend_type_from_backend(self, backend: object) -> str | None:
+    def _backend_type_from_backend(self, backend: EmbeddingBackend) -> str | None:
         backend_type = getattr(backend, "backend_type", None)
         return self._enum_value(backend_type)
 

{groundworkers-0.1.0 → groundworkers-0.2.0}/src/groundworkers/adapters/omop_graph.py

@@ -7,7 +7,7 @@ from typing import Any
 
 from omop_graph.extensions.omop_alchemy import PredicateKind
 from omop_graph.graph.constraints import SearchConstraintConcept
-from omop_graph.graph.kg import KnowledgeGraph
+from omop_graph.graph.kg import KnowledgeGraph, KnowledgeGraphEmbeddingConfiguration
 from omop_graph.graph.paths import find_shortest_paths_batch
 from omop_graph.graph.traverse import traverse
 from omop_graph.reasoning.grounding import GroundingConstraints, ground_term
@@ -32,6 +32,8 @@ from sqlalchemy import func, select, text
 from sqlalchemy.engine import Engine
 from sqlalchemy.exc import NoResultFound
 
+from omop_emb import EmbeddingClient
+
 from groundworkers.base.errors import GroundworkersError
 
 # TODO: some of this adapter logic really should be pushed back into 
@@ -45,12 +47,28 @@ class OmopGraphAdapter:
         *,
         vocab_schema: str = "omop_vocab",
         emb_model_name: str | None = None,
+        embedding_client: EmbeddingClient | None = None,
+        min_fulltext_overlap: float = 0.0,
     ) -> None:
         self.engine = engine
         self.vocab_schema = vocab_schema
         self.emb_model_name = emb_model_name
+        self._embedding_client: EmbeddingClient | None = embedding_client
+        self.min_fulltext_overlap = min_fulltext_overlap
         self._kg: KnowledgeGraph | None = None
 
+    def set_embedding_client(self, client: EmbeddingClient, model_name: str | None = None) -> 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.
+        """
+        self._embedding_client = client
+        if model_name is not None:
+            self.emb_model_name = model_name
+
     def is_available(self) -> bool:
         try:
             self._get_kg()
@@ -157,22 +175,38 @@ class OmopGraphAdapter:
             (ExactLabelResolver(), ExactSynonymResolver()),
             (FullTextResolver(), FullTextSynonymResolver()),
         ]
-        if self.emb_model_name:
+        if self.emb_model_name or self._embedding_client is not None:
             tiers.append((EmbeddingResolver(),))
         tiers.append((PartialLabelResolver(), PartialSynonymResolver()))
 
         results: list[Any] = []
         for tier in tiers:
+            is_fts_tier = any(
+                isinstance(r, (FullTextResolver, FullTextSynonymResolver)) for r in tier
+            )
             pipeline = ResolverPipeline(resolvers=tier)
             try:
-                results = ground_term(
+                raw = ground_term(
                     pipeline, kg, query,
-                    query_embedding=None,
+                    query_embedding=None,  # KG computes this via its emb_config
                     constraints=constraints,
                     max_candidates=limit,
                 )
             except Exception as exc:
                 raise self._wrap_graph_error(exc, default_code="QUERY_ERROR")
+            # Apply minimum token-overlap filter to FTS results: if fewer than
+            # min_fulltext_overlap of the query tokens appear in the matched
+            # concept name, drop the hit and fall through to a better tier.
+            if raw and is_fts_tier and self.min_fulltext_overlap > 0.0:
+                query_tokens = set(query.lower().split())
+                filtered = [
+                    r for r in raw
+                    if self._fts_overlap(query_tokens, r.matched_concept_label or "")
+                    >= self.min_fulltext_overlap
+                ]
+                results = filtered
+            else:
+                results = list(raw)
             if results:
                 break
 
@@ -535,6 +569,20 @@ class OmopGraphAdapter:
             "valid": edge.invalid_reason is None,  # type: ignore[attr-defined]
         }
 
+    @staticmethod
+    def _fts_overlap(query_tokens: set[str], concept_label: str) -> float:
+        """Return the proportion of query tokens that appear in *concept_label*.
+
+        Both sides are lowercased and split on whitespace.  A value of 1.0
+        means every query token was found; 0.0 means none were found.
+        Used to filter noisy fulltext results before falling through to the
+        embedding tier.
+        """
+        if not query_tokens:
+            return 1.0
+        label_tokens = set(concept_label.lower().split())
+        return len(query_tokens & label_tokens) / len(query_tokens)
+
     @staticmethod
     def _label_match_kind_name(match_kind: object) -> str:
         _MAP = {0: "EXACT", 1: "FULLTEXT", 2: "PARTIAL", 3: "EMBEDDING_NEAREST"}
@@ -588,7 +636,18 @@ class OmopGraphAdapter:
             raise GroundworkersError("DB_UNAVAILABLE", f"Cannot connect to database: {exc}") from exc
 
         try:
-            self._kg = KnowledgeGraph(cdm_engine=self.engine)
+            emb_config: KnowledgeGraphEmbeddingConfiguration | None = None
+            if self._embedding_client is not None:
+                try:
+                    from omop_emb.config import MetricType
+                    emb_config = KnowledgeGraphEmbeddingConfiguration(
+                        metric_type=MetricType.COSINE,
+                        model_name=self.emb_model_name,
+                        client=self._embedding_client,
+                    )
+                except Exception:
+                    emb_config = None  # Non-fatal: grounding falls back to non-embedding tiers
+            self._kg = KnowledgeGraph(cdm_engine=self.engine, emb_config=emb_config)
         except Exception as exc:
             raise self._wrap_graph_error(exc, default_code="BACKEND_UNAVAIL")
         return self._kg
@@ -597,11 +656,11 @@ class OmopGraphAdapter:
     # These are consistent across all Athena vocabulary releases (concept_ids may differ
     # between instances, but concept_codes are stable).
     _DOMAIN_ROOT_CODES: dict[str, tuple[str, str]] = {
-        "condition":   ("SNOMED", "404684003"),  # Clinical finding
-        "procedure":   ("SNOMED", "71388002"),   # Procedure
-        "drug":        ("SNOMED", "373873005"),  # Pharmaceutical / biologic product
-        "measurement": ("SNOMED", "363787002"),  # Observable entity
-        "device":      ("SNOMED", "260787004"),  # Physical object
+        "Condition":   ("SNOMED", "404684003"),  # Clinical finding
+        "Procedure":   ("SNOMED", "71388002"),   # Procedure
+        "Drug":        ("SNOMED", "373873005"),  # Pharmaceutical / biologic product
+        "Measurement": ("SNOMED", "363787002"),  # Observable entity
+        "Device":      ("SNOMED", "260787004"),  # Physical object
     }
 
     def _get_domain_root_ids(self, domain: str | None) -> tuple[int, ...]: