Switching Image Models Quietly Degrades Quality — A Gate That Catches It Without Manual Review

import io
from dataclasses import dataclass
from PIL import Image
 
 
@dataclass
class PropertyResult:
    ok: bool
    reasons: list
 
 
def check_image_properties(image_bytes, target_w, target_h, tolerance=0.01):
    """Check resolution, aspect ratio, decodability, and flatness."""
    reasons = []
    try:
        img = Image.open(io.BytesIO(image_bytes))
        img.load()
    except Exception as exc:
        return PropertyResult(False, [f"decode_failed: {exc}"])
 
    w, h = img.size
    target_ratio = target_w / target_h
    actual_ratio = w / h
    if abs(actual_ratio - target_ratio) / target_ratio > tolerance:
        reasons.append(f"aspect_mismatch: {actual_ratio:.4f} vs {target_ratio:.4f}")
 
    # Detect degenerate flat images (failed generations going all-black/white) via variance
    gray = img.convert("L")
    pixels = list(gray.getdata())
    mean = sum(pixels) / len(pixels)
    variance = sum((p - mean) ** 2 for p in pixels) / len(pixels)
    if variance < 25.0:
        reasons.append(f"low_variance: {variance:.1f} (flat image)")
 
    return PropertyResult(len(reasons) == 0, reasons)
 
 
result = check_image_properties(open("sample.png", "rb").read(), 1206, 2622)
print(result.ok, result.reasons)
# Example: True []  /  failure: False ['low_variance: 3.2 (flat image)']

import os
import numpy as np
from google import genai
from google.genai import types
 
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
 
 
def embed(content_parts):
    resp = client.models.embed_content(
        model="gemini-embedding-2",
        contents=content_parts,
        config=types.EmbedContentConfig(output_dimensionality=1024),
    )
    return np.array(resp.embeddings[0].values, dtype=np.float32)
 
 
def cosine(a, b):
    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))
 
 
def brief_adherence(image_bytes, brief_text):
    """Return semantic closeness between the brief and the image, 0 to 1."""
    image_part = types.Part.from_bytes(data=image_bytes, mime_type="image/png")
    text_vec = embed([brief_text])
    image_vec = embed([image_part])
    return cosine(text_vec, image_vec)
 
 
brief = "misty cedar forest, low morning light, calm composition with generous negative space, muted saturation"
score = brief_adherence(open("sample.png", "rb").read(), brief)
print(round(score, 4))
# Example: around 0.31 (read this relative to a baseline, not as an absolute)

import os
import json
from google import genai
from google.genai import types
 
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
 
JUDGE_SCHEMA = {
    "type": "object",
    "properties": {
        "adherence": {"type": "integer"},
        "aesthetic": {"type": "integer"},
        "artifacts": {"type": "boolean"},
        "reason": {"type": "string"},
    },
    "required": ["adherence", "aesthetic", "artifacts", "reason"],
}
 
 
def judge_image(image_bytes, brief_text):
    image_part = types.Part.from_bytes(data=image_bytes, mime_type="image/png")
    instruction = (
        "You are a wallpaper quality reviewer. Evaluate the image against this brief. "
        "adherence and aesthetic are integers 0-100. "
        "Set artifacts to true if there is distortion or unnatural repetition. "
        "Keep reason under 12 words.\n\nBrief: " + brief_text
    )
    resp = client.models.generate_content(
        model="gemini-3.5-flash",
        contents=[instruction, image_part],
        config=types.GenerateContentConfig(
            response_mime_type="application/json",
            response_schema=JUDGE_SCHEMA,
            temperature=0.0,
        ),
    )
    return json.loads(resp.text)
 
 
verdict = judge_image(open("sample.png", "rb").read(), "misty cedar forest, low morning light, calm composition")
print(verdict)
# Example: {'adherence': 88, 'aesthetic': 82, 'artifacts': False, 'reason': 'composition and light faithful to brief'}

def quality_gate(image_bytes, brief_text, target_w, target_h, thresholds):
    prop = check_image_properties(image_bytes, target_w, target_h)
    if not prop.ok:
        return {"verdict": "fail", "stage": "properties", "detail": prop.reasons}
 
    sim = brief_adherence(image_bytes, brief_text)
    if sim < thresholds["min_similarity"]:
        return {"verdict": "fail", "stage": "embedding", "detail": round(sim, 4)}
 
    j = judge_image(image_bytes, brief_text)
    if j["artifacts"] or j["adherence"] < thresholds["min_adherence"]:
        return {"verdict": "fail", "stage": "judge", "detail": j}
 
    return {"verdict": "pass", "similarity": round(sim, 4), "judge": j}
 
 
thresholds = {"min_similarity": 0.22, "min_adherence": 70}
out = quality_gate(open("sample.png", "rb").read(), "misty cedar forest, morning light", 1206, 2622, thresholds)
print(out["verdict"], out.get("stage", "ok"))
# Example: pass ok