Upload README.md with huggingface_hub

README.md

@@ -1,5 +1,6 @@
 ---
 license: apache-2.0
+library_name: onnx
 pipeline_tag: image-classification
 tags:
   - medical-imaging
@@ -116,7 +117,143 @@ whether an image is worth processing at all is satisfied by `family`.
 * Scores are calibrated. Read the measured precision and
   recall above, not the score, when choosing a policy.
 
-## Usage
+## Quick start (Python + onnxruntime)
+
+No clone, no framework - the artifact and its config files are all you need.
+
+```bash
+pip install onnxruntime pillow numpy huggingface_hub
+```
+
+```python
+import json, numpy as np, onnxruntime as ort
+from PIL import Image
+from huggingface_hub import hf_hub_download
+
+REPO = "vectorsense/modalityscan"
+sess = ort.InferenceSession(hf_hub_download(REPO, "model.int8.onnx"),
+                            providers=["CPUExecutionProvider"])
+tax  = json.load(open(hf_hub_download(REPO, "modality-taxonomy.json"), encoding="utf-8"))
+book = json.load(open(hf_hub_download(REPO, "modality-thresholds.json"), encoding="utf-8"))
+pre  = json.load(open(hf_hub_download(REPO, "preprocessor.json"), encoding="utf-8"))
+
+MODALITY = tax["levels"]["modality"]["index"]
+FAMILY   = tax["levels"]["family"]["index"]
+TIER     = {label: tier
+            for tier in ("model_trained", "experimental", "not_trained")
+            for label in tax["tiers"][tier]["types"]}
+
+mean = np.array(pre["image_mean"], np.float32)[:, None, None]
+std  = np.array(pre["image_std"],  np.float32)[:, None, None]
+
+def pixel_values(path, size=224):
+    # Letterbox, never centre-crop. The field-of-view outline - ultrasound sector, circular
+    # fundus aperture, endoscope vignette - is a top-tier modality cue; cropping discards it.
+    image = Image.open(path).convert("RGB")
+    scale = size / max(image.size)
+    small = image.resize((max(1, round(image.width * scale)),
+                          max(1, round(image.height * scale))), Image.BILINEAR)
+    canvas = Image.new("RGB", (size, size), (0, 0, 0))
+    canvas.paste(small, ((size - small.width) // 2, (size - small.height) // 2))
+    array = np.asarray(canvas, np.float32) / 255.0
+    return ((array.transpose(2, 0, 1) - mean) / std)[None]
+
+def softmax(x):
+    e = np.exp(x - x.max())
+    return e / e.sum()
+
+family_logits, modality_logits = sess.run(
+    ["family_logits", "modality_logits"], {"pixel_values": pixel_values("frame.png")}
+)
+
+# Temperature lives outside the graph so calibration stays configuration, not a re-export.
+T = book["calibration"]["temperature"]
+p_mod = softmax(modality_logits[0] / T["modality"])
+p_fam = softmax(family_logits[0] / T["family"])
+
+policy = book["default_policy"]
+floor  = book["policies"][policy]["modality"]
+over   = book["per_class_overrides"].get(policy, {})
+
+# Energy over logits, not softmax: softmax is confident on garbage by construction.
+energy = -float(np.log(np.exp(modality_logits[0] / T["modality"]).sum()))
+if energy > book["ood"]["energy_threshold"][policy]:
+    print("out of distribution ->", book["ood"]["fallback_label"])
+else:
+    # `not_trained` classes keep their slot because the output width is a published contract,
+    # but they are not claims. A raw argmax will eventually return one of them.
+    best = next(i for i in np.argsort(-p_mod) if TIER.get(MODALITY[i]) != "not_trained")
+    label, score = MODALITY[best], float(p_mod[best])
+    if score >= over.get(label, floor):
+        print(f"modality: {label} {score:.3f}  tier={TIER[label]}")
+    else:
+        print(f"family:   {FAMILY[int(p_fam.argmax())]} {p_fam.max():.3f}  (cascade fell back)")
+```
+
+Two lines carry most of the correctness. **Letterbox rather than centre-crop** - the field-of-view
+outline is signal, not padding. **Skip `not_trained` classes** - a raw `argmax` will eventually
+hand you a label this model does not stand behind.
+
+## Run it as a REST API
+
+The companion repo ships a FastAPI service with the cascade, the calibrated thresholds, the
+energy rejection and series aggregation already wired up.
+
+```bash
+pip install fastapi "uvicorn[standard]" onnxruntime pillow numpy
+uvicorn service.app:app --port 5003      # auto-loads model.int8.onnx from ./models
+```
+
+```bash
+curl -s http://127.0.0.1:5003/classify_modality \
+  -H "Content-Type: application/json" \
+  -d '{"frames":[{"id":"series-1/f000","image_base64":"iVBORw0KGgo..."}],
+       "options":{"policy":"balanced"}}'
+```
+
+The same call from Python - send a PNG or JPEG, get parsed JSON back:
+
+```python
+import base64, requests
+
+URL = "http://127.0.0.1:5003/classify_modality"
+
+def classify(path, policy="balanced"):
+    payload = {
+        "frames": [{"id": "series-1/f000",
+                    "image_base64": base64.b64encode(open(path, "rb").read()).decode()}],
+        "options": {"policy": policy, "top_k": 3},
+    }
+    response = requests.post(URL, json=payload, timeout=30)
+    response.raise_for_status()     # unknown request fields return 422, never a silent default
+    return response.json()
+
+frame = classify("frame.png")["results"][0]
+print(frame["modality"]["label"], frame["modality"]["granularity"], frame["modality"]["score"])
+print("out of distribution:", frame["out_of_distribution"])
+```
+
+A whole DICOM series in one request, which is the cheapest accuracy in the serving path:
+
+```python
+payload = {
+    "frames": [{"id": f"series-1/f{i:03d}",
+                "image_base64": base64.b64encode(open(p, "rb").read()).decode()}
+               for i, p in enumerate(frame_paths)],
+    "options": {"policy": "balanced", "aggregate_by": "series"},
+}
+print(requests.post(URL, json=payload, timeout=60).json()["aggregate"])
+```
+
+Endpoints: `GET /`, `POST /classify_modality`, `GET /health/ready`, `GET /metadata`.
+`GET /metadata` reports the tier of every class at runtime, so a caller can tell a claimed class
+from an experimental one without reading this card.
+
+Prefer the service over the raw-ONNX snippet unless you have a reason not to: it already applies
+the calibrated temperature, the per-class thresholds, the abstention cascade and the rejection
+path. The snippet reimplements those in miniature and will drift from the config.
+
+## Usage via the library
 
 ```python
 from modalityscan import ModalityClassifier