feat: integrate Hugging Face storage for answer images and update related functionality

.env.example

@@ -24,6 +24,14 @@ MATHLY_ANSWER_SCANS_ENABLED=0
 # (this spends API tokens). Anything else, or unset, keeps them locked.
 MATHLY_OPEN_ENDED_LOCKED=1
 
+# ---- Answer images on Hugging Face (optional) ----
+# A private Hugging Face storage bucket for new answer images (photos and the board's hand-ins), instead of
+# Supabase Storage: reading them back to grade and show them is then not Supabase egress. Images saved before
+# stay in Supabase and are still read from there. Leave empty to keep everything in Supabase.
+MATHLY_ANSWER_BUCKET=
+# A token that can write to that bucket (on a Space: add it as a secret).
+HF_TOKEN=
+
 # ---- Phone notifications for photo requests (app/push.py) ----
 # When the computer asks for a photo of an answer, the student's phone gets a notification, even with the app closed.
 # Apply supabase/migrations/20261103180000_math_push_subs.sql first. Make a key with:  python -m app.push

README.md

@@ -58,6 +58,7 @@ Requests last **15 minutes**. A failed upload can be retried on the phone withou
 2. Apply [the additive answer-scan migration](supabase/migrations/20261031133254_math_answer_scans.sql) in that project's SQL editor or your normal migration pipeline. It adds three tables, ownership policies, a service-only transactional RPC, and the private `mathly-answers` bucket. **Do not rerun `docs/mathly-supabase.sql`**, which is the older destructive migration. Back up the target database before applying migrations.
 3. Set `MATHLY_ANSWER_SCANS_ENABLED=1` and restart the app after the migration succeeds. The scan feature needs no AI key. With the flag off or credentials absent, scan APIs fail closed; guest practice and AI problem help still work.
 4. Run `python -m app.answer_cleanup` hourly with the same server environment. It removes unreferenced private objects older than **24 hours** using the Storage API, including images orphaned by failed commits or account/attempt deletion. Referenced answers remain with their attempts; deleting an account/attempt cascades its records and cleanup removes the bytes after the grace period. The maintenance command continues to work when the student-facing feature flag is off. Monitor nonzero cleanup exit codes.
+5. Optional: keep new answer images in a **private** Hugging Face storage bucket instead of Supabase Storage, so reading them back (to grade and to show them) is not Supabase egress. Set `MATHLY_ANSWER_BUCKET` (e.g. `wzender/mathly-answers`) and `HF_TOKEN` (a token that can write to it; on a Space, a secret). New images get file names starting with `hf-` and go to the bucket under `answers/`; images saved before stay in Supabase and are still read from there. Cleanup covers both: for the bucket it lists images older than 24 hours and removes the ones no answer uses. Never use a public bucket: these are students' answers.
 
 Upload leases last at most **3 minutes**, bounded by request expiry. Interrupted leases become retryable failures on the next status/discovery check. Images are limited to 5 MB JPEG/PNG/WebP, decoded and re-encoded as JPEG to remove metadata, and accessed through owner-checked authenticated endpoints. When grading is configured, saving the image starts an automatic check using the saved image bytes and original question snapshot; the review screen explains this before submission. Private storage URLs are never sent. Upload receipt is independent of grading: an AI failure leaves the photograph saved and provides a retry option. The flow works across workers and server restarts.
 

app/answer_routes.py

@@ -213,7 +213,7 @@ def install_answer_routes(app, signed_in):
             raise ScanError(409, "invalid_upload")
         try:
             image = clean_image(data, content_type)
-            object_key = f"{user}/{sid}/{lease}/{uuid.uuid4()}.jpg"
+            object_key = app.state.answers.new_key(user, sid, lease)
             app.state.answers.put(object_key, image)
             result = usable(call(user, "finalize", scan_id=sid, lease_id=lease,
                                  object_key=object_key, byte_size=len(image)))

app/answer_scans.py

@@ -2,24 +2,36 @@
 
 No fallback to process memory is allowed. The adapter uses the same Supabase
 project as sign-in; a verified user ID is passed on every student operation.
+
+Images: with MATHLY_ANSWER_BUCKET set (a private Hugging Face storage bucket, written with HF_TOKEN), new answer
+images are kept there instead of Supabase Storage, so reading them back (to grade and to show them) is not Supabase
+egress. Their file names start with "hf-"; images saved before keep their names and stay in Supabase, where they
+are still read from.
 """
 from __future__ import annotations
 
 import io
 import json
+import logging
 import os
+import tempfile
 import urllib.error
 import urllib.parse
 import urllib.request
 import uuid
 import warnings
 from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
 
 from PIL import Image, ImageOps, UnidentifiedImageError
 
 MAX_IMAGE = 5_000_000
 Image.MAX_IMAGE_PIXELS = 20_000_000
 BUCKET = "mathly-answers"
+HUB_MARK = "hf-"   # an image kept in the Hugging Face bucket: its file name starts with this
+ORPHAN_AGE = timedelta(hours=24)
+log = logging.getLogger("mathly.answers")
 
 
 @dataclass
@@ -54,10 +66,65 @@ def clean_image(data: bytes, content_type: str) -> bytes:
         raise ScanError(415, "invalid_image") from exc
 
 
+class HubImages:
+    """Answer images in a private Hugging Face storage bucket, under answers/<the object key>."""
+    PREFIX = "answers/"
+
+    def __init__(self, bucket: str, token: str | None = None):
+        from huggingface_hub import HfApi
+        from huggingface_hub.utils import disable_progress_bars
+        disable_progress_bars()   # no progress bars in the server's log
+        self.bucket, self.api = bucket, HfApi(token=token or None)
+
+    @classmethod
+    def from_env(cls):
+        bucket = os.environ.get("MATHLY_ANSWER_BUCKET", "").strip()
+        return cls(bucket, os.environ.get("HF_TOKEN", "").strip()) if bucket else None
+
+    def _call(self, what, *args, **kwargs):
+        from huggingface_hub.errors import EntryNotFoundError
+        try:
+            return what(self.bucket, *args, **kwargs)
+        except EntryNotFoundError as exc:
+            raise ScanError(404, "not_found") from exc
+        except Exception as exc:   # network, token or quota: never pass the details on to the browser
+            log.warning("answer bucket failed: %s", type(exc).__name__)
+            raise ScanError(503, "answer_storage_unavailable") from exc
+
+    def put(self, object_key: str, data: bytes):
+        self._call(self.api.batch_bucket_files, add=[(data, self.PREFIX + object_key)])
+
+    def read(self, object_key: str) -> bytes:
+        with tempfile.TemporaryDirectory() as tmp:
+            target = Path(tmp) / "image.jpg"
+            self._call(self.api.download_bucket_files, [(self.PREFIX + object_key, str(target))], raise_on_missing_files=True)
+            return target.read_bytes()
+
+    def delete(self, object_key: str):
+        self._call(self.api.batch_bucket_files, delete=[self.PREFIX + object_key])
+
+    def older_than(self, age: timedelta) -> list[str]:
+        """The object keys uploaded before now - age."""
+        cutoff = datetime.now(timezone.utc) - age
+        files = self._call(self.api.list_bucket_tree, prefix=self.PREFIX.rstrip("/"), recursive=True)
+        return [f.path[len(self.PREFIX):] for f in files
+                if getattr(f, "type", "") == "file" and f.path.startswith(self.PREFIX)
+                and (getattr(f, "uploaded_at", None) or getattr(f, "mtime", None) or cutoff) < cutoff]
+
+
+def on_hub(object_key: str) -> bool:
+    return object_key.rsplit("/", 1)[-1].startswith(HUB_MARK)
+
+
 class AnswerScans:
-    def __init__(self, auth, *, enabled=None):
+    def __init__(self, auth, *, enabled=None, images="env"):
         self.auth = auth
         self.enabled = (os.environ.get("MATHLY_ANSWER_SCANS_ENABLED") == "1") if enabled is None else enabled
+        self.images = HubImages.from_env() if images == "env" else images   # None: every image in Supabase Storage
+
+    def new_key(self, user_id: str, scan_id: str, lease_id: str) -> str:
+        """A new image's object key; the database checks its user/scan/lease start."""
+        return f"{user_id}/{scan_id}/{lease_id}/{HUB_MARK if self.images else ''}{uuid.uuid4()}.jpg"
 
     @property
     def configured(self):
@@ -104,22 +171,55 @@ class AnswerScans:
         except (urllib.error.URLError, TimeoutError, OSError) as exc:
             raise ScanError(503, "answer_storage_unavailable") from exc
 
+    def _hub(self, object_key):
+        if not on_hub(object_key):
+            return None
+        if not self.images:   # an "hf-" image while the bucket is not configured: say so, never ask Supabase for it
+            raise ScanError(503, "answer_storage_unavailable")
+        return self.images
+
     def put(self, object_key, data):
+        if hub := self._hub(object_key):
+            return hub.put(object_key, data)
         self._request(f"/storage/v1/object/{BUCKET}/{urllib.parse.quote(object_key, safe='/')}",
                       "POST", data, "image/jpeg")
 
     def read(self, object_key):
+        if hub := self._hub(object_key):
+            return hub.read(object_key)
         return self._request(f"/storage/v1/object/authenticated/{BUCKET}/{urllib.parse.quote(object_key, safe='/')}")
 
     def delete(self, object_key):
+        if hub := self._hub(object_key):
+            return hub.delete(object_key)
         self._request(f"/storage/v1/object/{BUCKET}", "DELETE",
                       json.dumps({"prefixes": [object_key]}).encode(), "application/json")
 
+    def referenced(self, keys: list[str]) -> set[str]:
+        """Which of these object keys an answer still uses."""
+        found = set()
+        for i in range(0, len(keys), 40):
+            chunk = keys[i:i + 40]
+            names = ",".join('"' + k.replace('"', "") + '"' for k in chunk)
+            raw = self._request("/rest/v1/math_answer_attachments?select=object_key&object_key=in."
+                                + urllib.parse.quote(f"({names})", safe="(),"))
+            found |= {row["object_key"] for row in json.loads(raw)}
+        return found
+
     def cleanup(self):
+        """Removes images no answer uses, a day after they were uploaded (an upload's answer is saved right after it)."""
         candidates = self.action(None, "cleanup_candidates")
         for key in candidates:
             self.delete(key)
-        return len(candidates)
+        removed = len(candidates)
+        if self.images:   # the database cannot list the bucket: the bucket is listed and each image looked up
+            old = self.images.older_than(ORPHAN_AGE)
+            used = self.referenced(old) if old else set()
+            for key in old:
+                if key not in used:
+                    self.images.delete(key)
+                    removed += 1
+        return removed
 
 
 def public_result(result):

app/monitoring.py

@@ -149,7 +149,7 @@ def install_monitoring_routes(app, manager) -> None:
         answers = app.state.answers
         return {"build": build_metadata(), "errors": log_errors.COUNTER.summary(),
                 "seen": seen_summary(app.state.seen), "actions": app.state.actions.recent(), "photos": photo_summary(app.state.photo_counts),
-                "answers": {"storage": answers.configured, "open_ended_locked": open_ended_locked(),
+                "answers": {"storage": answers.configured, "images": "huggingface" if getattr(answers, "images", None) else "supabase", "open_ended_locked": open_ended_locked(),
                             "grading": bool(grading_key())},
                 "photo_help": bool(os.environ.get("ANTHROPIC_API_KEY", "").strip()
                                    or os.environ.get("CLAUDE_API_KEY", "").strip())}

requirements.txt

@@ -7,3 +7,4 @@ anthropic>=1.0  # photographed-problem hints and solutions
 tzdata>=2024.1
 Pillow==12.3.0  # validate and strip metadata; compatible with Python 3.10 and 3.11
 pywebpush>=2.0,<3  # phone notifications for photo requests (app/push.py)
+huggingface_hub>=1.16,<2  # answer images in a private Hugging Face storage bucket (MATHLY_ANSWER_BUCKET)

tests/conftest.py

@@ -4,3 +4,4 @@ import os
 os.environ["SUPABASE_URL"] = ""
 os.environ["SUPABASE_PUBLISHABLE_KEY"] = ""
 os.environ["VAPID_PRIVATE_KEY"] = ""   # push notifications are off unless a test turns them on
+os.environ["MATHLY_ANSWER_BUCKET"] = ""   # answer images never go to a real Hugging Face bucket from a test

tests/test_answer_images.py

@@ -0,0 +1,93 @@
+"""Answer images in a private Hugging Face bucket (app/answer_scans.py): which store each image is in, and cleanup.
+The bucket here is a stand-in; nothing leaves the machine."""
+import json
+import urllib.parse
+import pytest
+
+from app.answer_scans import AnswerScans, HubImages, ScanError, on_hub
+
+
+class Auth:
+    url, secret = "https://example.supabase.co", "service-key"
+
+
+class FakeHub:
+    def __init__(self):
+        self.files, self.old = {}, set()
+
+    def put(self, key, data): self.files[key] = data
+
+    def read(self, key):
+        if key not in self.files:
+            raise ScanError(404, "not_found")
+        return self.files[key]
+
+    def delete(self, key): self.files.pop(key, None)
+
+    def older_than(self, age): return [k for k in self.files if k in self.old]
+
+
+class Store(AnswerScans):
+    """The adapter with Supabase's HTTP calls recorded instead of sent."""
+    def __init__(self, images, referenced=(), candidates=()):
+        super().__init__(Auth(), enabled=True, images=images)
+        self.calls, self._referenced, self._candidates = [], set(referenced), list(candidates)
+
+    def _request(self, path, method="GET", data=None, content_type=None):
+        self.calls.append((method, path))
+        if path.startswith("/rest/v1/math_answer_attachments"):
+            return json.dumps([{"object_key": k} for k in self._referenced if f'"{k}"' in urllib.parse.unquote(path)]).encode()
+        return b"supabase-image"
+
+    def action(self, user_id, action, **data):
+        assert action == "cleanup_candidates"
+        return self._candidates
+
+
+def test_new_images_are_named_for_the_bucket_and_kept_there():
+    hub = FakeHub(); store = Store(hub)
+    key = store.new_key("u1", "s1", "l1")
+    assert key.startswith("u1/s1/l1/hf-") and key.endswith(".jpg") and on_hub(key)
+    store.put(key, b"jpeg")
+    assert hub.files == {key: b"jpeg"} and store.calls == []   # no Supabase Storage call at all
+    assert store.read(key) == b"jpeg"
+    store.delete(key)
+    assert hub.files == {} and store.calls == []
+
+
+def test_images_saved_before_the_bucket_are_still_read_from_supabase():
+    store = Store(FakeHub())
+    assert store.read("u1/s1/l1/1234.jpg") == b"supabase-image"
+    assert store.calls == [("GET", "/storage/v1/object/authenticated/mathly-answers/u1/s1/l1/1234.jpg")]
+
+
+def test_without_a_bucket_everything_stays_in_supabase():
+    store = Store(None)
+    key = store.new_key("u1", "s1", "l1")
+    assert not on_hub(key)
+    store.put(key, b"jpeg")
+    assert store.calls[0][0] == "POST" and store.calls[0][1].startswith("/storage/v1/object/mathly-answers/u1/s1/l1/")
+    with pytest.raises(ScanError) as err:   # a bucket image while the bucket is off: unavailable, not a Supabase 404
+        store.read("u1/s1/l1/hf-x.jpg")
+    assert err.value.status == 503
+
+
+def test_cleanup_removes_old_bucket_images_no_answer_uses():
+    hub = FakeHub()
+    kept, orphan, fresh = "u/s/l/hf-kept.jpg", "u/s/l/hf-orphan.jpg", "u/s/l/hf-fresh.jpg"
+    for k in (kept, orphan, fresh):
+        hub.put(k, b"x")
+    hub.old = {kept, orphan}   # fresh is less than a day old: its answer may still be on its way
+    store = Store(hub, referenced={kept}, candidates=["u/s/l/old-supabase.jpg"])
+    assert store.cleanup() == 2   # the Supabase orphan and the bucket orphan
+    assert set(hub.files) == {kept, fresh}
+    assert ("DELETE", "/storage/v1/object/mathly-answers") in store.calls
+
+
+def test_the_bucket_is_configured_from_the_environment(monkeypatch):
+    monkeypatch.setenv("MATHLY_ANSWER_BUCKET", "")
+    assert HubImages.from_env() is None
+    monkeypatch.setenv("MATHLY_ANSWER_BUCKET", "someone/answers")
+    monkeypatch.setenv("HF_TOKEN", "hf_test")
+    hub = HubImages.from_env()
+    assert hub.bucket == "someone/answers" and hub.api.token == "hf_test"