Fit hosted-backend payloads under the HF router's ~5MiB body cap

All HF-Inference extract models 413'd ("request entity too large") on a
15MP photo: router.huggingface.co rejects request bodies over ~5MiB
(undocumented; measured 2026-08-28 — 5.23MB passes, 5.31MB fails), and
the image rides inline as a base64 data URL. The app path made it worse:
_prepare_image saves its 3MP downscale as lossless PNG, which for photos
can exceed the original JPEG (3.5MB JPEG -> 5.1MB PNG -> 6.85MB base64).

extract_arena.image_to_data_url now budgets MAX_DATA_URL_BYTES (4.5MB):
images under it pass through byte-identical; oversized ones re-encode as
JPEG q85 and downscale 15% per step until they fit (logged). Fixes the
CLI and the Space tab at the single shared choke point; moondream3
(file upload) and local council members were never affected.

Also: note the recompression in the extract_fields MCP docstring
(schema re-verified) and record the router cap + PNG-inflation trap in
MODEL_RESEARCH.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

MODEL_RESEARCH.md

@@ -18,6 +18,13 @@ Verification endpoints (all checked live during the original research):
 - **Reliability marker**: a model whose ONLY provider is `featherless-ai` is on-demand: it
   cold-starts (503 `capacity_exhausted`, sometimes for minutes) and its router entries carry no
   pricing/latency fields. Treat featherless-only as "works, but flaky".
+- **Router body cap ~5 MiB** (undocumented; measured 2026-08-28 by binary search: 5.23MB body
+  passes, 5.31MB gets 413 `request entity too large`, identical across models/providers). Images
+  ride inline as base64 data URLs (×4/3), so the effective image budget is ~3.7MB encoded —
+  `extract_arena.image_to_data_url` recompresses to fit `MAX_DATA_URL_BYTES`. Trap that
+  triggered this: `app.py`'s `_prepare_image` saves its 3MP downscale as **lossless PNG**, which
+  for photos can be *larger* than the original JPEG (a 3.5MB/15MP JPEG became a 5.1MB PNG →
+  6.85MB base64 → 413 on every hosted model).
 - **Leaderboards**: [Roboflow vision evals — Data Extraction](https://playground.roboflow.com/evals/data-extraction)
   (single-field, exact-match — the closest public proxy for this project's task),
   [OCRBench v2](https://99franklin.github.io/ocrbench_v2/) (has an Extraction subscore),

app.py

@@ -502,7 +502,9 @@ configured on the server; without it they fail per-model while the rest still ru
 which models fit your task, read the maintained model research notes (benchmarks, strengths,
 quirks per member) at {MODEL_RESEARCH_URLS}.
 Inputs larger than {MAX_IMAGE_PIXELS / 1e6:.1f} megapixels are downscaled (aspect preserved)
-before inference, so very small text in very large images may need pre-cropping by the caller.
+before inference, so very small text in very large images may need pre-cropping by the caller;
+images sent to hosted backends are additionally recompressed as JPEG when needed to fit the HF
+router's ~5MB request-body cap, so hosted models may see a slightly lossier image than local ones.
 The output is a JSON list with one object per requested model, in request order. Each object
 has: "model" (the model name, or null when the request itself was invalid); "value" (single-field
 requests: the normalized answer, "" meaning the model abstained/field not found, null on

extract_arena.py

@@ -65,6 +65,12 @@ GEMMA_26B_MODEL_ID = "google/gemma-4-26B-A4B-it"
 # (@spaces.GPU(duration=30)) caps how far this can be raised.
 MOONDREAM_SETTINGS = '{"temperature": 0.0, "top_p": 0.95, "max_tokens": 1024}'
 
+# router.huggingface.co rejects request bodies over ~5 MiB with a 413
+# (measured empirically 2026-08-28: 5.23MB passes, 5.31MB fails). The image
+# rides inline as a base64 data URL, so budget it below the cap with headroom
+# for the prompt and JSON scaffolding.
+MAX_DATA_URL_BYTES = 4_500_000
+
 # Abstention sentinel: models emit a fixed token far more reliably than an
 # empty reply; _normalize_value maps it (and close variants) back to "".
 NOT_FOUND = "N/A"
@@ -110,8 +116,37 @@ class ExtractResult:
 
 
 def image_to_data_url(image_path: Path) -> str:
-    mime = mimetypes.guess_type(image_path.name)[0] or "image/png"
-    return f"data:{mime};base64,{base64.b64encode(image_path.read_bytes()).decode()}"
+    """Encode the image as a data URL that fits MAX_DATA_URL_BYTES.
+
+    Images already under budget pass through byte-identical (no quality loss);
+    oversized ones are re-encoded as JPEG and downscaled until they fit.
+    """
+    encoded = base64.b64encode(image_path.read_bytes()).decode()
+    if len(encoded) <= MAX_DATA_URL_BYTES:
+        mime = mimetypes.guess_type(image_path.name)[0] or "image/png"
+        return f"data:{mime};base64,{encoded}"
+
+    import io
+
+    from PIL import Image
+
+    with Image.open(image_path) as im:
+        im = im.convert("RGB")
+        while True:
+            buf = io.BytesIO()
+            im.save(buf, format="JPEG", quality=85)
+            recoded = base64.b64encode(buf.getvalue()).decode()
+            if len(recoded) <= MAX_DATA_URL_BYTES or min(im.size) <= 64:
+                break
+            im = im.resize(
+                (max(1, round(im.width * 0.85)), max(1, round(im.height * 0.85))),
+                Image.LANCZOS,
+            )
+        logger.info(
+            "Recompressed {} for the ~5MiB router body cap: {} -> {} data-URL bytes ({}x{} sent)",
+            image_path.name, len(encoded), len(recoded), im.width, im.height,
+        )
+    return f"data:image/jpeg;base64,{recoded}"
 
 
 def _strip_think(text: str) -> str: