# How to Select a Model from OpenMed's Registry: A Complete Guide

> Easily select models from OpenMed's registry using the ModelLoader class. This guide shows how to map symbolic keys to HuggingFace model IDs for your AI projects.

- Repository: [Maziyar Panahi/openmed](https://github.com/maziyarpanahi/openmed)
- Tags: how-to-guide
- Published: 2026-06-12

---

**You can select an OpenMed model by querying the built-in registry using the `ModelLoader` class, which maps symbolic keys like `disease_detection_tiny` to full HuggingFace model IDs via the `OPENMED_MODELS` dictionary defined in [`openmed/core/model_registry.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/core/model_registry.py).**

Selecting the right medical NLP model from OpenMed's registry allows you to leverage pre-trained biomedical models without hard-coding HuggingFace URLs. The `maziyarpanahi/openmed` repository provides a centralized model registry that loads metadata from a static manifest and exposes convenient lookup methods for filtering by category, size, or clinical domain.

## How the OpenMed Model Registry Is Constructed

The registry system separates model discovery from model loading. At import time, [`openmed/core/model_registry.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/core/model_registry.py) builds a module-level constant `OPENMED_MODELS` by parsing the static `models.jsonl` manifest file located at the repository root.

### Loading the Manifest and Creating ModelInfo Objects

The `load_manifest_rows()` function reads the JSONL file (defined at `MANIFEST_PATH = Path(__file__).resolve().parents[2] / "models.jsonl"`). Each row is converted into a `ModelInfo` dataclass by `_model_info_from_row()`, which extracts fields including category, display name, entity types, size category, and recommended confidence thresholds.

### Generating Registry Keys

The `_registry_key()` function categorizes models into families—Privacy (PII), NER, or general—while `_unique_key()` appends format-specific suffixes to ensure uniqueness when collisions occur. Finally, `_compatibility_aliases()` adds legacy aliases to maintain backward compatibility with older codebases.

## Querying the Registry to Select Models

Once loaded, the registry exposes several helper functions to locate specific models without manually searching the JSONL file:

- **`get_model_info(key)`** – Returns a `ModelInfo` dataclass for a registry key or full repo ID.
- **`get_models_by_category(cat)`** – Filters models by clinical category (e.g., *Disease*, *Oncology*, *Privacy*).
- **`get_models_by_size(size)`** – Returns models matching size buckets like *Tiny*, *Small*, or *Base*.
- **`get_model_suggestions(text)`** – Heuristically suggests up to three models based on keywords in clinical text.
- **`list_model_categories()`** – Returns all available categories present in the registry.
- **`get_pii_models_by_language(lang)`** – Retrieves language-specific PII models (e.g., `pii_fr_...`).

### Listing All Available Models

To view every registry key programmatically:

```python
from openmed.core.models import ModelLoader

loader = ModelLoader()
print(loader.list_available_models())

```

### Retrieving Detailed Model Metadata

Access the `ModelInfo` dataclass for a specific key to inspect its HuggingFace ID, entity types, and recommended confidence:

```python
from openmed.core.models import ModelLoader

loader = ModelLoader()
info = loader.get_registry_info('oncology_detection_tiny')
print(info)

```

### Finding Models by Clinical Context

The registry can suggest appropriate models based on raw clinical text heuristics:

```python
from openmed.core.models import ModelLoader

loader = ModelLoader()
text = "Patient was diagnosed with metastatic breast cancer and started on paclitaxel."
suggestions = loader.get_model_suggestions(text)
for key, model, reason in suggestions:
    print(f"{key}: {model.display_name} ({reason})")

```

### Filtering PII Models by Language

For privacy-focused applications, select language-specific models using the registry's dedicated helper:

```python
from openmed.core.model_registry import get_pii_models_by_language

fr_models = get_pii_models_by_language('fr')
for key, info in fr_models.items():
    print(key, info.display_name)

```

## Loading and Running Models from the Registry

The `ModelLoader` class in [`openmed/core/models.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/core/models.py) bridges the registry and HuggingFace's infrastructure. When you request a model, the loader uses `_resolve_model_name()` to translate registry keys to full model IDs, then caches the model, tokenizer, and pipeline for reuse.

### Creating an Inference Pipeline

```python
from openmed.core.models import ModelLoader

loader = ModelLoader()
pipeline = loader.create_pipeline('disease_detection_tiny')
result = pipeline("The patient suffers from diabetes mellitus.")
print(result)

```

## Summary

- The OpenMed registry is defined in [`openmed/core/model_registry.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/core/model_registry.py) and loads from `models.jsonl` at runtime to populate the `OPENMED_MODELS` dictionary.
- Use `ModelLoader` to query available models without hard-coding HuggingFace URLs, leveraging methods like `list_available_models()` and `get_registry_info()`.
- Filter models by clinical category, size bucket, or language using helpers such as `get_models_by_category()` and `get_pii_models_by_language()`.
- The `get_model_suggestions()` function analyzes clinical text to recommend relevant models based on detected keywords.
- `ModelLoader` caches loaded models and tokenizers to avoid redundant downloads and API calls.

## Frequently Asked Questions

### How do I find the registry key for a specific OpenMed model?

You can call `loader.list_available_models()` on a `ModelLoader` instance to see all available keys, or use `get_model_suggestions()` with sample text from your clinical domain to receive heuristic recommendations. Each key maps to a `ModelInfo` object containing the full HuggingFace model ID as the `model_id` attribute.

### What is the difference between the registry key and the model ID?

The registry key is a human-readable shorthand (e.g., `disease_detection_tiny`) used within OpenMed's ecosystem, while the model ID is the full HuggingFace repository path (e.g., `OpenMed/OpenMed-NER-DiseaseDetection-TinyMed-65M`). The `ModelLoader` automatically translates keys to IDs using the internal `_resolve_model_name()` method.

### Can I filter models by supported languages?

Yes. For PII detection models, use `get_pii_models_by_language(lang)` from [`openmed/core/model_registry.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/core/model_registry.py), passing the ISO language code (e.g., `'fr'` for French). For other categories, inspect the `languages` field of the `ModelInfo` dataclass returned by `get_model_info()`.

### Where is the model metadata stored?

The static metadata lives in `models.jsonl` at the repository root, which is parsed at import time by `load_manifest_rows()` in [`openmed/core/model_registry.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/core/model_registry.py). This file contains the definitive list of supported models, their categories, sizes, supported entity types, and compatibility aliases.