1"""Build image-bearing request payloads for Converse and the Responses API.
2
3Two mistakes are easy to make by hand and both produce a confusing failure mode
4where the vision smoke test passes (it hardcodes a known-good jpeg) while every
5golden case fails:
6
71. **Extension is not the wire format.** A `.jpg` file is `jpeg` for Converse and
8   `image/jpeg` for Responses. Passing `jpg` / `image/jpg` is rejected.
92. **Responses content must be wrapped in a message item.** A bare
10   `[{"type": "input_text", ...}]` list is not a valid `input`; it has to be
11   `[{"role": "user", "content": [...]}]`.
123. **`detail` is required on a Responses image block.** The pinned OpenAI SDK
13   declares `ResponseInputImageParam.detail` as `Required`, so omitting it is a
14   contract violation even though a TypedDict will not catch it at runtime.

image_input.py on GitHub

Callers should use `converse_message` / `responses_message` rather than assembling

these dicts inline, so the shape is decided in one tested place.

"""

from pathlib import Path

# Accepted by ResponseInputImageParam.detail; "auto" is the SDK's documented default.

DETAIL_LEVELS = ("low", "high", "auto", "original")

DEFAULT_DETAIL = "auto"

# Formats Bedrock Converse accepts, keyed by the extensions that map onto them.

_CONVERSE_FORMATS = {

"jpg": "jpeg",

"jpeg": "jpeg",

"png": "png",

"gif": "gif",

"webp": "webp",

}

def converse_format(image_path: str) -> str:

"""Converse `image.format` value for a file path. Raises on unsupported types.

Note `.jpg` -> `jpeg`: the extension and the wire format differ, and Converse

rejects `jpg`.

"""

ext = Path(image_path).suffix.lstrip(".").lower()

if ext not in _CONVERSE_FORMATS:

raise ValueError(

f"unsupported image type {ext!r} for {image_path}: "

f"Bedrock accepts {sorted(set(_CONVERSE_FORMATS.values()))}")

return _CONVERSE_FORMATS[ext]

def mime_type(image_path: str) -> str:

"""MIME type for a data URL, e.g. `.jpg` -> `image/jpeg` (never `image/jpg`)."""

return f"image/{converse_format(image_path)}"

def data_url(image_path: str, raw: bytes) -> str:

"""base64 data URL for the Responses API `input_image.image_url` field."""

import base64

return f"data:{mime_type(image_path)};base64,{base64.b64encode(raw).decode()}"

def converse_message(prompt: str, image_path: str | None = None,

raw: bytes | None = None) -> dict:

"""One Converse `messages[]` item. Image block precedes the text block."""

content: list[dict] = []

if image_path is not None:

if raw is None:

raise ValueError("raw image bytes are required when image_path is given")

content.append({"image": {"format": converse_format(image_path),

"source": {"bytes": raw}}})

content.append({"text": prompt})

return {"role": "user", "content": content}

def responses_message(prompt: str, image_path: str | None = None,

raw: bytes | None = None, detail: str = DEFAULT_DETAIL) -> dict:

"""One Responses API `input[]` item, wrapped as a user message.

Returning the wrapper (rather than a bare content list) is the point: an

unwrapped list is invalid input, and that is the easiest thing to get wrong.

`detail` is always emitted because the SDK declares it Required.

"""

if detail not in DETAIL_LEVELS:

raise ValueError(f"invalid image detail {detail!r}: expected one of {list(DETAIL_LEVELS)}")

content: list[dict] = [{"type": "input_text", "text": prompt}]

if image_path is not None:

if raw is None:

raise ValueError("raw image bytes are required when image_path is given")

content.append({"type": "input_image",

"image_url": data_url(image_path, raw),

"detail": detail})

return {"role": "user", "content": content}