# Integrating OpenMedKit Swift Library in iOS Applications: Complete Setup Guide

> Integrate OpenMedKit Swift library into your iOS app. Easily add the maziyarpanahi/openmed package, initialize OpenMed, and extract PII for clinical entity recognition on-device.

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

---

**To integrate OpenMedKit into an iOS application, add the Swift package from the `maziyarpanahi/openmed` repository, initialize an `OpenMed` instance with either the MLX or CoreML backend, and call `extractPII(_:confidenceThreshold:)` to perform on-device clinical entity recognition and PII de-identification.**

OpenMedKit is a Swift package that brings clinical NLP capabilities—including named entity recognition (NER) and PII de-identification—directly to iOS, iPadOS, and macOS applications. Integrating this library enables developers to run HIPAA-compliant text analysis locally without network latency, leveraging the `OpenMedBackend` enum to choose between MLX acceleration on Apple Silicon or CoreML for simulator compatibility. The integration process involves adding the package dependency, configuring the appropriate backend in [`swift/OpenMedKit/Sources/OpenMedKit/OpenMedBackend.swift`](https://github.com/maziyarpanahi/openmed/blob/main/swift/OpenMedKit/Sources/OpenMedKit/OpenMedBackend.swift), and calling the high-level API defined in [`swift/OpenMedKit/Sources/OpenMedKit/OpenMedKit.swift`](https://github.com/maziyarpanahi/openmed/blob/main/swift/OpenMedKit/Sources/OpenMedKit/OpenMedKit.swift).

## Adding the OpenMedKit Dependency

You can add the OpenMedKit Swift package to your iOS project using either the Xcode user interface or by modifying your [`Package.swift`](https://github.com/maziyarpanahi/openmed/blob/main/Package.swift) manifest.

### Via Xcode

1. Open your iOS project in Xcode.
2. Select **File > Add Package Dependencies…**.
3. Enter the repository URL: `https://github.com/maziyarpanahi/openmed`.
4. Select the **OpenMedKit** product and add it to your app target.

### Via Package.swift

Add the following to your [`Package.swift`](https://github.com/maziyarpanahi/openmed/blob/main/Package.swift) dependencies, referencing the package manifest located at [`swift/OpenMedKit/Package.swift`](https://github.com/maziyarpanahi/openmed/blob/main/swift/OpenMedKit/Package.swift):

```swift
dependencies: [
    .package(url: "https://github.com/maziyarpanahi/openmed.git", from: "1.5.5")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "OpenMedKit", package: "openmed")
        ]
    )
]

```

## Selecting a Runtime Backend

OpenMedKit abstracts the model runtime behind the `OpenMedBackend` enum defined in [`swift/OpenMedKit/Sources/OpenMedKit/OpenMedBackend.swift`](https://github.com/maziyarpanahi/openmed/blob/main/swift/OpenMedKit/Sources/OpenMedKit/OpenMedBackend.swift). You must choose between two backends based on your deployment target:

- **MLX**: Loads Hugging Face MLX artifacts with Apple Silicon acceleration. Use this for physical iPhone/iPad devices or Apple Silicon Macs.
- **CoreML**: Uses pre-converted CoreML bundles (`.mlmodelc` or `.mlpackage`) shipped with your app. Use this when targeting the iOS simulator or when you have existing CoreML models.

### MLX Backend for Apple Silicon Devices

The MLX backend downloads model artifacts from Hugging Face Hub using the `OpenMedModelStore` class defined in [`swift/OpenMedKit/Sources/OpenMedKit/OpenMedModelStore.swift`](https://github.com/maziyarpanahi/openmed/blob/main/swift/OpenMedKit/Sources/OpenMedKit/OpenMedModelStore.swift). The `downloadMLXModel(repoID:)` function handles caching and local storage automatically.

```swift
import OpenMedKit

// Download the MLX artifact (async, cached locally)
let modelDirectory = try await OpenMedModelStore.downloadMLXModel(
    repoID: "OpenMed/OpenMed-PII-ClinicalE5-Small-33M-v1-mlx"
)

// Initialize OpenMed with MLX backend
let openmed = try OpenMed(
    backend: .mlx(modelDirectoryURL: modelDirectory)
)

// Extract PII entities
let entities = try openmed.extractPII(
    "Patient John Doe, DOB 1990-05-15, SSN 123-45-6789",
    confidenceThreshold: 0.5
)

```

### CoreML Backend for Bundled Models

The CoreML backend requires you to bundle the `.mlmodelc` compiled model and an [`id2label.json`](https://github.com/maziyarpanahi/openmed/blob/main/id2label.json) mapping file with your app. This approach works on both physical devices and the iOS simulator.

```swift
import OpenMedKit

// Locate bundled resources
let modelURL = Bundle.main.url(forResource: "OpenMedPII", withExtension: "mlmodelc")!
let labelURL = Bundle.main.url(forResource: "id2label", withExtension: "json")!

// Initialize OpenMed with CoreML backend
let openmed = try OpenMed(
    backend: .coreML(
        modelURL: modelURL,
        id2labelURL: labelURL,
        tokenizerName: "OpenMed/OpenMed-PII-ClinicalE5-Small-33M-v1"
    )
)

// Run entity extraction
let entities = try openmed.extractPII("Patient Jane Doe, SSN 000-00-0000")

```

## Implementing the API in SwiftUI

The following SwiftUI view demonstrates a complete integration pattern adapted from the demo app in [`swift/OpenMedScanDemo/OpenMedScanDemo/OpenMedScanDemo/ContentView.swift`](https://github.com/maziyarpanahi/openmed/blob/main/swift/OpenMedScanDemo/OpenMedScanDemo/OpenMedScanDemo/ContentView.swift). This example uses the MLX backend with asynchronous model downloading:

```swift
import SwiftUI
import OpenMedKit

struct PIIExtractorView: View {
    @State private var text = "Patient: Jane Doe, DOB: 01/15/1970, SSN: 000-00-0000"
    @State private var entities: [EntityPrediction] = []
    @State private var isLoading = false
    @State private var errorMessage: String?

    var body: some View {
        VStack {
            TextEditor(text: $text)
                .border(Color.gray)
                .frame(height: 150)

            if isLoading {
                ProgressView("Loading model…")
            }

            Button("Detect PII") {
                Task { await performExtraction() }
            }
            .disabled(isLoading)

            if let error = errorMessage {
                Text(error).foregroundColor(.red)
            }

            List(entities) { entity in
                VStack(alignment: .leading) {
                    Text("[\(entity.label)] \(entity.text)")
                    Text("Confidence: \(entity.confidence, specifier: "%.2f")")
                        .font(.caption)
                        .foregroundColor(.secondary)
                }
            }
        }
        .padding()
    }

    private func performExtraction() async {
        isLoading = true
        errorMessage = nil
        
        do {
            let modelDir = try await OpenMedModelStore.downloadMLXModel(
                repoID: "OpenMed/OpenMed-PII-ClinicalE5-Small-33M-v1-mlx"
            )
            let openmed = try OpenMed(backend: .mlx(modelDirectoryURL: modelDir))
            entities = try openmed.extractPII(text)
        } catch {
            errorMessage = error.localizedDescription
        }
        
        isLoading = false
    }
}

```

The `extractPII` method returns an array of `EntityPrediction` objects, each containing the recognized text span, entity label, and confidence score. For general NER tasks beyond PII, use the `analyzeText(_:confidenceThreshold:)` method available in the same `OpenMed` class.

## Summary

- **OpenMedKit** enables on-device clinical NLP in iOS apps without network dependencies, implemented in the `maziyarpanahi/openmed` repository.
- **Add the dependency** via Swift Package Manager using the URL `https://github.com/maziyarpanahi/openmed`.
- **Choose a backend**: Use `.mlx` with `OpenMedModelStore.downloadMLXModel()` for Apple Silicon devices, or `.coreML` with bundled `.mlmodelc` files for simulator compatibility.
- **Initialize** the `OpenMed` class with your selected backend configuration from [`OpenMedBackend.swift`](https://github.com/maziyarpanahi/openmed/blob/main/OpenMedBackend.swift).
- **Call extraction methods** (`extractPII` or `analyzeText`) to receive `[EntityPrediction]` arrays containing recognized entities and confidence scores.
- **Reference implementation** is available in [`swift/OpenMedScanDemo/OpenMedScanDemo/OpenMedScanDemo/ContentView.swift`](https://github.com/maziyarpanahi/openmed/blob/main/swift/OpenMedScanDemo/OpenMedScanDemo/OpenMedScanDemo/ContentView.swift).

## Frequently Asked Questions

### What is the difference between MLX and CoreML backends in OpenMedKit?

The **MLX backend** downloads and runs Hugging Face MLX artifacts with Apple Silicon GPU acceleration, providing optimal performance on physical iPhone and iPad devices. The **CoreML backend** uses pre-compiled `.mlmodelc` bundles shipped with your app, which is required for running on the iOS simulator and works on all device types. According to [`swift/OpenMedKit/Sources/OpenMedKit/OpenMedBackend.swift`](https://github.com/maziyarpanahi/openmed/blob/main/swift/OpenMedKit/Sources/OpenMedKit/OpenMedBackend.swift), the MLX backend is recommended for production deployment on real devices, while CoreML offers broader compatibility during development.

### How do I download MLX models for OpenMedKit?

Use the `OpenMedModelStore.downloadMLXModel(repoID:)` asynchronous method defined in [`swift/OpenMedKit/Sources/OpenMedKit/OpenMedModelStore.swift`](https://github.com/maziyarpanahi/openmed/blob/main/swift/OpenMedKit/Sources/OpenMedKit/OpenMedModelStore.swift). This function automatically handles downloading from the Hugging Face Hub, caching the artifacts locally, and returning a `URL` pointing to the model directory. You must await this call before initializing the `OpenMed` class with the `.mlx` backend.

### Can OpenMedKit run on the iOS simulator?

Yes, but only when using the **CoreML backend**. The MLX backend requires Apple Silicon hardware and will not function on the iOS simulator. To test on the simulator, bundle a CoreML model (`.mlmodelc`) and JSON label file with your app, then initialize `OpenMed` using `.coreML(modelURL:id2labelURL:tokenizerName:)` as shown in [`swift/OpenMedKit/Sources/OpenMedKit/OpenMedKit.swift`](https://github.com/maziyarpanahi/openmed/blob/main/swift/OpenMedKit/Sources/OpenMedKit/OpenMedKit.swift).

### What file formats does OpenMedKit require for CoreML integration?

CoreML integration requires two files: a compiled `.mlmodelc` (or `.mlpackage`) containing the model weights, and an [`id2label.json`](https://github.com/maziyarpanahi/openmed/blob/main/id2label.json) file mapping numeric indices to entity labels (e.g., "PER" for person, "SSN" for social security numbers). The tokenizer name parameter should reference the Hugging Face tokenizer identifier used during model conversion. Both files must be included in your app bundle and referenced via `Bundle.main.url`.