biomedical-knowledge-lookup 2.2.0__tar.gz → 2.3.0__tar.gz

{biomedical_knowledge_lookup-2.2.0 → biomedical_knowledge_lookup-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biomedical-knowledge-lookup
-Version: 2.2.0
+Version: 2.3.0
 Summary: Unified biological concept lookup across 36 biomedical knowledge sources including BioPortal, OLS, UMLS, ChEMBL, DisGeNET, and more
 License-Expression: MIT
 License-File: LICENSE

{biomedical_knowledge_lookup-2.2.0 → biomedical_knowledge_lookup-2.3.0}/pyproject.toml

@@ -16,7 +16,7 @@ urls = { Documentation = "https://jonasheinickeBio.github.io/biomedical-knowledg
 # Optional feature groups. The core install pulls none of these; each dependency
 # guards its own import so `import knowledge_lookup` works without them and the
 # matching adapter/feature is simply disabled when absent.
-version = "2.2.0"
+version = "2.3.0"
 
 
 [project.optional-dependencies]

{biomedical_knowledge_lookup-2.2.0 → biomedical_knowledge_lookup-2.3.0}/src/knowledge_lookup/__init__.py

@@ -114,7 +114,7 @@ __all__ = [
 # poetry-dynamic-versioning rewrites the next line with the real version at build time
 # ([tool.poetry-dynamic-versioning.substitution] in pyproject.toml). Keep it the only line
 # that starts with `__version__ = "`, or the substitution would hit more than one line.
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 __author__ = "AID-PAIS Knowledge Graph Team"
 __description__ = "Unified biological concept lookup across multiple knowledge sources"
 

{biomedical_knowledge_lookup-2.2.0 → biomedical_knowledge_lookup-2.3.0}/src/knowledge_lookup/__main__.py

@@ -72,6 +72,26 @@ def search(
     partial: bool = typer.Option(
         False, "--partial", "-p", help="Enable partial/fuzzy matching (UMLS adapter)"
     ),
+    expand: bool = typer.Option(
+        False,
+        "--expand",
+        "-e",
+        help="Iteratively expand the query with synonyms/long-forms discovered from results "
+        "and search each new term (uses search_concepts_expanded)",
+    ),
+    relationships: bool = typer.Option(
+        False,
+        "--relationships",
+        help="With --expand, also traverse relationship edges (STRING interactions, KEGG "
+        "pathways, DisGeNET/Open Targets associations) and search their named targets "
+        "(implies --expand)",
+    ),
+    expand_hierarchy: bool = typer.Option(
+        False,
+        "--expand-hierarchy",
+        help="With --expand, traverse only taxonomic class<->member edges (OLS narrower/"
+        "broader, UMLS parent/child) so a class term surfaces its members (implies --expand)",
+    ),
 ):
     """
     Search for biological concepts across knowledge sources.
@@ -119,6 +139,31 @@ def search(
                         result = LookupResult(query=query)
                         result.add_concepts(umls_concepts, KnowledgeSource.UMLS)
                         return result
+                if expand or relationships or expand_hierarchy:
+                    if expand_hierarchy:
+                        from knowledge_lookup.core.term_expansion import (
+                            hierarchy_relationship_sources,
+                        )
+
+                        return await lkp.search_concepts_expanded(
+                            query=query,
+                            sources=source_enums,
+                            max_results=limit,
+                            relationships=True,
+                            relationship_sources=hierarchy_relationship_sources(lkp),
+                        )
+                    if relationships:
+                        return await lkp.search_concepts_expanded(
+                            query=query,
+                            sources=source_enums,
+                            max_results=limit,
+                            relationships=True,
+                        )
+                    return await lkp.search_concepts_expanded(
+                        query=query,
+                        sources=source_enums,
+                        max_results=limit,
+                    )
                 return await lkp.search_concepts(
                     query=query,
                     sources=source_enums,
@@ -249,6 +294,11 @@ def workflow(
     concept_types: list[str] | None = typer.Option(
         None, "--type", "-t", help="Filter by concept types"
     ),
+    relationships: bool = typer.Option(
+        False,
+        "--relationships",
+        help="Expand the search with relationship edges (interactions, pathways, class members)",
+    ),
 ):
     """
     Run the intelligent agent workflow with review and approval.
@@ -284,6 +334,7 @@ def workflow(
             export_path=export_path,
             max_iterations=max_iterations,
             auto_approve_threshold=auto_approve,
+            include_relationships=relationships,
         )
 
     result = asyncio.run(_run())

{biomedical_knowledge_lookup-2.2.0 → biomedical_knowledge_lookup-2.3.0}/src/knowledge_lookup/adapters/ols_adapter.py

@@ -65,6 +65,26 @@ class OLSAdapter(KnowledgeSourceAdapter):
                     # Get the first match
                     term_data = data["_embedded"]["terms"][0]
                     concept = self._convert_ols_concept_to_unified(term_data)
+                    if concept is not None:
+                        links = term_data.get("_links", {}) or {}
+                        child_labels = [
+                            label
+                            for _iri, label in await self._fetch_linked_terms(
+                                (links.get("children") or {}).get("href")
+                            )
+                            if label
+                        ]
+                        parent_labels = [
+                            label
+                            for _iri, label in await self._fetch_linked_terms(
+                                (links.get("parents") or {}).get("href")
+                            )
+                            if label
+                        ]
+                        if child_labels:
+                            concept.children = child_labels
+                        if parent_labels:
+                            concept.parents = parent_labels
                     return concept
 
             return None
@@ -73,6 +93,62 @@ class OLSAdapter(KnowledgeSourceAdapter):
             logger.error(f"Failed to get OLS concept details for '{concept_id}': {e}")
             return None
 
+    async def _fetch_linked_terms(
+        self, href: str | None, limit: int = 20
+    ) -> list[tuple[str, str]]:
+        """Follow an OLS ``_links`` hierarchy href (children/parents/...) and
+        return ``(iri, label)`` pairs. Any failure degrades to ``[]``."""
+        if not href:
+            return []
+        try:
+            base = href.split("?", 1)[0]
+            data = await self._make_request(base, {"size": max(1, min(limit, 200)), "page": 0})
+        except Exception as e:
+            logger.debug(f"OLS linked-terms request failed for {href}: {e}")
+            return []
+        terms = (data.get("_embedded") or {}).get("terms") or []
+        return [(t.get("iri", ""), t.get("label", "")) for t in terms if t.get("iri")]
+
+    async def get_relationships(self, concept_id: str, limit: int = 10) -> list[dict[str, Any]]:
+        """Return direct hierarchy neighbours of an OLS term as relationship
+        edges.
+
+        Resolves the term's ``_links.children``/``_links.parents`` (the API
+        supplies ready-to-follow hrefs, so no endpoint guessing) and returns
+        them in the adapter relationship shape. Narrower terms become
+        ``has_narrower`` (a class->member edge for class terms), broader terms
+        ``has_broader``. Non-IRI ids and any failure return ``[]``.
+        """
+        if not concept_id or "http" not in concept_id:
+            return []
+        try:
+            data = await self._make_request(f"{self.base_url}/terms", {"iri": concept_id})
+            terms = (data.get("_embedded") or {}).get("terms") or []
+            if not terms:
+                return []
+            links = terms[0].get("_links", {}) or {}
+        except Exception as e:
+            logger.error(f"OLS get_relationships failed for '{concept_id}': {e}")
+            return []
+
+        rels: list[dict[str, Any]] = []
+        for key, label in (("children", "has_narrower"), ("parents", "has_broader")):
+            href = (links.get(key) or {}).get("href")
+            for iri, name in await self._fetch_linked_terms(href, limit=limit):
+                if not name:
+                    continue
+                rels.append(
+                    {
+                        "relation_label": label,
+                        "related_id": iri,
+                        "related_name": name,
+                        "source": "OLS",
+                    }
+                )
+                if len(rels) >= limit:
+                    return rels
+        return rels
+
     def _convert_ols_result_to_concept(self, result: dict[str, Any]) -> UnifiedConcept | None:
         """Convert OLS search result to unified concept."""
         try:

{biomedical_knowledge_lookup-2.2.0 → biomedical_knowledge_lookup-2.3.0}/src/knowledge_lookup/agents/nodes/expand.py

@@ -34,7 +34,11 @@ from __future__ import annotations
 import asyncio
 
 from ...core.central_lookup import CentralKnowledgeLookup
-from ...core.term_expansion import AbbreviationSource, expand_and_search
+from ...core.term_expansion import (
+    AbbreviationSource,
+    default_relationship_sources,
+    expand_and_search,
+)
 from ...models import KnowledgeSource, LookupConfig
 from ..state import LookupWorkflowState, make_step
 from . import _limits
@@ -66,6 +70,12 @@ async def expand_node(state: LookupWorkflowState) -> dict:
         None if source_filter is None or KnowledgeSource.UMLS in source_filter else []
     )
     lookup = CentralKnowledgeLookup(config=config, auto_initialize=True)
+    # Relationship-edge expansion (interactions, pathways, associations, class
+    # members) is opt-in via the workflow state; off by default so the bounded
+    # quality pass stays cheap unless a caller asks for a relationship network.
+    relationship_sources = (
+        default_relationship_sources(lookup) if state.get("include_relationships") else None
+    )
     try:
         _, trace = await asyncio.wait_for(
             expand_and_search(
@@ -75,6 +85,7 @@ async def expand_node(state: LookupWorkflowState) -> dict:
                 max_rounds=_MAX_ROUNDS,
                 max_terms_per_round=_MAX_TERMS_PER_ROUND,
                 abbreviation_sources=abbreviation_sources,
+                relationship_sources=relationship_sources,
             ),
             timeout=_limits.EXPAND_TIMEOUT,
         )

{biomedical_knowledge_lookup-2.2.0 → biomedical_knowledge_lookup-2.3.0}/src/knowledge_lookup/agents/runners.py

@@ -41,6 +41,7 @@ def _initial_state(
     export_path: str | None,
     max_iterations: int,
     auto_approve_threshold: float,
+    include_relationships: bool = False,
 ) -> LookupWorkflowState:
     return {
         "query": query,
@@ -68,6 +69,7 @@ def _initial_state(
         "normalized_query": "",
         "original_query": query,
         "expanded_search_terms": [],
+        "include_relationships": include_relationships,
         "is_german": False,
         "quality_score": None,
         "quality_details": None,
@@ -125,6 +127,7 @@ async def run_workflow(
     export_path: str | None = None,
     max_iterations: int = 3,
     auto_approve_threshold: float = 0.8,
+    include_relationships: bool = False,
     checkpointer: BaseCheckpointSaver | None = None,
 ) -> dict:
     """Run the full lookup-review-approval-export workflow.
@@ -138,6 +141,8 @@ async def run_workflow(
         export_path: Directory for export files.
         max_iterations: Maximum lookup passes (initial search + refinements).
         auto_approve_threshold: Score above which auto-approval triggers.
+        include_relationships: Enable relationship-edge expansion (interactions,
+            pathways, class members) during the search step.
         checkpointer: Checkpointer holding paused runs. Defaults to a
             process-wide in-memory saver; pass the same one to
             :func:`resume_workflow`.
@@ -162,6 +167,7 @@ async def run_workflow(
         export_path=export_path,
         max_iterations=max_iterations,
         auto_approve_threshold=auto_approve_threshold,
+        include_relationships=include_relationships,
     )
 
     # Run the graph to completion (or interrupt)

{biomedical_knowledge_lookup-2.2.0 → biomedical_knowledge_lookup-2.3.0}/src/knowledge_lookup/agents/state.py

@@ -44,6 +44,9 @@ class LookupWorkflowState(TypedDict):
     normalized_query: str  # Cleaned/normalized version of the query
     original_query: str  # Original query as provided
     expanded_search_terms: list[str]  # Flat list of ALL search variants (searched in parallel)
+    include_relationships: (
+        bool  # Opt-in relationship-edge expansion (interactions, pathways, class members)
+    )
     is_german: bool  # Whether the query appears to be German
     quality_score: float | None  # Quality gate score (0-1)
     quality_details: dict | None  # Quality breakdown