fix: composite alpha onto white before VLM round-trip

Wikimedia SVG→PNG renders with a transparent background. A naive
.convert('RGB') turned every transparent pixel black, so the VLM saw
a solid black square and (correctly) said 'unknown'.

- New shared signbridge.imageio module with load_rgb() + array_to_rgb()
helpers that composite alpha onto white at every loader boundary.
- Wired into smoke_test, run_gold_set, backend (b64 decode), and the
vlm recognizer's _frame_to_data_url.
- Confirmed: ASL letter A from Wikimedia is now identified correctly
via Qwen3-VL-8B on HF Inference Providers, conf 0.85.

HF provider also added as a fallback to the composer client resolver,
so we can validate the pipeline end-to-end while waiting for AMD Dev
Cloud credit email.

68 tests still pass; ruff clean.

signbridge/backend.py

@@ -15,17 +15,16 @@ Endpoints:
 from __future__ import annotations
 
 import base64
-import io
 import logging
 import os
 
 import numpy as np
 from fastapi import FastAPI, HTTPException
 from fastapi.responses import FileResponse
-from PIL import Image
 from pydantic import BaseModel, Field
 
 from signbridge.composer.sentence import compose_sentence
+from signbridge.imageio import load_rgb
 from signbridge.recognizer.vlm import recognize_sign_from_frame
 from signbridge.voice.tts import synthesize_speech
 
@@ -69,7 +68,7 @@ def _decode_b64_image(b64: str) -> np.ndarray:
         if b64.startswith("data:"):
             b64 = b64.split(",", 1)[1]
         raw = base64.b64decode(b64)
-        return np.asarray(Image.open(io.BytesIO(raw)).convert("RGB"))
+        return load_rgb(raw)
     except Exception as exc:  # noqa: BLE001
         raise HTTPException(status_code=400, detail=f"bad frame: {exc}") from exc
 

signbridge/composer/sentence.py

@@ -63,6 +63,22 @@ def _resolve_client() -> tuple[object | None, str]:
             "SIGNBRIDGE_COMPOSER_MODEL_OPENAI", "gpt-4o-mini"
         )
 
+    if provider == "hf":
+        api_key = os.getenv("HF_TOKEN", "")
+        if not api_key:
+            logger.info("HF_TOKEN not set; falling back to naive joiner.")
+            return None, composer_model
+        return (
+            OpenAI(
+                base_url=os.getenv(
+                    "HF_INFERENCE_BASE_URL",
+                    "https://router.huggingface.co/v1",
+                ),
+                api_key=api_key,
+            ),
+            composer_model,
+        )
+
     logger.warning("unknown SIGNBRIDGE_PROVIDER=%r; using naive joiner.", provider)
     return None, composer_model
 

signbridge/imageio.py

@@ -0,0 +1,70 @@
+"""Shared image-loading helpers.
+
+Centralised so the recognizer, smoke test, gold-set harness, and backend
+all behave the same way on alpha-channel images (e.g. SVG-rendered PNGs
+with transparent backgrounds — those would otherwise come out solid black
+after a naive `.convert("RGB")` and the VLM sees nothing).
+"""
+
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+import numpy as np
+
+
+def load_rgb(source: str | Path | bytes | io.IOBase) -> np.ndarray:
+    """Load an image as an RGB ndarray, compositing any alpha onto white.
+
+    Accepts a filesystem path, raw bytes, or any file-like object PIL
+    knows how to open.
+    """
+    from PIL import Image
+
+    if isinstance(source, (str, Path)):
+        img = Image.open(source)
+    elif isinstance(source, (bytes, bytearray)):
+        img = Image.open(io.BytesIO(bytes(source)))
+    else:
+        img = Image.open(source)
+
+    return _composite_to_rgb(img)
+
+
+def array_to_rgb(arr: np.ndarray) -> np.ndarray:
+    """Convert an arbitrary-shape ndarray (H,W,3 or H,W,4) to RGB on white.
+
+    Used at the recognizer's API boundary in case a caller hands us a
+    pre-decoded RGBA array.
+    """
+    from PIL import Image
+
+    if arr.ndim == 2:
+        img = Image.fromarray(arr).convert("RGB")
+        return np.asarray(img)
+    if arr.shape[-1] == 3:
+        return arr if arr.dtype == np.uint8 else arr.astype(np.uint8)
+    if arr.shape[-1] == 4:
+        img = Image.fromarray(arr, mode="RGBA")
+        return _composite_to_rgb(img)
+    raise ValueError(f"unsupported array shape for RGB conversion: {arr.shape}")
+
+
+def _composite_to_rgb(img) -> np.ndarray:  # noqa: ANN001
+    from PIL import Image
+
+    if img.mode in ("RGBA", "LA"):
+        bg = Image.new("RGB", img.size, (255, 255, 255))
+        alpha = img.getchannel("A") if img.mode == "RGBA" else img.split()[-1]
+        bg.paste(img.convert("RGB"), mask=alpha)
+        img = bg
+    elif img.mode == "P" and "transparency" in img.info:
+        # Palette image with transparent index — also composite.
+        rgba = img.convert("RGBA")
+        bg = Image.new("RGB", rgba.size, (255, 255, 255))
+        bg.paste(rgba, mask=rgba.getchannel("A"))
+        img = bg
+    elif img.mode != "RGB":
+        img = img.convert("RGB")
+    return np.asarray(img)

signbridge/recognizer/vlm.py

@@ -90,15 +90,20 @@ def _resolve_client() -> tuple[object | None, str]:
         if not api_key:
             logger.info("HF_TOKEN not set; recognizer in stub mode.")
             return None, DEFAULT_VLM_MODEL
+        # HF Inference Providers — OpenAI-compatible router serving Qwen2-VL,
+        # Llama-3.2-Vision, etc. via Together/Fireworks/Hyperbolic backends.
         return (
             OpenAI(
                 base_url=os.getenv(
                     "HF_INFERENCE_BASE_URL",
-                    "https://api-inference.huggingface.co/v1",
+                    "https://router.huggingface.co/v1",
                 ),
                 api_key=api_key,
             ),
-            DEFAULT_VLM_MODEL,
+            os.getenv(
+                "SIGNBRIDGE_VLM_MODEL_HF",
+                "meta-llama/Llama-3.2-11B-Vision-Instruct",
+            ),
         )
 
     logger.warning("unknown SIGNBRIDGE_PROVIDER=%r; recognizer in stub mode.", provider)
@@ -108,7 +113,10 @@ def _resolve_client() -> tuple[object | None, str]:
 def _frame_to_data_url(frame: np.ndarray) -> str:
     from PIL import Image
 
-    img = Image.fromarray(frame)
+    from signbridge.imageio import array_to_rgb
+
+    rgb = array_to_rgb(frame)
+    img = Image.fromarray(rgb)
     buf = io.BytesIO()
     img.save(buf, format="JPEG", quality=85)
     b64 = base64.b64encode(buf.getvalue()).decode("ascii")

signbridge/scripts/run_gold_set.py

@@ -29,10 +29,9 @@ from collections import defaultdict
 from datetime import datetime, timezone
 from pathlib import Path
 
-import numpy as np
 from dotenv import load_dotenv
-from PIL import Image
 
+from signbridge.imageio import load_rgb
 from signbridge.recognizer.vlm import recognize_sign_from_frame
 
 VALID_EXTS = {".jpg", ".jpeg", ".png", ".webp"}
@@ -87,7 +86,7 @@ def main() -> int:
     t_start = time.perf_counter()
     for expected, path in samples:
         per_class_total[expected] += 1
-        img = np.asarray(Image.open(path).convert("RGB"))
+        img = load_rgb(path)
         t0 = time.perf_counter()
         predicted, confidence = recognize_sign_from_frame(img)
         dt_ms = (time.perf_counter() - t0) * 1000

signbridge/scripts/smoke_test.py

@@ -24,6 +24,7 @@ from dotenv import load_dotenv
 from PIL import Image, ImageDraw
 
 from signbridge.composer.sentence import compose_sentence
+from signbridge.imageio import load_rgb
 from signbridge.recognizer.vlm import recognize_sign_from_frame
 from signbridge.voice.tts import synthesize_speech
 
@@ -95,7 +96,7 @@ def main() -> int:
 
     _step("VLM recognizer (sign-frame → token)")
     if args.frame:
-        img = np.asarray(Image.open(args.frame).convert("RGB"))
+        img = load_rgb(args.frame)
         print(f"  using real frame: {args.frame} ({img.shape})")
     else:
         img = _make_synthetic_frame()