Refresh README for current MLX and OpenMedKit instructions

README.md

@@ -16,90 +16,90 @@ tags:
 
 # OpenMed-PII-SuperClinical-Base-184M-v1 for OpenMed MLX
 
-This repository contains a **private MLX packaging** of [`OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1`](https://huggingface.co/OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1) for Apple Silicon inference with [**OpenMed**](https://github.com/maziyarpanahi/openmed).
+This repository contains an MLX packaging of [`OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1`](https://huggingface.co/OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1) for Apple Silicon inference with [OpenMed](https://github.com/maziyarpanahi/openmed).
 
-[OpenMed](https://github.com/maziyarpanahi/openmed) is the main product experience:
+## At a Glance
 
-- Install the Python package with `pip install openmed`
-- Enable Apple Silicon acceleration with `pip install "openmed[mlx]"`
-- Run the same OpenMed API you already use, now backed by MLX on macOS
-- For Apple apps, use **OpenMedKit** from the same GitHub repository with a CoreML bundle
+- **Source checkpoint:** [`OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1`](https://huggingface.co/OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1)
+- **Model family:** `deberta-v2` (`DebertaV2ForTokenClassification`)
+- **Primary language hint:** English (`en`)
+- **Artifact layout:** legacy-compatible MLX (`config.json`, `id2label.json`, MLX weight files)
+- **Python MLX:** supported through `openmed[mlx]` on Apple Silicon Macs
+- **Swift MLX:** not yet in the current OpenMedKit Swift MLX v1 rollout for `deberta-v2` models
 
-This MLX repo is meant to pair with:
+## Python Quick Start
 
-- OpenMed GitHub: [https://github.com/maziyarpanahi/openmed](https://github.com/maziyarpanahi/openmed)
-- OpenMed website: [https://openmed.life](https://openmed.life)
-- Source checkpoint: [`OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1`](https://huggingface.co/OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1)
-
-## Quick Start
-
-### Python
+Use the standard OpenMed API if you want OpenMed to choose the right runtime automatically:
 
 ```bash
-pip install openmed
 pip install "openmed[mlx]"
 ```
 
 ```python
-from openmed import analyze_text
-from openmed.core.config import OpenMedConfig
+from openmed import extract_pii
 
-result = analyze_text(
-    "Patient John Doe, DOB 1990-05-15, SSN 123-45-6789",
+text = "<your clinical note here>"
+result = extract_pii(
+    text,
     model_name="OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1",
-    config=OpenMedConfig(backend="mlx"),
+    use_smart_merging=True,
 )
 
 for entity in result.entities:
     print(entity.label, entity.text, round(entity.confidence, 4))
 ```
 
-You can use the source model ID directly through OpenMed, or download this private MLX packaging from [`OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1-mlx`](https://huggingface.co/OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1-mlx) for a preconverted path.
+On Apple Silicon, OpenMed auto-selects MLX when `openmed[mlx]` is installed. On other systems it falls back to the Hugging Face / PyTorch backend.
 
-### Swift
+## Use This Preconverted MLX Repo Directly
 
-Use Swift with **OpenMedKit**, not with MLX weight files directly.
+If you want to use this MLX snapshot explicitly, download it locally and point OpenMed at the directory:
 
-1. Open Xcode and go to **File > Add Package Dependencies...**
-2. Paste the OpenMed repository URL:
-   `https://github.com/maziyarpanahi/openmed`
-3. Choose the package product **OpenMedKit** from the repository.
-4. Add a compatible CoreML model bundle plus `id2label.json` to your app target.
+```bash
+pip install "openmed[mlx]"
+hf download OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1-mlx --local-dir ./OpenMed-PII-SuperClinical-Base-184M-v1-mlx
+```
 
-After that, import OpenMedKit in Swift:
+If this repo is still private in your environment, authenticate first with `hf auth login` or set `HF_TOKEN`.
 
-```swift
-import OpenMedKit
+```python
+from openmed import extract_pii
+from openmed.core import OpenMedConfig
+
+text = "<your clinical note here>"
+result = extract_pii(
+    text,
+    model_name="./OpenMed-PII-SuperClinical-Base-184M-v1-mlx",
+    config=OpenMedConfig(backend="mlx"),
+    use_smart_merging=True,
+)
+
+print(result.entities)
 ```
 
-Then load your bundled CoreML model and label map:
+## Swift Status
 
-```swift
-import Foundation
-import OpenMedKit
+This repo is based on `deberta-v2`. Python MLX supports this family today, but the current public Swift MLX rollout in OpenMedKit is intentionally limited to `bert`, `distilbert`, `roberta`, `xlm-roberta`, and `electra`.
 
-let modelFolder = Bundle.main.resourceURL!
-let modelURL = modelFolder.appendingPathComponent("OpenMedPII.mlmodelc")
-let labelsURL = modelFolder.appendingPathComponent("id2label.json")
+If you are building an Apple app today, the recommended paths for this model are:
 
-let openmed = try OpenMed(
-    modelURL: modelURL,
-    id2labelURL: labelsURL
-)
-```
+- **Python MLX** for evaluation or local workflows on Apple Silicon
+- **CoreML in OpenMedKit** if you already have a compatible bundled Apple export
+- Track the current Swift support matrix in the [OpenMedKit docs](https://openmed.life/docs/swift-openmedkit/)
 
-This private MLX artifact remains the right choice for:
+## Artifact Notes
 
-- Python services on Apple Silicon
-- local MLX inference on macOS
-- private preconverted packaging on the Hub
+This repo uses the current legacy-compatible MLX layout:
 
-If a given architecture or environment cannot be exported cleanly as `safetensors`, OpenMed falls back to `weights.npz` so the model remains usable.
+- `config.json`
+- `id2label.json`
+- MLX weight files (`weights.safetensors` and/or `weights.npz`)
 
-## Credits
+Tokenizer assets are not bundled in this repo layout. OpenMed and OpenMedKit keep backward compatibility by falling back to the source tokenizer reference in `config.json` when needed.
 
-- Base checkpoint: [`OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1`](https://huggingface.co/OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1)
+## Links
+
+- Source checkpoint: [`OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1`](https://huggingface.co/OpenMed/OpenMed-PII-SuperClinical-Base-184M-v1)
 - OpenMed GitHub: [https://github.com/maziyarpanahi/openmed](https://github.com/maziyarpanahi/openmed)
-- OpenMed website: [https://openmed.life](https://openmed.life)
-- MLX packaging and runtime support: [**OpenMed**](https://github.com/maziyarpanahi/openmed)
-- Swift runtime for Apple apps: **OpenMedKit** from the OpenMed repository
+- MLX backend docs: [https://openmed.life/docs/mlx-backend/](https://openmed.life/docs/mlx-backend/)
+- OpenMedKit docs: [https://openmed.life/docs/swift-openmedkit/](https://openmed.life/docs/swift-openmedkit/)