Deploy FelineBCS Gradio Space

README.md

@@ -1,13 +1,54 @@
 ---
-title: Catbcs
-emoji: 🦀
-colorFrom: red
-colorTo: pink
+title: CatBCS
 sdk: gradio
-sdk_version: 6.19.0
-python_version: '3.13'
 app_file: app.py
-pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# CatBCS / FelineBCS Hugging Face Space
+
+This directory contains the minimal files needed to run the FelineBCS Gradio
+inference app as a Hugging Face Space. The public website should call this Space
+API; Vercel should not run the model.
+
+## Create the Space
+
+1. In Hugging Face, create a new Space named `catbcs`.
+2. Set the Space SDK to **Gradio**.
+3. Upload or copy these files into the root of the Space repository:
+   - `app.py`
+   - `felinebcs_predict.py`
+   - `requirements.txt`
+   - `README.md`
+4. Let Hugging Face install dependencies and launch `app.py`.
+
+## Model artifacts
+
+The trained heads are not committed to the GitHub source repository. Provide the
+model artifacts to the Space separately.
+
+Default expected layout:
+
+```text
+models/
+  clip_vitb32_regressor.joblib
+  clip_vitb32_clf9.joblib
+  clip_vitb32_clf4.joblib
+```
+
+If the files live somewhere else in the Space runtime, set:
+
+```text
+FELINEBCS_MODEL_DIR=/path/to/models
+```
+
+Do not hardcode local machine paths. If the artifacts are missing, the Space
+will still start and the app will show a clear "model artifacts unavailable"
+message when a prediction is requested.
+
+## Responsible use
+
+CatBCS / FelineBCS is a non-diagnostic research and triage aid. It was trained
+on weak, model-generated labels, not veterinary ground truth. It is not
+veterinary advice, diagnosis, or a substitute for a licensed veterinarian's
+hands-on examination.

app.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python
+"""FelineBCS — Gradio inference app.
+Upload a cat (or dog) photo -> Body Condition Score 1-9 + group + uncertainty flag.
+
+NON-DIAGNOSTIC. Educational tool built on weak (vision-LLM) labels. Not a substitute
+for veterinary examination.
+"""
+import gradio as gr
+
+# The model (frozen CLIP backbone + trained heads) is loaded lazily on first
+# prediction so this module can be imported without the model artifacts present
+# (e.g. in CI import smoke tests). It is warmed at launch in __main__ below.
+_MODEL = None
+
+
+def get_model():
+    global _MODEL
+    if _MODEL is None:
+        from felinebcs_predict import FelineBCS
+        _MODEL = FelineBCS()
+    return _MODEL
+
+
+def model_unavailable_message(exc):
+    return (
+        "## Model artifacts unavailable\n\n"
+        f"{exc}\n\n"
+        "For deployment, provide the trained head files in `./models/` or set "
+        "`FELINEBCS_MODEL_DIR` to the artifact directory. This app is still a "
+        "non-diagnostic research tool and is not veterinary advice."
+    )
+
+
+BCS_DESC = {
+    1: "Emaciated — ribs/spine/pelvis visible, no fat, severe waist tuck.",
+    2: "Very thin — bones easily felt, minimal fat.",
+    3: "Thin — ribs easily felt, obvious waist.",
+    4: "Lean — ribs palpable, slight waist, minimal fat pad.",
+    5: "Ideal — well-proportioned, ribs felt with light fat cover, visible waist.",
+    6: "Slightly overweight — ribs felt with difficulty, waist less obvious.",
+    7: "Overweight — ribs hard to feel, rounded abdomen, fat pad present.",
+    8: "Obese — ribs not palpable, no waist, prominent abdominal fat pad.",
+    9: "Severely obese — heavy fat deposits, distended abdomen.",
+}
+
+DISCLAIMER = """
+### ⚠️ Non-diagnostic educational tool
+- **Not veterinary advice.** Body condition scoring by a professional includes *palpation* (feeling ribs/fat), which no photo model can replicate.
+- Labels are **weak** — generated by a vision language model, not clinicians. Expect bias toward "ideal" (BCS 5) and errors on extremes.
+- Trained on a dataset that **mixes cats and dogs** and contains some **contaminated / off-distribution images** (puppies, non-cats, synthetic renders).
+- Best performance on **clear, side-on, full-body** photos of short-haired animals. Fluffy coats, occlusion, odd angles, and close-up faces degrade accuracy.
+- For any health concern, **consult a veterinarian.**
+"""
+
+def analyze(img):
+    if img is None:
+        return "Please upload an image.", {}, "", {}
+    try:
+        r = get_model().predict(img)
+    except Exception as exc:
+        return model_unavailable_message(exc), {}, "", {"error": str(exc)}
+    bcs = r["bcs"]; rd = r["bcs_rounded"]
+    # headline
+    head = f"## Estimated BCS: **{bcs} / 9**  →  {r['group']}\n\n*{BCS_DESC[rd]}*"
+    # quality / reject warning
+    warn = []
+    if r["reject"]:
+        warn.append(f"🚩 **Low-confidence prediction** (regressor–classifier disagreement "
+                    f"{r['disagreement']}, above reject threshold). The two model heads disagree "
+                    f"on this image — treat the score as unreliable. Try a clearer, side-on, "
+                    f"full-body photo.")
+    if r["tta_std"] > 0.6:
+        warn.append(f"⚠️ Prediction is unstable across image augmentations "
+                    f"(TTA std {r['tta_std']}). Interpret with caution.")
+    warn_md = "\n\n".join(warn) if warn else "✅ Model heads agree; prediction is within normal confidence."
+    # probability distribution over 1-9
+    probs = {f"BCS {k}": v for k, v in r["prob9"].items()}
+    detail = (f"- **Regressor:** {bcs}\n"
+              f"- **Classifier expected value:** {r['classifier_expected']}\n"
+              f"- **Group (from BCS):** {r['group']}\n"
+              f"- **4-way classifier:** {r['group_clf']} (confidence {r['group_clf_conf']:.0%}, "
+              f"{'agrees' if r['group_agree'] else 'disagrees'})\n"
+              f"- **Disagreement:** {r['disagreement']}  |  **TTA std:** {r['tta_std']}")
+    api_result = {
+        "bcs": r["bcs"],
+        "bcs_rounded": r["bcs_rounded"],
+        "group": r["group"],
+        "group_classifier": r["group_clf"],
+        "group_classifier_confidence": r["group_clf_conf"],
+        "group_agree": r["group_agree"],
+        "classifier_expected": r["classifier_expected"],
+        "tta_std": r["tta_std"],
+        "disagreement": r["disagreement"],
+        "reject": r["reject"],
+        "prob9": r["prob9"],
+    }
+    return head + "\n\n" + warn_md, probs, detail, api_result
+
+with gr.Blocks(title="FelineBCS") as demo:
+    gr.Markdown("# 🐾 FelineBCS — Cat/Dog Body Condition Score Estimator")
+    gr.Markdown("Upload a photo to estimate the 9-point Body Condition Score. "
+                "Best with a clear, side-on, full-body shot.")
+    with gr.Row():
+        with gr.Column():
+            inp = gr.Image(type="pil", label="Upload photo")
+            btn = gr.Button("Analyze", variant="primary")
+        with gr.Column():
+            out_head = gr.Markdown()
+            out_prob = gr.Label(label="Score distribution (9-way classifier)", num_top_classes=5)
+            out_detail = gr.Markdown()
+            out_api = gr.JSON(visible=False)
+    btn.click(analyze, inputs=inp, outputs=[out_head, out_prob, out_detail, out_api], api_name="analyze")
+    inp.change(analyze, inputs=inp, outputs=[out_head, out_prob, out_detail, out_api], api_name=False)
+    gr.Markdown(DISCLAIMER)
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860)

felinebcs_predict.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python
+"""FelineBCS inference: frozen CLIP ViT-B/32 backbone + trained heads.
+Predicts Body Condition Score (1-9) with an uncertainty-based reject option.
+
+NON-DIAGNOSTIC: weak-label model trained on vision-LLM scores. Not veterinary advice.
+"""
+import os
+
+import numpy as np
+os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
+import torch, joblib, open_clip
+import torchvision.transforms as T
+from PIL import Image
+
+MODEL_DIR_ENV = "FELINEBCS_MODEL_DIR"
+DEFAULT_MODEL_DIR = "models"
+REQUIRED_MODEL_FILES = (
+    "clip_vitb32_regressor.joblib",
+    "clip_vitb32_clf9.joblib",
+    "clip_vitb32_clf4.joblib",
+)
+_MEAN = (0.48145466, 0.4578275, 0.40821073)
+_STD  = (0.26862954, 0.26130258, 0.27577711)
+GRP_NAMES = {0: "Underweight (BCS 1-3)", 1: "Ideal (BCS 4-5)",
+             2: "Overweight (BCS 6-7)", 3: "Obese (BCS 8-9)"}
+# Reject threshold on regressor-classifier disagreement (calibrated on test set;
+# ~70% coverage operating point where MAE drops 0.83->0.74).
+DISAGREE_REJECT = 1.5
+
+
+class MissingModelArtifactsError(RuntimeError):
+    """Raised when the trained head artifacts are unavailable."""
+
+
+def resolve_model_dir(model_dir=None):
+    return os.path.expanduser(model_dir or os.environ.get(MODEL_DIR_ENV, DEFAULT_MODEL_DIR))
+
+
+def validate_model_dir(model_dir):
+    missing = [
+        os.path.join(model_dir, name)
+        for name in REQUIRED_MODEL_FILES
+        if not os.path.exists(os.path.join(model_dir, name))
+    ]
+    if missing:
+        missing_list = "\n".join(f"- {path}" for path in missing)
+        raise MissingModelArtifactsError(
+            "FelineBCS model artifacts were not found.\n"
+            f"Set {MODEL_DIR_ENV} to a directory containing the trained heads, "
+            f"or place them in ./{DEFAULT_MODEL_DIR}/.\n"
+            "Required files:\n"
+            f"{missing_list}"
+        )
+
+def _bcs_to_grp(b):
+    b = int(b)
+    if b <= 3: return 0
+    if b <= 5: return 1
+    if b <= 7: return 2
+    return 3
+
+class FelineBCS:
+    def __init__(self, model_dir=None, device=None):
+        model_dir = resolve_model_dir(model_dir)
+        validate_model_dir(model_dir)
+        self.model_dir = model_dir
+        if device is None:
+            device = os.environ.get("FELINEBCS_DEVICE", "cpu")
+        self.device = device
+        model, _, self.preprocess = open_clip.create_model_and_transforms(
+            "ViT-B-32", pretrained="openai")
+        self.visual = model.visual.eval().to(device)
+        self.reg  = joblib.load(os.path.join(model_dir, "clip_vitb32_regressor.joblib"))
+        self.clf9 = joblib.load(os.path.join(model_dir, "clip_vitb32_clf9.joblib"))
+        self.clf4 = joblib.load(os.path.join(model_dir, "clip_vitb32_clf4.joblib"))
+        self._tta = [self.preprocess,
+                     self._mk(True, 1.0), self._mk(False, 1.1),
+                     self._mk(True, 1.1), self._mk(False, 1.2)]
+
+    @staticmethod
+    def _mk(hflip, scale):
+        ops = ([T.RandomHorizontalFlip(1.0)] if hflip else []) + \
+              [T.Resize(int(224*scale)), T.CenterCrop(224),
+               T.ToTensor(), T.Normalize(_MEAN, _STD)]
+        return T.Compose(ops)
+
+    def _feat(self, img, tf):
+        with torch.no_grad():
+            return self.visual(tf(img).unsqueeze(0).to(self.device)).cpu().numpy()[0]
+
+    def predict(self, img):
+        if isinstance(img, str):
+            img = Image.open(img)
+        img = img.convert("RGB")
+        f = self._feat(img, self.preprocess).reshape(1, -1)
+        bcs = float(np.clip(self.reg.predict(f)[0], 1, 9))
+        p9 = self.clf9.predict_proba(f)[0]
+        ev = float((p9 * self.clf9.classes_).sum())
+        p4 = self.clf4.predict_proba(f)[0]
+        grp_clf = int(self.clf4.classes_[p4.argmax()])
+        # Primary group is derived from the production regressor so the band is
+        # always coherent with the reported BCS; the 4-way classifier is a
+        # secondary opinion (its agreement is an extra confidence signal).
+        grp = _bcs_to_grp(round(bcs))
+        # TTA spread for a stability read
+        tta = np.array([np.clip(self.reg.predict(self._feat(img, tf).reshape(1, -1))[0], 1, 9)
+                        for tf in self._tta])
+        disagree = abs(bcs - ev)
+        return {
+            "bcs": round(bcs, 1),
+            "bcs_rounded": int(round(bcs)),
+            "group": GRP_NAMES[grp],
+            "group_clf": GRP_NAMES[grp_clf],
+            "group_clf_conf": round(float(p4.max()), 3),
+            "group_agree": bool(grp == grp_clf),
+            "classifier_expected": round(ev, 1),
+            "tta_std": round(float(tta.std()), 2),
+            "disagreement": round(disagree, 2),
+            "reject": bool(disagree > DISAGREE_REJECT),
+            "prob9": {int(c): round(float(p), 3) for c, p in zip(self.clf9.classes_, p9)},
+        }
+
+if __name__ == "__main__":
+    import sys, json
+    m = FelineBCS()
+    print(json.dumps(m.predict(sys.argv[1]), indent=2))

requirements.txt

@@ -0,0 +1,9 @@
+gradio
+joblib
+numpy
+open-clip-torch
+pandas
+Pillow
+scikit-learn
+torch
+torchvision