K-Dense-AI/scientific-agent-skills / skills/ontology-term-resolution
ontology-term-resolution
VerifiedResolves free-text scientific labels to ontology term IDs and validates existing CURIEs against the EBI Ontology Lookup Service (OLS4). Also looks up prefixes in Bioregistry, resolves compact identifiers via Identifiers.org, maps lab shorthand with ZOOMA, and builds Ontobee term pages. Use whenever an ontology identifier must be produced or checked - annotating tissue, cell type, disease, phenotype, assay, chemical, organism, sex, or developmental stage fields; preparing metadata for GEO, ENA, BioSamples, CELLxGENE, HCA, or ISA-Tab submission; auditing a metadata table of term IDs; checking whether a term is obsolete and what replaced it; or deciding HPO vs HP. Triggers include "ontology term", "ontology ID", "CURIE", "controlled vocabulary", "UBERON", "CL:", "MONDO", "HPO", "EFO", "ChEBI", "NCBITaxon", "GO term", "PATO", "Zooma", "Bioregistry", "Identifiers.org", "Ontobee", "annotate this tissue/cell type/disease", and any request to emit or verify an identifier shaped like PREFIX:0001234.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.3 KB |
| references/companion-apis.md | markdown | 9.4 KB |
| references/curation-rules.md | markdown | 5.9 KB |
| references/ols4-api.md | markdown | 7.5 KB |
| references/ontology-registry.md | markdown | 6.1 KB |
| scripts/id_client.py | script | 11.5 KB |
| scripts/lookup_prefix.py | script | 6.3 KB |
| scripts/map_terms.py | script | 7.3 KB |
| scripts/ols_client.py | script | 15.5 KB |
| scripts/resolve_terms.py | script | 8.3 KB |
| scripts/validate_terms.py | script | 10.7 KB |
| scripts/zooma_client.py | script | 5.2 KB |
scripts/id_client.py
View on GitHub#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""Prefix and compact-identifier helpers for Bioregistry and Identifiers.org.
OLS checks whether a term is present and current in its loaded release. These
services answer a different question: is this prefix real, is the local id
well-formed, and which landing pages resolve it?
Standard library only. Network access to https://bioregistry.io and
https://resolver.api.identifiers.org is required for the request functions;
helpers below the ``--- pure helpers ---`` mark are offline.
Reviewed against official schemas and live APIs on 2026-10-01 (see
``references/companion-apis.md``):
* ``/api/registry/{prefix}`` accepts synonyms (``HPO`` → ``hp``) and returns
the canonical record. A 404 body is ``{"detail": "Prefix not found: ..."}``.
* ``/api/reference/{CURIE}`` validates the local id against ``pattern``. A
404 body of ``{"detail": "invalid identifier: ..."}`` means the prefix is
known and the local part is wrong — not that the prefix is unknown.
* Identifiers.org rejects synonym prefixes (``HPO:0001250`` → HTTP 400) and
also rejects Bioregistry's preferred prefix when that is not the MIRIAM
namespace (``ORPHA:558`` → 400; ``orphanet:558`` → 200). Landing pages
come from ``/api/reference/{CURIE}`` ``providers.miriam`` and the
registry ``mappings.ontobee`` field — never from templating
``preferred_prefix``.
"""
from __future__ import annotations
import json
import re
import time
import urllib.error
import urllib.parse
import urllib.request
from typing import Any
BIOREGISTRY_BASE = "https://bioregistry.io/api"
IDENTIFIERS_RESOLVER = "https://resolver.api.identifiers.org"
ONTOBEE_TERM = "https://ontobee.org/ontology/{prefix}?iri={iri}"
USER_AGENT = "scientific-agent-skills-ontology-term-resolution/1.4"
TIMEOUT = 30
MAX_ATTEMPTS = 3
RETRY_STATUS = {429, 500, 502, 503, 504}
CURIE_RE = re.compile(r"^([A-Za-z][A-Za-z0-9_.]*):(.+)$")
PREFIX_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_.]*$")
class IdError(RuntimeError):
"""A request to Bioregistry or Identifiers.org failed unrecoverably."""
class NotFoundError(IdError):
"""The remote service answered 404 with a JSON ``detail`` body."""
def __init__(self, detail: str, url: str):
super().__init__(detail)
self.detail = detail
self.url = url
def _request(url: str, *, return_rejection: bool = False) -> dict:
"""GET a JSON document, retrying transient failures."""
request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT, "Accept": "application/json"})
last: Exception | None = None
for attempt in range(MAX_ATTEMPTS):
try:
with urllib.request.urlopen(request, timeout=TIMEOUT) as response:
payload = json.load(response)
if not isinstance(payload, dict):
raise IdError(f"Expected a JSON object from {url}")
return payload
except urllib.error.HTTPError as exc:
body = exc.read().decode("utf-8", errors="replace")
if return_rejection and exc.code == 400:
try:
payload = json.loads(body)
except json.JSONDecodeError as error:
raise IdError(f"Non-JSON rejection from {url}") from error
if isinstance(payload, dict) and payload.get("errorMessage"):
return payload
raise IdError(f"Malformed rejection from {url}") from exc
if exc.code == 404:
detail = _detail_from_body(body) or f"HTTP 404 for {url}"
raise NotFoundError(detail, url) from exc
last = exc
if exc.code not in RETRY_STATUS:
raise IdError(f"HTTP {exc.code} for {url}: {body[:200]}") from exc
except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
last = exc
if attempt < MAX_ATTEMPTS - 1:
time.sleep(1.5 * (attempt + 1))
raise IdError(f"request failed after {MAX_ATTEMPTS} attempts: {url} ({last})")
def _detail_from_body(body: str) -> str:
try:
payload = json.loads(body)
except json.JSONDecodeError:
return body.strip()[:200]
if isinstance(payload, dict):
return str(payload.get("detail") or payload.get("errorMessage") or body[:200])
return body.strip()[:200]
def get_resource(prefix: str) -> dict:
"""Return the Bioregistry record for a prefix or synonym, or raise NotFoundError."""
encoded = urllib.parse.quote(prefix, safe="")
return _request(f"{BIOREGISTRY_BASE}/registry/{encoded}")
def get_reference(curie: str) -> dict:
"""Resolve a CURIE to provider URLs, validating the local id.
Raises ``NotFoundError`` when the prefix is unknown *or* the local id
fails the recorded pattern — inspect ``detail`` to tell them apart.
"""
encoded = urllib.parse.quote(curie, safe="")
return _request(f"{BIOREGISTRY_BASE}/reference/{encoded}")
def identifiers_resolver_url(curie: str) -> str:
"""Build the Identifiers.org resolver URL.
The colon in ``PREFIX:local`` must stay a colon. Encoding it as ``%3A``
is HTTP 400: ``NOT A NAMESPACE`` for a CURIE the service otherwise accepts.
"""
encoded = urllib.parse.quote(curie, safe=":")
return f"{IDENTIFIERS_RESOLVER}/{encoded}"
def resolve_identifiers(curie: str) -> dict:
"""Ask Identifiers.org for landing pages. Returns the JSON payload.
A rejected compact identifier comes back as HTTP 400 with
``errorMessage`` set and ``payload.resolvedResources`` null — that is
returned as a dict, not raised, so the caller can report it.
"""
return _request(identifiers_resolver_url(curie), return_rejection=True)
# --- pure helpers -----------------------------------------------------------
def split_query(value: str) -> tuple[str, str | None]:
"""Split ``PREFIX`` or ``PREFIX:local`` into ``(prefix, local_or_None)``."""
text = value.strip()
match = CURIE_RE.match(text)
if match:
return match.group(1), match.group(2)
return text, None
def is_prefix(value: str) -> bool:
"""True for a bare registry prefix, false for CURIEs and junk."""
return bool(PREFIX_RE.match(value.strip())) and ":" not in value.strip()
def local_matches_pattern(local: str, pattern: str | None) -> bool | None:
"""Check a local unique id against a Bioregistry regex.
Returns ``None`` when the registry has no pattern, so the caller can
distinguish "unchecked" from "failed".
"""
if not pattern:
return None
try:
return re.fullmatch(pattern, local) is not None
except re.error:
return None
def apply_uri_format(uri_format: str | None, local: str) -> str | None:
"""Fill a Bioregistry ``uri_format`` template (``$1`` is the local id)."""
if not uri_format or "$1" not in uri_format:
return None
return uri_format.replace("$1", local)
def ontobee_url(ontobee_prefix: str | None, iri: str | None) -> str | None:
"""Build the Ontobee HTML/RDF page for a term IRI.
``ontobee_prefix`` is Bioregistry ``mappings.ontobee``, not
``preferred_prefix``. Ontobee has no JSON search API. The page is the
product: HTML for humans, RDF when the same IRI is dereferenced as
linked data.
"""
if not ontobee_prefix or not iri:
return None
return ONTOBEE_TERM.format(
prefix=ontobee_prefix,
iri=urllib.parse.quote(iri, safe=""),
)
def compact_id_from_identifiers_url(url: str) -> str | None:
"""``https://identifiers.org/orphanet:558`` → ``orphanet:558``."""
if not url:
return None
path = urllib.parse.urlparse(url).path.lstrip("/")
return path or None
def landing_page_urls(
resource: dict | None,
reference: dict | None,
iri: str | None,
) -> tuple[str, str]:
"""Return ``(identifiers_org, ontobee)`` from mappings, never templates.
Identifiers.org comes from ``/api/reference/{CURIE}`` ``providers.miriam``.
Ontobee comes from the registry ``mappings.ontobee`` field plus ``iri``.
Either side is empty when that mapping is missing — Bioregistry's
preferred prefix is not a substitute.
"""
identifiers = ""
if reference:
providers = reference.get("providers") or {}
if isinstance(providers, dict):
identifiers = providers.get("miriam") or ""
ontobee = ""
if resource:
mappings = resource.get("mappings") or {}
ontobee = ontobee_url(mappings.get("ontobee"), iri) or ""
return identifiers, ontobee
def identifiers_landing_pages(payload: dict) -> list[dict[str, Any]]:
"""Flatten Identifiers.org ``resolvedResources`` into compact rows."""
resources = (payload.get("payload") or {}).get("resolvedResources") or []
rows = []
for item in resources:
rec = item.get("recommendation") or {}
rows.append(
{
"provider": item.get("providerCode") or "official",
"url": item.get("compactIdentifierResolvedUrl") or "",
"official": bool(item.get("official")),
"score": rec.get("recommendationIndex"),
}
)
rows.sort(key=lambda row: (not row["official"], -(row["score"] or 0)))
return rows
def classify_prefix_query(
query: str,
resource: dict | None,
*,
local: str | None,
reference_detail: str | None = None,
) -> dict:
"""Build the status record for one prefix or CURIE lookup.
Pure: callers supply the Bioregistry payload (or ``None`` on 404).
"""
prefix, parsed_local = split_query(query)
local = local if local is not None else parsed_local
result = {
"query": query,
"status": "ok",
"preferred_prefix": "",
"canonical_curie": "",
"pattern": "",
"example": "",
"name": "",
"default_iri": "",
"identifiers_org": "",
"ontobee": "",
"ols_id": "",
"detail": "",
}
if resource is None:
result["status"] = "unknown_prefix"
result["detail"] = reference_detail or f"no Bioregistry record for {prefix!r}"
return result
preferred = resource.get("preferred_prefix") or resource.get("prefix") or ""
canonical_prefix = resource.get("prefix") or ""
result["preferred_prefix"] = preferred
result["pattern"] = resource.get("pattern") or ""
result["example"] = resource.get("example") or ""
result["name"] = resource.get("name") or ""
mappings = resource.get("mappings") or {}
result["ols_id"] = mappings.get("ols") or ""
queried = prefix
accepted = {canonical_prefix.casefold(), preferred.casefold()} - {""}
if queried.casefold() not in accepted:
result["status"] = "synonym_prefix"
result["detail"] = f"{queried!r} is a synonym of preferred prefix {preferred}"
if local is None:
return result
matched = local_matches_pattern(local, result["pattern"] or None)
if matched is False or (reference_detail and "invalid identifier" in reference_detail):
result["status"] = "invalid_local"
result["detail"] = (
reference_detail
or f"{local!r} does not match pattern {result['pattern']}"
)
return result
canonical = f"{preferred}:{local}" if preferred else f"{canonical_prefix}:{local}"
result["canonical_curie"] = canonical
iri = apply_uri_format(resource.get("uri_format"), local)
result["default_iri"] = iri or ""
# Landing pages are filled by the caller from /api/reference providers
# and mappings.ontobee. Templating preferred_prefix here emits dead URLs
# (ORPHA:558, OBA:0000001).
return result
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |