Lean README: three-task framing (class + medical + handwritten), remove quality head docs

README.md

@@ -9,45 +9,29 @@ tags:
 library_name: transformers
 ---
 
-# Hierarchical SigLIP2 Document Classifier (~97M)
+# Eka Doc Classifier (~96M)
 
-A **frozen SigLIP2 base** vision tower (`google/siglip2-base-patch16-naflex`, single
-high-res forward at `max_num_patches=1024`) plus lightweight heads that classify a
-document image across several tasks from one shared pooled embedding:
+A compact vision model for classifying health-app uploads — prescriptions shot at an angle, X-rays, Aadhaar cards, discharge summaries, the occasional accidental selfie. A frozen **SigLIP2-base** tower (`google/siglip2-base-patch16-naflex`) with lightweight heads answers three questions about an image in a single pass:
 
-| Task | Output |
-|------|--------|
-| `l2` (flat, **default**) | leaf class — flat 27-way head; **L1 inferred** from it |
-| `l1` | document group — one of 5 (Document, Miscellaneous, Diagnostic imaging, Card / credential, Body images) |
-| `l2` (leaf) | leaf class via a per-L1 head, when the group is fixed/predicted |
-| `medical` | sigmoid — `medical` / `non_medical` (+ `p_positive`) |
-| `handwritten` | sigmoid — `handwritten` / `printed` (+ `p_positive`); tuned on documents |
-| `quality` | sigmoid — a single **`score` in 1–100** (P(good) mapped onto 1–100; higher = better), no label |
+- **What it is** — a two-level label: 5 groups (L1) → 27 leaf classes (L2)
+- **Is it medical?** — binary head
+- **Is it handwritten?** — binary head
 
-## L2 has two paths, selected by `scope`
+The model was built by training many specialised models, ensembling them, and distilling the ensemble into this one compact student.
 
-There is **both** a flat 27-way L2 head (the backbone's own end-to-end classifier,
-run on the raw pooled feature) **and** a per-L1 leaf head per group (run on the
-standardized embedding). You choose how L2 / L1 are produced:
+## Results
 
-| `scope` | what runs | L1 | L2 |
-|---------|-----------|----|----|
-| `"flat"` *(default)* | flat 27-way head | **inferred** from the L2 prediction | flat |
-| `"l1"` | L1 group head only | predicted | — (not produced) |
-| `"hierarchical"` | L1 head → that group's leaf head | predicted | leaf |
+Full internal test = 16,204 images (see `benchmark_results.json`).
 
-**Fix the group yourself** by passing `l1="Document"` (any group name): L2 is then
-read from that group's leaf head, overriding the scope's routing.
+| Precision | Size | Accuracy (27-class) | Macro-F1 |
+|-----------|------|---------------------|----------|
+| bf16 | 193 MB | 96.45 | 0.965 |
+| int8 | 103 MB | 96.43 | 0.965 |
+| int4 | 60 MB | 95.22 | 0.955 |
 
-```
-image → frozen SigLIP2 tower → pooled embedding ──► flat L2 head ─► L2 (+ inferred L1)   [scope="flat"]
-                                     │
-                                     ├─ standardize (mu/sd) → L1 head ─► L1               [scope="l1"]
-                                     │                          └─► leaf L2 head[L1] ─► L2 [scope="hierarchical" / fixed l1]
-                                     └─ medical · handwritten · quality  (sigmoid heads, independent)
-```
+int8 is effectively lossless; int4 trades about a point of accuracy for a model over 3× smaller that runs comfortably on a plain CPU. It matches or beats models several times its size, including a 428M SigLIP2-SO400M variant (96.24%) and a 256M generative VLM baseline (90.42%).
 
-### Taxonomy (5 L1 groups → 27 L2 leaves)
+## Taxonomy (5 L1 groups → 27 L2 leaves)
 
 ```
 Document  (10 leaves)
@@ -61,27 +45,27 @@ Document  (10 leaves)
     ├─ Form                   (key: form)
     ├─ Invoice / bill         (key: invoice_bill)
     ├─ Certificate            (key: certificate)
-Miscellaneous  (2 leaves)
-    ├─ Other (Miscellaneous)  (key: other_miscellaneous)
-    ├─ Medication image       (key: medication_image)
-Diagnostic imaging  (5 leaves)
-    ├─ Ultrasound             (key: ultrasound)
-    ├─ X-ray                  (key: x_ray)
-    ├─ MRI                    (key: mri)
-    ├─ CT                     (key: ct)
-    ├─ Other (Diagnostic imaging) (key: other_diagnostic_imaging)
 Card / credential  (7 leaves)
     ├─ ABHA card              (key: abha_card)
-    ├─ Voter ID               (key: voter_id)
     ├─ Aadhaar card           (key: aadhaar_card)
-    ├─ Insurance e-card       (key: insurance_e_card)
     ├─ PAN card               (key: pan_card)
+    ├─ Voter ID               (key: voter_id)
     ├─ PMJAY / Ayushman       (key: pmjay_ayushman)
+    ├─ Insurance e-card       (key: insurance_e_card)
     ├─ Other card             (key: other_card)
+Diagnostic imaging  (5 leaves)
+    ├─ X-ray                  (key: x_ray)
+    ├─ CT                     (key: ct)
+    ├─ MRI                    (key: mri)
+    ├─ Ultrasound             (key: ultrasound)
+    ├─ Other (Diagnostic imaging) (key: other_diagnostic_imaging)
 Body images  (3 leaves)
-    ├─ Headshot               (key: headshot)
     ├�� Skin / wound           (key: skin_wound)
+    ├─ Headshot               (key: headshot)
     ├─ Other (Body images)    (key: other_body_images)
+Miscellaneous  (2 leaves)
+    ├─ Medication image       (key: medication_image)
+    ├─ Other (Miscellaneous)  (key: other_miscellaneous)
 ```
 
 ## Usage
@@ -93,46 +77,34 @@ from PIL import Image
 model = AutoModel.from_pretrained("ekacare/med-doc-classifier", trust_remote_code=True).eval()
 img = Image.open("doc.jpg")
 
-model.classify(img)                       # default: flat L2 + inferred L1 + binaries
+model.classify(img)
 ```
 
 ```jsonc
-// example return value (scope="flat")
+// example return value
 {
   "l2":          { "source": "flat", "key": "lab_diagnostic_report",
                     "value": "Lab / diagnostic report", "confidence": 0.97 },
   "l1":          { "value": "Document", "source": "inferred_from_flat_l2" },
   "medical":     { "value": "medical", "confidence": 0.99, "p_positive": 0.99 },
-  "handwritten": { "value": "printed", "confidence": 0.98, "p_positive": 0.02 },
-  "quality":     { "score": 94, "p_good": 0.94 }
+  "handwritten": { "value": "printed", "confidence": 0.98, "p_positive": 0.02 }
 }
 ```
 
-### Choosing the L2 scope
+By default L2 comes from a flat 27-way head and L1 is inferred from it. Other options:
 
 ```python
-model.classify(img)                       # scope="flat" (default): flat L2, L1 inferred
 model.classify(img, scope="l1")           # L1 group only (no L2)
-model.classify(img, scope="hierarchical") # L1 head → leaf L2
-model.classify(img, l1="Document")         # FIX L1 = Document → that group's leaf L2
-model.classify(img, medical=False, handwritten=False, quality=False)  # L2/L1 only
-```
-
-`medical`, `handwritten`, `quality` are independent sigmoid heads — toggle them
-freely. `quality` reports a single **`score` in 1–100** (the sigmoid P(good) mapped
-onto the range; higher = better quality) plus the raw `p_good` — there is no
-poor/good label. `handwritten` is trained on document images.
-
-### Top-k
-
-```python
+model.classify(img, scope="hierarchical") # L1 head → that group's leaf L2 head
+model.classify(img, l1="Document")        # fix L1 → that group's leaf L2 head
 model.classify(img, top_k=3)              # top-3 candidates for the multi-class heads
 ```
 
+`medical` and `handwritten` are independent binary heads — disable them with `medical=False` / `handwritten=False`.
+
 ## Quantized loading (optimum-quanto — CPU & GPU)
 
-int8 **and int4** run on CPU as well as GPU. Only the vision tower is quantized;
-`patch_embedding` and the heads stay full precision.
+Only the vision tower is quantized; the heads stay full precision.
 
 ```python
 # pip install optimum-quanto
@@ -141,17 +113,3 @@ from modeling_siglip2_hier import load_classifier   # downloaded by trust_remote
 model = load_classifier("ekacare/med-doc-classifier", quantization="int4")  # None | "int8" | "int4"
 model.classify(img)
 ```
-
-Flat-L2 accuracy by precision (vision tower quantized; full internal test = 16,204
-images, external OOD = 953; see `benchmark_results.json`):
-
-| precision | internal acc / mF1 (cluster) | external acc / mF1 (cluster) |
-|-----------|------------------------------|------------------------------|
-| bf16 | 96.45 / 0.965 (97.36) | 80.90 / 0.702 (90.95) |
-| int8 | 96.43 / 0.965 (97.36) | 80.90 / 0.653 (91.15) |
-| int4 | 95.22 / 0.955 (94.23) | 77.23 / 0.630 (85.60) |
-
-**int8 is effectively lossless on accuracy** (internal −0.02, external acc identical;
-only the external macro-F1 dips as rare classes lose a little balance). **int4** trades
-~1.2pt internal / ~3.7pt external for the smallest footprint. Base weights ship in bf16
-(~193 MB); int8/int4 quantize the vision tower only (heads + `patch_embedding` stay fp).