pytholove/compact-rcgf-3-class

MM-RetFund Compact: three-class research model

Start here for the size-first compact release. This private model combines 1–20 fundus photographs and nine clinical factors to predict Normal, DM, or DM_CKD (including the advanced DM_CKD_V group). It is not the separate binary six-feature model.

Research only. Not a medical device; do not use for diagnosis, screening, treatment, or patient-care decisions. No external validation or regulatory clearance is reported.

Choose a format

Format	Files	Model size	Start here when
PyTorch FP32	fp32/	117.24 MB	You want a CPU-compatible starting point
PyTorch FP16	fp16/	58.63 MB	You have a GPU supporting FP16
PyTorch BF16	bf16/	58.63 MB	Your device and PyTorch support BF16
LiteRT INT8	litert/int8/	30.46 MB	You want the smallest bundle; CPU interpreter tested
LiteRT FP16	litert/fp16/	59.16 MB	You want FP16 weights with FP32 activations
ONNX / OpenVINO FP32	onnx/, openvino/	about 117 MB each	You use another inference runtime

Sizes refer to model files, not dependencies or memory. LiteRT INT8 uses dynamic INT8 weights and FP32 input/output. The bundled LiteRT backend was tested on CPU; Android/iOS delegates and other devices need target-specific validation. TensorRT engines are hardware/software-specific, not portable defaults.

For a larger accuracy reference, the private three-seed ensemble uses three backbones (175.89 MB FP16). The big quantized RCGF is a separate, larger model. This compact model is the size-first choice, not a claim that its single seed has the best accuracy.

Install and predict

Ask the owner for access to this private Hugging Face repository. You do not need the research codebase. Use Python 3.10 or newer in a fresh virtual environment:

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install -U huggingface_hub
hf auth login
hf download pytholove/compact-rcgf-3-class \
  compact_rcgf_runtime-0.1.0-py3-none-any.whl requirements-torch.txt \
  --local-dir compact-download
cd compact-download
python -m pip install -r requirements-torch.txt

The requirements file installs the local wheel and its declared dependencies: numpy, Pillow, huggingface-hub, torch, torchvision, transformers, and safetensors. Dependencies are resolved by pip, not locked; use a compatible PyTorch build for your device. The wheel contains inference code, not weights. Weights download on first load using your Hugging Face credentials.

For LiteRT INT8 instead, download requirements-litert.txt alongside the same wheel and run python -m pip install -r requirements-litert.txt from compact-download. It installs ai-edge-litert plus the shared dependencies. In the example below change the loader options to backend='litert', precision='int8', device='cpu'.

The example uses synthetic inputs to check installation, not patient data:

from PIL import Image
from compact_rcgf import CompactRCGF

model = CompactRCGF.from_pretrained(
    'pytholove/compact-rcgf-3-class',
    backend='torch', precision='fp32', device='cpu',
)
factors = {
    'age': 58.0, 'sex': 0.0, 'bmi': 25.76, 'waist_circ': 93.72,
    'sbp': 137.29, 'dbp': 80.46, 'hba1c': 7.18,
    'fasting_glucose': 131.21, 'postprandial_glucose': 202.33,
}
image = Image.new('RGB', (672, 672), (128, 128, 128))
result = model.predict([image], factors)
print(result['label'], result['probabilities'])

Replace the synthetic image and factors with appropriate research inputs. The synthetic example is only an installation check: PyTorch FP32 and LiteRT INT8 produced different labels for this artificial image. predict also accepts image file paths and returns class_order and model_version. For reproducibility, pass revision='<Hub commit SHA>' to from_pretrained.

LiteRT and other devices

Install the corresponding extra instead of [torch] and use the same predict call:

Extra	Explicit loading options
[litert]	backend='litert', precision='int8', device='cpu'
[litert]	backend='litert', precision='fp16', device='cpu'
[torch]	backend='torch', precision='fp16', device='cuda'
[torch]	backend='torch', precision='bf16', device='cpu' on a BF16-capable device
[onnx]	backend='onnx', precision='fp32', device='cpu'
[openvino]	backend='openvino', precision='fp32', device='cpu'

The loader defaults to ONNX FP32, so specify the backend and precision explicitly. Hardware and dependency support varies; a file existing does not establish that it runs on every device.

Inference speed

Median time per patient in milliseconds, including preprocessing and prediction for one or four images per patient, not four classes. Linux x86-64, Intel Core i9-12900H CPU or NVIDIA RTX 3070 Ti Laptop GPU (8 GB); four CPU threads. Each cell uses three warmups and 15 timed calls with a synthetic in-memory 672×672 RGB PIL image; model loading, download, disk I/O and concurrent requests are excluded. Times are indicative, not clinical or device guarantees.

Format	Device	1 image (ms)	4 images (ms)
LiteRT INT8	CPU	242	994
LiteRT FP16	CPU	591	2367
PyTorch FP32	CPU	461	2215
PyTorch BF16	CPU	4466	16501
ONNX FP32	CPU	506	1895
OpenVINO FP32	CPU	455	1880
PyTorch FP32	GPU	38	162
PyTorch FP16	GPU	32	121
PyTorch BF16	GPU	31	121

BF16 was especially slow on this CPU; smaller weights do not guarantee faster inference. GPU and CPU used different PyTorch versions. Results depend on hardware, input dimensions, image counts, runtime and load. Raw measurements, including p95 and software versions, are in benchmarks/published_runtime.json; benchmarks/benchmark_published.py reproduces the protocol.

Input contract

• Supply 1–20 RGB image paths or PIL images for one patient. The runtime resizes the shorter side to 768, center-crops to 672, normalizes with ImageNet statistics and applies release-evaluation FP16 rounding.
• Supply exactly the nine factor keys in the example. None or NaN is imputed with the training mean; config.json contains factor order and normalization parameters. Confirm units and sex encoding against the study data dictionary; do not infer them from example values.
• Output probabilities sum to one in class order Normal, DM, DM_CKD; these are not calibrated clinical risk estimates.
• Direct LiteRT integrations require matching preprocessing, [1, 3, 672, 672] vision input and head inputs [1, 20, 768] embeddings, [1, 9] factors and [1] image count. Zero-pad shorter bags; the Python runtime handles this.

Evidence and limitations

The released checkpoint is S3 fold 0, seed 42. Its fold-0 canary contains 66 patients. Three-fold pooled OOF figures are from fold-specific models, not a test of this one file on all 196 patients.

Internal evaluation	Patients	Macro-F1	Macro-AUC
Seed 42 pooled OOF	196	0.7732	0.9262
Three-seed recipe mean pooled OOF	196	0.7934	0.9283
Three-seed ensemble pooled OOF	196	0.7931	0.9314
Released fold-0 seed-42 canary	66	0.7848	0.9169

The seed 42/43/44 pooled F1 values are 0.7732 / 0.8332 / 0.7737; do not quote the three-seed recipe mean as this checkpoint's score. On the same internal canary, historical LiteRT INT8 testing reported 100% argmax agreement and F1/AUC 0.7848/0.9217, with maximum absolute probability difference 0.10579. This is not proof of equivalence on other patients or hardware. No held-out n=43 scoring or external validation is reported. FP32 SafeTensors were upcast from FP16 exports, not independently saved original FP32 training weights.

The student uses a frozen DINOv3 ConvNeXt-Tiny vision backbone and a TabM clinical/fusion head, trained with nested-OOF TabICL feature distillation and cross-cohort big-RCGF logit distillation. See the detailed model card, eval/, benchmarks/, and checksums.sha256 for lineage and format evidence.

Licenses and upstream terms

This research release uses a DINOv3 backbone and was distilled using a RETFound-based teacher. Review both upstream terms before use or redistribution:

• DINOv3: DINOv3 model card and license.
• RETFound: RETFound model card and Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0).

CC BY-NC 4.0 requires attribution and restricts commercial use of licensed material. The exact applicability of upstream terms to this distilled release and your intended use requires review; this card does not grant rights beyond those held by the respective licensors.