OpenMed Project Structure: A Complete Guide to the Repository Layout

OpenMed organizes clinical NLP capabilities into a multi-language Python and Swift repository, with the core openmed/ package containing model registry, MLX acceleration, NER pipelines, and FastAPI services, alongside a Swift OpenMedKit framework for iOS/macOS deployment.

The maziyarpanahi/openmed repository follows a modular architecture designed to support both server-side Python deployments and on-device mobile inference. Understanding this project structure is essential for developers integrating clinical entity recognition models, deploying REST APIs, or embedding the framework into Swift applications.

Repository Root Structure

The top-level directory contains standard Python packaging metadata and dual-language build configuration files. At the root, you will find README.md, LICENSE, and pyproject.toml defining the Python package dependencies. The Package.swift manifest enables Swift Package Manager integration for mobile developers, while Dockerfile provides containerization for the FastAPI service.

Key directories at the root level include:

• openmed/ – The core Python package containing all clinical NLP logic
• swift/ – Swift package providing the OpenMedKit iOS/macOS framework
• docs/ – MkDocs documentation site configuration and markdown sources
• examples/ – Ready-to-run Jupyter notebooks and demonstration scripts
• tests/ – Unit and integration test suite covering core logic and API endpoints
• scripts/ – Release automation and environment bootstrap utilities

Core Python Package Architecture (openmed/)

The openmed/ directory implements the heart of the clinical NLP system, organized into functional submodules that separate model management, inference, and service layers.

Model Registry and Core Logic (openmed/core/)

The openmed/core/ module defines the abstract ModelRegistry class in model_registry.py, which manages model loading and lifecycle across different backends. This directory also contains the PII (Personally Identifiable Information) pipeline implementation across pii.py, pii_i18n.py, and pii_entity_merger.py, plus quality gate validation in quality_gates.py.

Apple Silicon Acceleration (openmed/mlx/)

For Apple Silicon devices, the openmed/mlx/ directory contains lightweight wrappers for MLX-accelerated inference. The mlx/models/gliner_span.py file implements optimized span-based entity recognition, while mlx/inference.py provides utilities for running models on local Apple hardware with Metal Performance Shaders.

Named Entity Recognition (openmed/ner/)

The openmed/ner/ submodule houses zero-shot NER implementations including GLiNER (Generalist Lightweight Model for Named Entity Recognition) and custom clinical adapters. This separation allows the system to support multiple NER families while maintaining a consistent interface for entity extraction.

Clinical Processing and Utilities

Supporting modules include openmed/processing/ for batching, tokenization, and sentence handling, openmed/clinical/ for clinical-specific utilities, and openmed/utils/ for profiling, logging, and validation helpers. These utilities ensure consistent data handling across the pipeline.

REST Service Layer (openmed/service/)

The FastAPI-based microservice resides in openmed/service/, with app.py serving as the main application entry point. The runtime.py module handles service lifecycle management, while limits.py defines rate limiting and resource constraints. Key endpoints include GET /health, POST /analyze, and POST /pii/extract.

To start the service locally:

uvicorn openmed.service.app:app --host 0.0.0.0 --port 8080

Command Line Interface (openmed/cli/)

The openmed/cli/ directory provides the Typer-based command-line entry point via typer_app.py. This exposes the openmed-cli command, which forwards to analyze_text and other core utilities for terminal-based text processing workflows.

Swift OpenMedKit Framework (swift/)

The swift/ directory contains a complete Swift package that mirrors the Python API for on-device inference. The OpenMedKit framework supports iOS and macOS applications, with OpenMedDemo/ and OpenMedScanDemo/ subdirectories providing sample applications that demonstrate camera-based clinical text scanning and entity recognition.

To integrate into an iOS project:

// Package.swift entry
.package(url: "https://github.com/maziyarpanahi/openmed.git", from: "1.5.5")

Documentation, Examples, and Testing Infrastructure

Documentation (docs/)

The docs/ directory contains a complete MkDocs site with guides for the MLX backend, CoreML export workflows, and API references. Each documentation page links back to relevant source files, creating a guided tour of the architecture.

Runnable Examples (examples/)

The examples/ folder provides practical Python notebooks and scripts demonstrating typical workflows. These include privacy filter demonstrations, batch processing pipelines, and model comparison utilities.

Quick usage example:

from openmed import analyze_text

result = analyze_text(
    "Patient started on imatinib for chronic myeloid leukemia.",
    model_name="disease_detection_superclinical",
)

for ent in result.entities:
    print(f"{ent.label:<12} {ent.text:<28} {ent.confidence:.2f}")

Test Suite (tests/)

The tests/ directory contains extensive unit and integration tests ensuring correct behavior across the model registry, service API, and privacy filter modules. Tests validate functionality across different backends (CPU, MLX, CoreML) and platforms.

Automation Scripts (scripts/)

The scripts/ directory houses release tooling including scripts/release/release.sh for version management, plus environment bootstrap scripts like reset_uv_env_and_run_tests.sh for development environment preparation.

Key Configuration Files

Several critical files define the build and runtime behavior:

• pyproject.toml – Python package metadata and dependency specification
• openmed/core/model_registry.py – Central model management implementation
• openmed/core/pii.py – PII extraction and redaction logic
• openmed/service/app.py – FastAPI application factory
• Package.swift – Swift package manifest for mobile framework distribution

Summary

• Root Level – Contains pyproject.toml, Package.swift, Dockerfile, and directory pointers for the dual-language architecture
• openmed/ – Core Python package with core/ (registry, PII), mlx/ (Apple Silicon), ner/ (entity recognition), service/ (FastAPI), and cli/ (Typer interface)
• swift/ – Swift OpenMedKit framework for native iOS/macOS deployment with demo applications
• docs/, examples/, tests/, scripts/ – Supporting infrastructure for documentation, demonstrations, validation, and release automation

Frequently Asked Questions

What is the main entry point for using OpenMed as a Python library?

The primary entry point is the analyze_text function exported from openmed/__init__.py. This function accepts clinical text and model names, routing to the appropriate backend (standard PyTorch or MLX) while handling PII filtering and quality gates automatically.

Where are the MLX acceleration models located in the OpenMed project structure?

MLX-specific implementations reside in openmed/mlx/, with model architectures defined in openmed/mlx/models/gliner_span.py and inference utilities in openmed/mlx/inference.py. These files provide Apple Silicon-optimized paths for the GLiNER NER models.

How does OpenMed support iOS and macOS development?

The swift/ directory contains the OpenMedKit Swift package, defined by Package.swift at the repository root. This framework wraps the core clinical NLP functionality for native mobile deployment, with sample apps in swift/OpenMedDemo/ and swift/OpenMedScanDemo/ demonstrating integration patterns.

What testing framework does OpenMed use for its validation suite?

The tests/ directory contains unit and integration tests covering the core logic in openmed/core/, the FastAPI service endpoints in openmed/service/, and the privacy filter implementations. The test suite validates behavior across CPU and MLX backends to ensure cross-platform consistency.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}