Integrating OpenMedKit Swift Library in iOS Applications: Complete Setup Guide

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, and calling the high-level API defined in 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 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 dependencies, referencing the package manifest located at swift/OpenMedKit/Package.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. 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. The downloadMLXModel(repoID:) function handles caching and local storage automatically.

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 mapping file with your app. This approach works on both physical devices and the iOS simulator.

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. This example uses the MLX backend with asynchronous model downloading:

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.
• 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.

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, 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. 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.

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 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.

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