judgevet.media

Status: draft.

`judgevet.media`

Validate ordered image evidence around application-owned providers.

Source: https://github.com/Alberto-Codes/judgevet/issues/203#issuecomment-5851219798.

Examples:

from judgevet.media import ImageAttachment, ImageEvidence, MediaCapabilities

evidence = ImageEvidence(
    [ImageAttachment("a", b"opaque", "image/png")], {"q": ["a"]}
)
assert evidence.by_question["q"] == ("a",)
assert "image/png" in MediaCapabilities({"image/png"}).image_types

async_judge_with_images keeps the checks, their order and the errors of judge_with_images, and awaits the provider instead. Source: https://github.com/Alberto-Codes/judgevet/issues/252#issuecomment-5924224316.

Both entries forward an optional provider_options mapping unchanged. They pass it only when it is set, and only to a method whose signature takes it. Source: https://github.com/Alberto-Codes/judgevet/issues/281.

`AsyncMediaSystemOnePort`

Bases: AsyncSystemOnePort, Protocol

Provide awaited text and image judgments without implicit media fallback.

The protocol check is structural. A port whose system_one_media is synchronous still passes isinstance, and awaiting its result raises TypeError.

Attributes:

Name	Type	Description
`capabilities`	`method`	Return a static declaration for the selected model.
`system_one_media`	`method`	Judge exact ordered evidence and bindings.
`system_one`	`method`	Preserve the existing async text operation.

Examples:

async def judge(port: AsyncMediaSystemOnePort, evidence, questions):
    return await port.system_one_media(
        "state", questions, "selected", evidence=evidence
    )

`capabilities(model)`

Return static capabilities without acquisition, IO or inference.

Parameters:

Name	Type	Description	Default
`model`	`str`	Caller-selected model, not an inferred resolved identity.	required

Returns:

Type	Description
`MediaCapabilities`	Capabilities established by the application during setup.

`system_one_media(state, questions, model, *, evidence)` `async`

Judge media while preserving bytes, identities, orders and bindings.

Parameters:

Name	Type	Description	Default
`state`	`str \| dict[str, Any] \| list[Any]`	Original caller state.	required
`questions`	`Mapping[str, Question \| Mapping[str, Any]]`	Original typed or raw question definitions.	required
`model`	`str`	Caller-selected model.	required
`evidence`	`ImageEvidence`	Immutable ordered attachment snapshot.	required

Returns:

Type	Description
`SystemOneResponse`	Typed answers with provider-reported model and usage metadata.

Raises:

Type	Description
`ProviderError`	A declared provider failure, never a semantic answer.

`ImageAttachment` `dataclass`

An opaque encoded image with a caller-owned identity.

Attributes:

Name	Type	Description
`id`	`str`	Nonempty attachment identity.
`data`	`bytes`	Exact nonempty encoded bytes, never decoded here.
`media_type`	`str`	Nonempty declared MIME type.

Examples:

image = ImageAttachment("scan", b"opaque", "image/png")

`__post_init__()`

Validate declarations without interpreting bytes.

Raises:

Type	Description
`ValueError`	An identifier or the byte payload is invalid.

`ImageEvidence` `dataclass`

Snapshot ordered images and question associations.

Attributes:

Name	Type	Description
`images`	`tuple[ImageAttachment, ...]`	Images in caller order.
`by_question`	`Mapping[str, tuple[str, ...]]`	Immutable ordered associations.
`required`	`frozenset[str]`	Questions requiring nonempty evidence at dispatch.

Examples:

evidence = ImageEvidence([], {})

`init(images, by_question, required=())`

Validate structure and take defensive snapshots.

Parameters:

Name	Type	Description	Default
`images`	`Sequence[ImageAttachment]`	Ordered attachments, each referenced at least once.	required
`by_question`	`Mapping[str, Sequence[str]]`	Ordered attachment IDs for each associated question.	required
`required`	`Collection[str]`	Questions whose evidence must be present at dispatch.	`()`

Raises:

Type	Description
`ValueError`	A shape, identifier, duplicate or association is invalid.

`MediaCapabilities` `dataclass`

Static supported formats and ceilings for one selected model.

Attributes:

Name	Type	Description
`image_types`	`frozenset[str]`	Declared MIME types.
`max_images`	`int`	Positive attachment-count ceiling.
`max_image_bytes`	`int`	Positive per-image byte ceiling.
`max_total_bytes`	`int`	Positive total byte ceiling.

Examples:

caps = MediaCapabilities({"image/png"})

`init(image_types, max_images=16, max_image_bytes=8 * 1024 * 1024, max_total_bytes=32 * 1024 * 1024)`

Snapshot declarations without acquisition or inference.

Parameters:

Name	Type	Description	Default
`image_types`	`Collection[str]`	Supported MIME declarations.	required
`max_images`	`int`	Provider count ceiling.	`16`
`max_image_bytes`	`int`	Provider per-image byte ceiling.	`8 * 1024 * 1024`
`max_total_bytes`	`int`	Provider total byte ceiling.	`32 * 1024 * 1024`

Raises:

Type	Description
`ValueError`	Formats or positive integer bounds are malformed.

`MediaSystemOnePort`

Bases: SystemOnePort, Protocol

Provide text and image judgments without implicit media fallback.

Attributes:

Name	Type	Description
`capabilities`	`method`	Return a static declaration for the selected model.
`system_one_media`	`method`	Judge exact ordered evidence and bindings.
`system_one`	`method`	Preserve the existing text operation.

Examples:

def capabilities(port: MediaSystemOnePort) -> MediaCapabilities:
    return port.capabilities("selected")

`capabilities(model)`

Return static capabilities without acquisition, IO or inference.

Parameters:

Name	Type	Description	Default
`model`	`str`	Caller-selected model, not an inferred resolved identity.	required

Returns:

Type	Description
`MediaCapabilities`	Capabilities established by the application during setup.

`system_one_media(state, questions, model, *, evidence)`

Judge media while preserving bytes, identities, orders and bindings.

Parameters:

Name	Type	Description	Default
`state`	`str \| dict[str, Any] \| list[Any]`	Original caller state.	required
`questions`	`Mapping[str, Question \| Mapping[str, Any]]`	Original typed or raw question definitions.	required
`model`	`str`	Caller-selected model.	required
`evidence`	`ImageEvidence`	Immutable ordered attachment snapshot.	required

Returns:

Type	Description
`SystemOneResponse`	Typed answers with provider-reported model and usage metadata.

Raises:

Type	Description
`ProviderError`	A declared provider failure, never a semantic answer.

`MissingEvidenceError`

Bases: ProviderRequestError

A required question has no associated image evidence.

Source: https://github.com/Alberto-Codes/judgevet/issues/203#issuecomment-5851219798.

Attributes:

Name	Type	Description
`args`	`tuple`	Standard exception arguments containing a safe message.

Examples:

from judgevet.media import MissingEvidenceError

error = MissingEvidenceError("Required question has no evidence")
assert isinstance(error, ProviderRequestError)

`async_judge_with_images(port, state, questions, model, *, evidence, provider_options=None)` `async`

Validate evidence before an awaited dispatch and preserve the typed result.

The checks, their order and their errors match judge_with_images. Empty optional evidence awaits the existing async text operation unchanged. The function adds no runtime awaitability check. A port whose system_one_media is synchronous raises TypeError when its result is awaited.

Parameters:

Name	Type	Description	Default
`port`	`AsyncSystemOnePort`	Explicitly selected borrowed async provider.	required
`state`	`str \| dict[str, Any] \| list[Any]`	Original caller state, never converted to text.	required
`questions`	`Mapping[str, Question \| Mapping[str, Any]]`	Typed or raw question definitions, including mixed mappings.	required
`model`	`str`	Caller-selected model label.	required
`evidence`	`ImageEvidence`	Immutable attachments and question associations.	required
`provider_options`	`Mapping[str, object] \| None`	Provider-defined settings forwarded unchanged when set.	`None`

Returns:

Type	Description
`SystemOneResponse`	The original response after media contract validation.

Raises:

Type	Description
`ProviderRequestError`	Question definitions or evidence references are invalid.
`MissingEvidenceError`	A required question has no evidence.
`ProviderCapabilityError`	The selected model cannot accept the evidence, or the chosen provider method cannot take `provider_options`.
`ProviderResponseError`	A media response violates the question contract.
`ProviderError`	A declared provider failure propagates unchanged.

`judge_with_images(port, state, questions, model, *, evidence, provider_options=None)`

Validate evidence before dispatch and preserve the original typed result.

Empty optional evidence uses the existing text operation unchanged. Media responses preserve resolved model identity and unknown or zero usage. An insufficient-evidence Choice is ordinary success only when the caller explicitly declares that option. Numbers carry no inferred calibration. async_judge_with_images shares these checks through private helpers.

Parameters:

Name	Type	Description	Default
`port`	`SystemOnePort`	Explicitly selected borrowed provider.	required
`state`	`str \| dict[str, Any] \| list[Any]`	Original caller state, never converted to text.	required
`questions`	`Mapping[str, Question \| Mapping[str, Any]]`	Typed or raw question definitions, including mixed mappings.	required
`model`	`str`	Caller-selected model label.	required
`evidence`	`ImageEvidence`	Immutable attachments and question associations.	required
`provider_options`	`Mapping[str, object] \| None`	Provider-defined settings forwarded unchanged when set.	`None`

Returns:

Type	Description
`SystemOneResponse`	The original response after media contract validation.

Raises:

Type	Description
`ProviderRequestError`	Question definitions or evidence references are invalid.
`MissingEvidenceError`	A required question has no evidence.
`ProviderCapabilityError`	The selected model cannot accept the evidence, or the chosen provider method cannot take `provider_options`.
`ProviderResponseError`	A media response violates the question contract.
`ProviderError`	A declared provider failure propagates unchanged.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

judgevet.media

judgevet.media

AsyncMediaSystemOnePort

capabilities(model)

system_one_media(state, questions, model, *, evidence) async

ImageAttachment dataclass

__post_init__()

ImageEvidence dataclass

__init__(images, by_question, required=())

MediaCapabilities dataclass

__init__(image_types, max_images=16, max_image_bytes=8 * 1024 * 1024, max_total_bytes=32 * 1024 * 1024)

MediaSystemOnePort

capabilities(model)

system_one_media(state, questions, model, *, evidence)

MissingEvidenceError

async_judge_with_images(port, state, questions, model, *, evidence, provider_options=None) async

judge_with_images(port, state, questions, model, *, evidence, provider_options=None)

`judgevet.media`

`AsyncMediaSystemOnePort`

`capabilities(model)`

`system_one_media(state, questions, model, *, evidence)` `async`

`ImageAttachment` `dataclass`

`__post_init__()`

`ImageEvidence` `dataclass`

`init(images, by_question, required=())`

`MediaCapabilities` `dataclass`

`init(image_types, max_images=16, max_image_bytes=8 * 1024 * 1024, max_total_bytes=32 * 1024 * 1024)`

`MediaSystemOnePort`

`capabilities(model)`

`system_one_media(state, questions, model, *, evidence)`

`MissingEvidenceError`

`async_judge_with_images(port, state, questions, model, *, evidence, provider_options=None)` `async`

`judge_with_images(port, state, questions, model, *, evidence, provider_options=None)`