# OpenMed Project Structure: A Complete Guide to the Repository Layout

> Understand OpenMed's project structure. Explore the repository layout for this multi-language clinical NLP project, including Python and Swift components for diverse deployment needs.

- Repository: [Maziyar Panahi/openmed](https://github.com/maziyarpanahi/openmed)
- Tags: getting-started
- Published: 2026-06-13

---

**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`](https://github.com/maziyarpanahi/openmed/blob/main/README.md), `LICENSE`, and [`pyproject.toml`](https://github.com/maziyarpanahi/openmed/blob/main/pyproject.toml) defining the Python package dependencies. The [`Package.swift`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/pii.py), [`pii_i18n.py`](https://github.com/maziyarpanahi/openmed/blob/main/pii_i18n.py), and [`pii_entity_merger.py`](https://github.com/maziyarpanahi/openmed/blob/main/pii_entity_merger.py), plus quality gate validation in [`quality_gates.py`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/mlx/models/gliner_span.py) file implements optimized span-based entity recognition, while [`mlx/inference.py`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/app.py) serving as the main application entry point. The [`runtime.py`](https://github.com/maziyarpanahi/openmed/blob/main/runtime.py) module handles service lifecycle management, while [`limits.py`](https://github.com/maziyarpanahi/openmed/blob/main/limits.py) defines rate limiting and resource constraints. Key endpoints include `GET /health`, `POST /analyze`, and `POST /pii/extract`.

To start the service locally:

```bash
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`](https://github.com/maziyarpanahi/openmed/blob/main/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:

```swift
// 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:

```python
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`](https://github.com/maziyarpanahi/openmed/blob/main/scripts/release/release.sh) for version management, plus environment bootstrap scripts like [`reset_uv_env_and_run_tests.sh`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/pyproject.toml)** – Python package metadata and dependency specification
- **[`openmed/core/model_registry.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/core/model_registry.py)** – Central model management implementation
- **[`openmed/core/pii.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/core/pii.py)** – PII extraction and redaction logic
- **[`openmed/service/app.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/service/app.py)** – FastAPI application factory
- **[`Package.swift`](https://github.com/maziyarpanahi/openmed/blob/main/Package.swift)** – Swift package manifest for mobile framework distribution

## Summary

- **Root Level** – Contains [`pyproject.toml`](https://github.com/maziyarpanahi/openmed/blob/main/pyproject.toml), [`Package.swift`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/mlx/models/gliner_span.py) and inference utilities in [`openmed/mlx/inference.py`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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.