피파가 보는 사본, 그리고 프레임

def downscale_for_pippa(payload: bytes, filename: str) -> bytes:
    """A JPEG no longer than 2048 px on its long edge (Firebrand measured a
    full-size photo at ~13k vision tokens; 2048 px cut a turn from 75 s to
    13.6 s). ``sips`` is Apple's, so it reads HEIC and runs under launchd."""
    with tempfile.TemporaryDirectory(prefix="spark-for-pippa-") as tmp_name:
        tmp = Path(tmp_name)
        source = tmp / f"in{Path(filename).suffix.lower() or '.img'}"
        source.write_bytes(payload)
        target = tmp / "for-pippa.jpg"
        command = ["/usr/bin/sips", "-s", "format", "jpeg", "-s", "formatOptions", "82"]
        size = _pixel_size(source)
        if size is None or max(size) > FOR_PIPPA_LONG_EDGE:
            command += ["-Z", str(FOR_PIPPA_LONG_EDGE)]
        result = subprocess.run(
            [*command, str(source), "--out", str(target)],
            capture_output=True,
            text=True,
            timeout=60,
        )
        if result.returncode != 0 or not target.is_file():
            raise PippaError(
                f"could not prepare the photo for Pippa: {result.stderr.strip() or 'sips failed'}"
            )
        return target.read_bytes()

_RESULT_CONTRACT = """\
Return your results in ONE fenced block whose info string is `spark`, one
JSON object per line, writing each line as soon as you have it. Start with
the text the photo is about: what dominates the frame (the largest, closest,
most central text, such as a book's cover or a menu's dishes), then the
rest in reading order. Small text in the background (spines on a shelf
behind, a sign far off) is still read, after the subject, with a note
that it is background. Your first line is the moment's title in Dad's
library.

```spark
{"type": "line", "n": 1, "source": "<the text as it reads>", "translation": "<translation>", "pronunciation": "<how Dad would say it, only when he might say it aloud>", "note": "<a few words, only when it helps>"}
{"type": "expression", "source": "<something useful to say here>", "translation": "<translation>", "pronunciation": "<how to say it>", "use": "<when to say it>"}
```

- `n` is the numbered line below that the text matches; leave `n` out for
  text the numbered lines missed.
- After the lines, add the few expressions Dad is most likely to need next
  in this situation (at a restaurant: asking what a dish is, allergies, the
  bill). A few, never a lesson.
- Outside the block, say what matters in a sentence or two."""

def _text_size(line: dict[str, Any]) -> float | None:
    """How much of the photo the line's text covers, in percent (Vision's
    normalized box): the one measure of what dominates the frame that the
    words alone do not carry. Area, not height: a book spine's vertical
    title is tall and still small."""
    box = line.get("box")
    try:
        area = float(box["w"]) * float(box["h"]) if isinstance(box, dict) else None
    except (KeyError, TypeError, ValueError):
        return None
    return round(area * 100, 2) if area and area > 0 else None