Map biotools ID and name gh->bt (#115)

* feat: implement name mapping function

* feat: wire in the mapping

* feat: implement and wire the mapping for bt id

* feat: add optional equality func param to policy

* chore: use the new equality param in name mapping

* doc: add placeholders for process diagrams for new maps

Author: thatmariia

docs/source/api_reference/diagrams.rst

@@ -57,7 +57,17 @@ Map publications
 Map documentation
 ~~~~~~~~~~~~~~~~~~~~
 
-TODO: add diagram here once errors in the mapping function are resolved.
+TODO: add diagram here.
+
+Map biotools ID
+~~~~~~~~~~~~~~~~~~
+
+TODO: add diagram here.
+
+Map name
+~~~~~~~~~~
+
+TODO: add diagram here.
 
 Map homepage
 ~~~~~~~~~~~~~~
@@ -114,7 +124,7 @@ Map topics
 Map version
 ~~~~~~~~~~~~~~
 
-TODO: add diagram here once errors in the mapping function are resolved.
+TODO: add diagram here.
 
 
 bio.tools → GitHub mapping for pull requests

src/bridge/pipelines/gh2bt_for_meta/main.py

@@ -77,7 +77,8 @@ async def run(args: GitHubToBiotoolsForMetaPipelineArgs) -> BiotoolsToolModel:
     )
 
     biotools_metadata = BiotoolsToolModel(
-        name=github_repo.repo.name,
+        biotoolsID=await mapper.map["biotools_id"].run(),
+        name=await mapper.map["name"].run(),
         description=((await mapper.map["description"].run()) or "***Please change this description***"),
         homepage=await mapper.map["homepage"].run(),
         maturity=await mapper.map["maturity"].run(),

src/bridge/pipelines/gh2bt_for_meta/map.py

@@ -8,12 +8,14 @@
 from bridge.pipelines.utils import load_dict_from_yaml_file
 
 from .map_funcs import (
+    map_biotools_id,
     map_description,
     map_documentation,
     map_homepage,
     map_language,
     map_license,
     map_maturity,
+    map_name,
     map_publication,
     map_version,
 )
@@ -34,7 +36,15 @@ def map(self) -> dict[str, MapItem]:
         Map GitHub metadata property to corresponding bio.tools property.
         """
         return {
-            "name": MapItem(schema_entry=self.metadata.name, repo_entry=self.repo.repo.name, method=Method.EXACT),
+            "biotools_id": MapItem(
+                schema_entry=self.metadata.biotoolsID,
+                repo_entry=self.repo.repo.name,
+                method=Method.FUZZY,
+                fn=map_biotools_id,
+            ),
+            "name": MapItem(
+                schema_entry=self.metadata.name, repo_entry=self.repo.repo.name, method=Method.EXACT, fn=map_name
+            ),
             # Languages are both lists
             "language": MapItem(
                 schema_entry=self.metadata.language,

src/bridge/pipelines/gh2bt_for_meta/map_funcs/__init__.py

@@ -2,12 +2,14 @@
 Individual mapping functions for GitHub to bio.tools.
 """
 
+from .biotools_id import map_biotools_id
 from .description import map_description
 from .documentation import map_documentation
 from .homepage import map_homepage
 from .language import map_language
 from .license import map_license
 from .maturity import map_maturity
+from .name import map_name
 from .publication import map_publication
 from .version import map_version
 
@@ -20,4 +22,6 @@
     "map_maturity",
     "map_version",
     "map_publication",
+    "map_name",
+    "map_biotools_id",
 ]

src/bridge/pipelines/gh2bt_for_meta/map_funcs/biotools_id.py

@@ -0,0 +1,111 @@
+"""
+Map GitHub repository name to bio.tools ID.
+
+This module reconciles the GitHub repository name with the bio.tools ID.
+It applies a policy that prefers the GitHub name while ensuring uniqueness
+within bio.tools, generating alternative IDs if necessary.
+"""
+
+import httpx
+
+from bridge.builders import compose_biotools_metadata
+from bridge.logging import get_user_logger
+from bridge.pipelines.utils import normalize_text, str_contain_each_other
+
+logger = get_user_logger()
+
+
+async def _matching_biotools_id_exists(biotools_id: str) -> bool:
+    """
+    Check if a bio.tools entry with the given ID already exists.
+
+    The check is performed by attempting to fetch bio.tools metadata
+    for the given ID. If a 404 Not Found error is returned, the ID
+    does not exist. Any other error is treated as an indication that
+    the ID may exist, to avoid false negatives.
+
+    Parameters
+    ----------
+    biotools_id : str
+        Candidate bio.tools ID to check.
+
+    Returns
+    -------
+    bool
+        True if a matching bio.tools entry exists, False otherwise.
+    """
+    try:
+        matching_bt_metadata = await compose_biotools_metadata(identifier=biotools_id)
+    except Exception as e:
+        if isinstance(e, httpx.HTTPStatusError) and e.response.status_code == 404:
+            return False
+        else:
+            logger.added(f"Failed to check existing bio.tools ID '{biotools_id}': {e}. Assuming it exists.")
+            return True
+
+    return matching_bt_metadata is not None
+
+
+async def map_biotools_id(gh_name: str | None, bt_id: str | None) -> str | None:
+    """
+    Map and reconcile GitHub repository name to bio.tools ID.
+
+    Policy:
+    1. If no GitHub repo name is available, preserve existing bio.tools ID (even if None).
+    2. If the existing bio.tools ID and GitHub repo name contain each other
+       (case-insensitive), preserve the existing bio.tools ID.
+    3. If they do not contain each other, log a conflict but continue.
+    4. If the GitHub repo name is not already used as a bio.tools ID,
+       use it as the new bio.tools ID.
+    5. If the GitHub repo name is already used as a bio.tools ID,
+       attempt to generate a unique ID by appending suffixes ``-1``, ``-2``, ...
+       up to ``-99``. If a unique ID is found, use it.
+    6. If no unique ID can be generated, log a note and return ``None``,
+       requiring manual intervention.
+
+    Parameters
+    ----------
+    gh_name : str | None
+        GitHub repository name.
+    bt_id : str | None
+        Existing bio.tools ID.
+
+    Returns
+    -------
+    str | None
+        Mapped bio.tools ID, or ``None`` if mapping failed.
+    """
+    if gh_name is None:
+        logger.unchanged("No GitHub repo name found, nothing to map.")
+        return bt_id
+
+    gh_norm = normalize_text(gh_name)
+    bt_norm = normalize_text(bt_id or "")
+
+    if bt_id is not None and str_contain_each_other(gh_norm, bt_norm):
+        logger.exact(f"bio.tools ID '{bt_id}' and GitHub repo name '{gh_name}' contain each other")
+        return bt_id
+
+    if bt_id is not None and not str_contain_each_other(gh_norm, bt_norm):
+        logger.conflict(f"bio.tools ID '{bt_id}' and GitHub repo name '{gh_name}' do not contain each other")
+
+    if not await _matching_biotools_id_exists(gh_norm):
+        logger.added(f"Using GitHub repo name '{gh_name}' as bio.tools ID")
+        return gh_norm
+
+    logger.conflict(
+        f"GitHub repo name '{gh_name}' cannot be used as bio.tools ID because it matches an existing entry. "
+        "Trying to generate a unique bio.tools ID."
+    )
+
+    for suffix in range(1, 100):
+        candidate_id = f"{gh_norm}-{suffix}"
+        if not await _matching_biotools_id_exists(candidate_id):
+            logger.added(f"Using generated bio.tools ID '{candidate_id}'")
+            return candidate_id
+
+    logger.note(
+        f"Failed to generate unique bio.tools ID based on GitHub repo name '{gh_name}'. "
+        "Please set bio.tools ID manually."
+    )
+    return None

src/bridge/pipelines/gh2bt_for_meta/map_funcs/name.py

@@ -0,0 +1,47 @@
+"""
+Mapping name from GitHub to bio.tools.
+
+This module reconciles the GitHub repository name with the bio.tools name.
+It compares the two names and applies a policy that prefers the GitHub name
+while preserving the bio.tools name when GitHub is silent or ambiguous.
+"""
+
+from bridge.logging import get_user_logger
+from bridge.pipelines.policies.gh2bt import reconcile_gh_over_bt
+from bridge.pipelines.utils import normalize_text, str_contain_each_other
+
+logger = get_user_logger()
+
+
+def map_name(gh_name: str | None, bt_name: str | None) -> str | None:
+    """
+    Map and reconcile GitHub and bio.tools names using the generic
+    GitHub-over-bio.tools policy.
+
+    Parameters
+    ----------
+    gh_name : str | None
+        GitHub repository name.
+    bt_name : str | None
+        Existing bio.tools name.
+
+    Returns
+    -------
+    str | None
+        Mapped bio.tools name.
+    """
+    if gh_name is None:
+        logger.unchanged("No GitHub name found, nothing to map.")
+        return bt_name
+
+    gh_norm = normalize_text(gh_name)
+    bt_norm = normalize_text(bt_name)
+
+    return reconcile_gh_over_bt(
+        gh_norm=gh_norm,
+        bt_norm=bt_norm,
+        bt_value=bt_name,
+        build_bt_from_gh=lambda name: name,
+        log_label="name",
+        equality_fn=str_contain_each_other,
+    )

src/bridge/pipelines/policies/gh2bt/reconcile_gh_over_bt.py

@@ -25,6 +25,7 @@ def reconcile_gh_over_bt(
     bt_value: BT | None,
     build_bt_from_gh: Callable[[GHN], BT],
     log_label: str,
+    equality_fn: Callable[[GHN, BTN], bool] | None = None,
 ) -> BT | None:
     """
     Apply a generic GitHub-over-bio.tools reconciliation policy.
@@ -66,6 +67,11 @@ def reconcile_gh_over_bt(
     log_label : str
         Short label used in log messages to identify the reconciled field
         (e.g., ``"license"``, ``"languages"``, ``"homepage"``).
+    equality_fn : Callable[[GHN, BTN], bool] | None, optional
+        Optional callable to determine equality between normalized GitHub and
+        bio.tools values. If ``None``, the default equality operator (``==``)
+        is used. This parameter is useful when the normalized representations
+        require custom comparison logic (e.g., set equality for lists).
 
     Returns
     -------
@@ -87,7 +93,12 @@ def reconcile_gh_over_bt(
         logger.added(f"{log_label} from GitHub: {gh_norm!r}")
         return gh_from_bt
 
-    if gh_from_bt == bt_norm:
+    if equality_fn is not None:
+        equal = equality_fn(gh_from_bt, bt_norm)
+    else:
+        equal = gh_from_bt == bt_norm
+
+    if equal:
         logger.exact(f"GitHub {log_label} matches bio.tools {log_label}.")
         return bt_value
 

src/bridge/pipelines/utils/__init__.py

@@ -12,6 +12,7 @@
     normalize_pydantic_model_strings,
     normalize_text,
 )
+from .comparisons import str_contain_each_other
 from .conversions import find_matching_enum_member, object_to_primitive, svg_to_base64
 from .files import check_file_with_extension_exists, get_file_content, load_dict_from_yaml_file
 from .templating import fill_template, remove_first_snippet_from_text
@@ -34,4 +35,5 @@
     "svg_to_base64",
     "find_matching_enum_member",
     "object_to_primitive",
+    "str_contain_each_other",
 ]

src/bridge/pipelines/utils/comparisons.py

@@ -0,0 +1,24 @@
+"""
+Utility functions for comparisons.
+"""
+
+
+def str_contain_each_other(str1: str, str2: str) -> bool:
+    """
+    Check if two strings contain each other (case-insensitive).
+
+    Parameters
+    ----------
+    str1 : str
+        First string.
+    str2 : str
+        Second string.
+
+    Returns
+    -------
+    bool
+        True if either string contains the other, False otherwise.
+    """
+    str1_lower = str1.lower()
+    str2_lower = str2.lower()
+    return str1_lower in str2_lower or str2_lower in str1_lower