med-ontology-lookup

What it is

med-ontology-lookup is a Python library and command line tool, molu, that looks up medical terms and codes in RadLex, SNOMED CT, FMA, LOINC, and UMLS through the BioPortal and UMLS Terminology Services REST APIs.¹ It is the infrastructure layer under every other piece of OIDM work that needs to turn a phrase into a code: index code assignment on finding models, anatomic coding, and the enrichment pipeline.

Its stated purpose is broader than a search box. The roadmap describes it as “the small, dependable layer that lets people and agents resolve medical language to versioned concepts, inspect the clinically relevant part of an ontology graph, and translate identifiers without learning each terminology provider’s API.”²

The repository is openimagingdata/med-ontology-lookup. Install and API key instructions are in its README and are not repeated here.¹

Providers and credentials

Two backends, selected by which keys are present.

Provider	Reached through	Supplies	Key
BioPortal	data.bioontology.org	Multi-ontology class search, concept retrieval, one-hop hierarchy	BIOPORTAL_API_KEY, with BIOONTOLOGY_API_KEY accepted as an alias
UMLS Terminology Services	uts-ws.nlm.nih.gov	CUI resolution and crosswalk	UMLS_API_KEY, requiring a UMLS licence

Either key works alone, with reduced capability; crosswalk and CUI resolution need UMLS, and multi-ontology search and hierarchy need BioPortal. With both set, search queries both APIs and merges the results.¹ The default BioPortal ontologies are RADLEX, SNOMEDCT, FMA, and LOINC, and the default crosswalk targets are the UMLS source abbreviations SNOMEDCT_US, FMA, RADLEX, and LNC.³ The tool does not read a .env file itself; keys must already be in the environment.

Operations

Operation	What it does
search	Free-text search across the profile’s ontologies, with per-ontology queries so that SNOMED CT does not crowd out RadLex
lookup	Auto-detects whether the input is a term, a source code, or a CUI, then routes accordingly
get	Retrieves one concept by CUI, RadLex identifier, SNOMED CT code, or FMA identifier
crosswalk	Translates through UMLS CUIs to codes in other source vocabularies
parents and children	One hop up or down the hierarchy, for structural checks
Semantic type filters	-t keeps untyped hits, -T requires a type match

Detection is deliberately conservative: anything ambiguous stays a term so that search still works. A CUI is C followed by seven or more digits; RadLex is RID plus digits; FMA needs an explicit prefix; LOINC is one to seven digits, a hyphen, and one or two digits; a bare six to eighteen digit integer is treated as SNOMED CT.⁴

Results are typed. A Concept carries concept_id, code, ontology, pref_label, synonyms, definition, semantic_types, cuis, an obsolete flag, a user interface link, and the backend that produced it.⁵

Typed provider failures

The distinguishing design decision is that a failure is a result, not a silent fallback. A ProviderFailure carries a FailureCategory, including not_found, authentication, authorization, licensing, rate_limited, timeout, unavailable, and invalid_response, and a ProviderOperation naming which call failed.⁵ The policy is that only absence of a result or an unsupported operation may trigger a fallback to another provider; authentication, licensing, rate limit, timeout, and upstream unavailability stay visible instead of being disguised as an empty answer.⁶

This matters to callers because SNOMED CT and UMLS are licensed. An unlicensed caller gets a licensing failure rather than a result that looks like the concept does not exist.

Agent skill

The repository ships an agent skill under skills/med-ontology-lookup/, portable across agent runtimes, that tells an agent to classify the input, search first for free text, and use the CLI rather than scraping the BioPortal or UMLS web interfaces.⁷ It is the reason this tool appears in coding workflows across the other repositories.

Stated direction

Two documents state where the project is going. Both are planning documents in the repository, not released behaviour.

The project review and proposal sets out a six-phase delivery sequence after a governance phase: an offline baseline and provider-failure contract; trustworthy lookup contracts covering backend selection, identity, bounded collections, and provenance; delegated authentication with live contract checks and diagnostics; release preparation with an explicit publication checkpoint; an agent-ready terminology workflow; and bounded graph context with typed mappings.⁸ It also contains the delegated authentication design: a mode in which the tool reaches providers through a proxy so that upstream API keys need not live in client environments, with the guarantee that credentials are absent from final outgoing requests and that the authentication method is never inferred from a hostname.⁸⁹

The issue backlog turns that sequence into one tracking issue and eleven focused issues, in dependency order: offline CI, typed provider failures, explicit backend selection and readiness, shared identifier normalization, bounded collection semantics, request and terminology provenance, ambiguity-preserving UMLS expansion, direct and delegated provider endpoints, opt-in live contract checks, bounded provider diagnostics, and hardened release preparation.⁹

The product roadmap adds the domain profile design, including the radiology default profile that would make the LOINC/RSNA Radiology Playbook first-class. That part is catalogued under existing building blocks for exam types because it is the only written exam-type design in any OIDM repository.

Status

Read at main, commit a1fd3ae, dated 2026-09-20.

• There are no unmerged branches. The two named feature branches were merged and are now ancestors of main.
• Typed provider failures shipped on 2026-09-20.
• Offline continuous integration is implementation-complete but uncommitted, living in a sibling worktree and awaiting authorization to publish.
• Of the twelve backlog issues, only typed provider failures is closed; the tracking issue and ten others remain open, plus one filed outside the sequence for bounded, credential-safe caching.
• Delegated authentication is designed and not built.

Relation to the rest of OIDM

The relationship is real in practice and thin in the documentation. The enrichment pipeline in findingmodel runs ontology search concurrently with anatomic location lookup to propose index codes for a finding model, and that phase is recorded as complete.¹⁰ But that pipeline calls a BioOntology client of its own, and findingmodel issue 34 asks for that client and its ontology search protocol to move into the shared oidm-common package as infrastructure, described as a hard break requiring an environment-only API key.¹¹

No document in findingmodel or findingmodels links to this repository, and no OIDM package depends on it today. It is best read as the layer that the coding and enrichment work is converging toward rather than one it already runs on. See the repository map for where it sits among the other repositories.

Footnotes

1. med-ontology-lookup README ↩ ↩² ↩³

2. med-ontology-lookup product roadmap ↩

3. Default ontologies and source abbreviation maps, med-ontology-lookup ↩

4. Input kind detection, med-ontology-lookup ↩

5. Concept and provider failure models, med-ontology-lookup ↩ ↩²

6. Typed provider failures and operation-aware fallback ↩

7. Agent skill for the molu command line tool ↩

8. Project review and proposal ↩ ↩²

9. GitHub issue backlog ↩ ↩²

10. Finding enrichment implementation plan, findingmodel main branch ↩

11. findingmodel issue 34 ↩