How to Integrate OpenMed with Other Systems: 5 Integration Patterns Explained

OpenMed supports five distinct integration patterns: an in-process Python library, a FastAPI REST service, an MCP RPC server, a native Swift framework (OpenMedKit), and an MLX backend for Apple silicon acceleration, all sharing the same configuration system and model artifacts.

OpenMed is a local-first, modular NLP engine designed for healthcare text analysis and PII extraction. As implemented in maziyarpanahi/openmed, the codebase provides multiple integration surfaces that allow you to embed clinical NLP capabilities into Python scripts, microservices, mobile apps, or enterprise RPC systems without external API dependencies.

Python Library Integration

Use the direct Python API for batch pipelines, Jupyter notebooks, or custom scripts where function calls are preferred over network requests.

Configuration and Model Loading

The public API resides in openmed/__init__.py, exposing analyze_text, extract_pii, and deidentify. Configuration is centralized in openmed/core/config.py through the OpenMedConfig class, which supports profiles and environment variable overrides.

from openmed import analyze_text, extract_pii, OpenMedConfig

# Use the "prod" profile and force the MLX backend on Apple silicon

cfg = OpenMedConfig.from_profile("prod", backend="mlx")

result = analyze_text(
    "Patient received 75 mg clopidogrel for NSTEMI.",
    model_name="disease_detection_superclinical",
    config=cfg,
    sentence_detection=True,
)

print(result.entities)  # → list of extracted entities

Batch Processing with Keep-Alive

For high-throughput scenarios, use BatchProcessor (also exposed in openmed/__init__.py) while leveraging the keep-alive mechanism managed by ServiceRuntime in openmed/service/runtime.py.

from openmed import BatchProcessor, OpenMedConfig

cfg = OpenMedConfig.from_profile("prod")
batch = BatchProcessor(
    model_name="disease_detection_superclinical",
    keep_alive="10m",  # keep model in memory for 10 minutes after each request

    config=cfg,
)

texts = [
    "Patient received clopidogrel.",
    "Diagnosed with chronic myeloid leukemia.",
]
results = batch.process_texts(texts)
for r in results:
    print(r.entities)

REST API Service

For language-agnostic clients or microservice architectures, deploy the FastAPI application defined in openmed/service/app.py.

Starting the FastAPI Server

The create_app function builds the application, while ServiceRuntime handles model caching and pre-loading via the OPENMED_SERVICE_PRELOAD_MODELS environment variable.

# Start the service (requires the "service" extra)

pip install "openmed[hf,service]"   # installs FastAPI, uvicorn, etc.

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

Endpoint Examples

The service exposes /analyze, /pii/extract, /pii/deidentify, /models/loaded, /models/unload, and /health. Results are converted to JSON via _result_to_dict before returning.

Analyze text with entity grouping:

curl -X POST http://localhost:8080/analyze \
  -H "Content-Type: application/json" \
  -d '{
        "text": "Patient: John Doe, DOB: 01/15/1970, SSN: 123-45-6789",
        "model_name": "pii_superclinical_large",
        "confidence_threshold": 0.5,
        "group_entities": true,
        "keep_alive": "5m"
      }'

Extract PII in Portuguese:

curl -X POST http://localhost:8080/pii/extract \
  -H "Content-Type: application/json" \
  -d '{"text":"Paciente: Pedro Almeida, CPF: 123.456.789-09", "model_name":"pii_superclinical_large", "lang":"pt"}'

MCP Server for Enterprise RPC

The openmed/mcp/server.py module provides a Model-Control-Protocol wrapper around the service runtime. This exposes functions like openmed_analyze_text and openmed_extract_pii as JSON-RPC methods that any language can invoke over HTTP.

from openmed.mcp.server import openmed_analyze_text

# Direct function call – under the hood it uses the same ServiceRuntime

resp = openmed_analyze_text(
    text="Patient started on imatinib for chronic myeloid leukemia.",
    model_name="disease_detection_superclinical",
    confidence_threshold=0.6,
    keep_alive="2m",
)

print(resp)   # JSON-serialisable dict

Swift and iOS Integration (OpenMedKit)

For native iOS and macOS applications, use the OpenMedKit Swift package located in swift/OpenMedKit/. The Swift SDK mirrors the Python API, offering analyzeText and extractPII methods that run on-device using CoreML or MLX artifacts generated by openmed/coreml/convert.py.

Add the dependency to your Package.swift:

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

Implement on-device analysis:

import OpenMedKit

let text = "Patient: John Doe, DOB: 01/15/1970, SSN: 123‑45‑6789"
OpenMed.shared.analyze(text: text,
                       modelName: "pii_superclinical_large",
                       confidenceThreshold: 0.5) { result in
    switch result {
    case .success(let entities):
        print("Detected entities:", entities)
    case .failure(let error):
        print("Error:", error)
    }
}

MLX Backend for Apple Silicon

When backend="mlx" is set in OpenMedConfig, the library automatically routes inference to the Apple MLX runtime via modules in openmed/mlx/ (specifically inference.py and convert.py), delivering 20-30× speed-ups on M-series chips.

from openmed.core.config import OpenMedConfig

cfg = OpenMedConfig.from_profile("prod", backend="mlx")

Summary

• Use the Python library (openmed/__init__.py) for direct integration in Python scripts and batch processing via BatchProcessor.
• Deploy the FastAPI service (openmed/service/app.py) to expose REST endpoints (/analyze, /pii/extract) for language-agnostic clients; models are cached via ServiceRuntime in openmed/service/runtime.py.
• Implement the MCP server (openmed/mcp/server.py) for enterprise RPC scenarios requiring JSON-RPC interfaces like openmed_analyze_text.
• Integrate OpenMedKit (swift/OpenMedKit/Package.swift) for on-device inference in iOS and macOS applications without Python dependencies.
• Enable the MLX backend (openmed/mlx/) to achieve 20-30× performance improvements on Apple silicon by setting backend="mlx" in OpenMedConfig.

Frequently Asked Questions

How do I configure OpenMed to use the MLX backend on Apple Silicon?

Set the backend parameter to "mlx" when creating your configuration. In openmed/core/config.py, the OpenMedConfig class accepts this parameter and routes inference through the MLX runtime modules in openmed/mlx/, automatically converting models if necessary.

What is the difference between the REST service and the MCP server?

The REST service (openmed/service/app.py) provides standard HTTP endpoints for direct HTTP clients, while the MCP server (openmed/mcp/server.py) wraps the same functionality in a JSON-RPC layer suitable for enterprise integration patterns. Both use the shared ServiceRuntime in openmed/service/runtime.py for model caching and keep-alive management.

How does model keep-alive work in OpenMed services?

The ServiceRuntime class in openmed/service/runtime.py implements keep-alive timers that unload idle models after a configurable period. When making requests via the REST API or Python library, pass the keep_alive parameter (e.g., "5m" or "10m") to keep models resident in memory between requests, reducing cold-start latency.

Can I use OpenMed in a mobile app without an internet connection?

Yes. The OpenMedKit Swift package (swift/OpenMedKit/) bundles MLX or CoreML model artifacts and runs inference natively on Apple devices. This enables offline, on-device clinical NLP without requiring a Python runtime or network connectivity.

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