Attachment Resolvers

Runtime resolvers for row-level multimodal attachment references.

AttachmentResolverRegistry(resolvers)

Registry that maps URI schemes to attachment resolvers.

Create a registry from resolvers with disjoint scheme ownership.

Parameters:

Name	Type	Description	Default
resolvers	list[BaseAttachmentResolver]	Resolver instances to register.	required

Raises:

Type	Description
EvalConfigurationError	If no resolvers are provided, a resolver has no schemes, or two resolvers claim the same scheme.

resolve(attachment_ref) async

Resolve an attachment reference with the resolver for its URI scheme.

Parameters:

Name	Type	Description	Default
attachment_ref	AttachmentRef	Row-level attachment reference.	required

Returns:

Name	Type	Description
Attachment	Attachment	Runtime attachment resolved by the registered scheme resolver.

Raises:

Type	Description
EvalInputError	If the URI has no scheme.
EvalUnsupportedOperationError	If no resolver handles the scheme.

BaseAttachmentResolver

Bases: ABC

Base class for runtime attachment resolvers.

resolve(attachment_ref) abstractmethod async

Resolve an attachment reference into a runtime attachment.

Parameters:

Name	Type	Description	Default
attachment_ref	AttachmentRef	Portable row-level attachment reference.	required

Returns:

Name	Type	Description
Attachment	Attachment	Runtime attachment for judge invocation.

DataUrlAttachmentResolver

Bases: BaseAttachmentResolver

Resolve data: attachments by delegating to the runtime parser.

resolve(attachment_ref) async

Resolve a data URL using Attachment.from_data_url.

A data URL is self-describing: its content type is derived from the encoded bytes, so it is authoritative. Unlike the file/http resolvers, the row-level mime_type override is NOT applied here, because forcing a different type would contradict the actual image bytes. A conflicting mime_type is ignored with a warning.

Parameters:

Name	Type	Description	Default
attachment_ref	AttachmentRef	Row-level data URL attachment reference.	required

Returns:

Name	Type	Description
Attachment	Attachment	Runtime attachment parsed from the data URL.

Raises:

Type	Description
EvalInputError	If the data URL is malformed or its data is not valid base64.

HttpAttachmentResolver(retry_config=None)

Bases: BaseAttachmentResolver

Resolve http: and https: attachments with async HTTP I/O.

Create the HTTP resolver, optionally retrying transient download failures.

Parameters:

Name	Type	Description	Default
retry_config	RetryConfig | None	Controls how transient failures are retried (retry count, backoff). Defaults to no retries (max_retries=0), preserving fail-on-first-error behavior. Only transient failures — HTTP 500, 502, 503 and 504 responses and connection errors — are retried regardless of the config's exception settings; 4xx responses, other 5xx responses and timeouts fail immediately.	None

resolve(attachment_ref) async

Download a remote attachment and create a runtime attachment from bytes.

Parameters:

Name	Type	Description	Default
attachment_ref	AttachmentRef	Row-level HTTP(S) attachment reference.	required

Returns:

Name	Type	Description
Attachment	Attachment	Runtime attachment created from downloaded bytes.

Raises:

Type	Description
BaseEvalError	The normalized download failure; see download_http_attachment.

LocalAttachmentResolver

Bases: BaseAttachmentResolver

Resolve local file: attachments.

resolve(attachment_ref) async

Resolve a local file URI using Attachment.from_path.

Parameters:

Name	Type	Description	Default
attachment_ref	AttachmentRef	Row-level file attachment reference.	required

Returns:

Name	Type	Description
Attachment	Attachment	Runtime attachment loaded from the local path.

Raises:

Type	Description
EvalInputError	If the URI is malformed.
EvalUnsupportedOperationError	If the URI names a remote host.
EvalResourceNotFoundError	If the file does not exist.
EvalAccessError	If reading the file is denied.
EvalIOError	If reading the file fails for another storage reason.

RowAttachmentResolutionCache(registry)

Single-flight, per-row memoization of attachment resolution.

A placeholder reused across fields (for example the same [ATTACHMENT:id] in both input and retrieved_context) would otherwise resolve — and for remote URIs, download — once per occurrence. This cache resolves each distinct attachment reference at most once per row and reuses the resulting attachment for every occurrence.

References are keyed by their serialized form, so two placeholders pointing at the same source (including a named ID and an inline URI that resolve to the same AttachmentRef) share one resolution. Resolution is single-flight: concurrent requests for the same reference await one shared task.

A cache instance is scoped to a single row; do not share it across rows, since attachment IDs are row-local.

Create a per-row resolution cache backed by a resolver registry.

Parameters:

Name	Type	Description	Default
registry	AttachmentResolverRegistry	Registry used to resolve cache misses.	required

resolve(attachment_ref) async

Resolve the reference, reusing an in-flight or finished resolution.

Parameters:

Name	Type	Description	Default
attachment_ref	AttachmentRef	Row-level attachment reference to resolve.	required

Returns:

Name	Type	Description
Attachment	Attachment	The runtime attachment. Concurrent calls for the same reference share one resolution; repeated calls yield the same attachment (or re-raise the same error).

attachment_ref_from_target(row, target)

Resolve placeholder target precedence into an AttachmentRef.

Named row attachments take precedence over URI interpretation. Inline URI targets are converted directly to AttachmentRef values. Missing named IDs fail before runtime invocation.

Parameters:

Name	Type	Description	Default
row	dict[str, Any]	Normalized evaluation row.	required
target	AttachmentTarget	Parsed attachment placeholder target.	required

Returns:

Name	Type	Description
AttachmentRef	AttachmentRef	Attachment reference to resolve at runtime.

Raises:

Type	Description
EvalInputError	If a named attachment ID is not defined in the row, or its definition is invalid.

create_default_attachment_resolver_registry(http_retry_config=None)

Create the default resolver registry for supported inline URI schemes.

Parameters:

Name	Type	Description	Default
http_retry_config	RetryConfig | None	Optional retry configuration for the HTTP(S) resolver, controlling how transient download failures are retried. Defaults to no retries.	None

Returns:

Name	Type	Description
AttachmentResolverRegistry	AttachmentResolverRegistry	Registry supporting file, HTTP(S), and data URL attachments.

download_http_attachment(uri, retry_config=None) async

Download an HTTP(S) attachment with shared timeout, retry, and error classification.

Retry policy attachment_download: 1 attempt by default, or retry_config.max_retries + 1 attempts with exponential backoff (base_delay, max_delay, jitter) when a config is supplied. Only transient failures are retried: connection failures, HTTP 429 and HTTP 500, 502, 503 and 504. Every other failure, including a request timeout, stops immediately. retry_config.timeout, when set, bounds the whole operation and is never restarted. The config's exception tuples are ignored because the decision uses the normalized error.

Parameters:

Name	Type	Description	Default
uri	str	HTTP(S) URI to download.	required
retry_config	RetryConfig | None	Controls retry count, backoff and overall deadline. Defaults to no retries (max_retries=0).	None

Returns:

Name	Type	Description
bytes	bytes	Downloaded response body.

Raises:

Type	Description
EvalAccessError	On HTTP 401 or 403.
EvalResourceNotFoundError	On HTTP 404.
EvalRateLimitError	On HTTP 429 once retries are exhausted.
EvalServiceError	On another HTTP error status, after retries for 500, 502, 503 and 504 are exhausted.
EvalConnectionError	On a connection failure once retries are exhausted.
EvalTimeoutError	When a request times out or the overall deadline expires.
EvalInputError	When the URI is not a valid URL.

path_from_file_uri(uri)

Convert a file URI into a decoded, platform-native filesystem path.

Uses urllib.request.url2pathname, the platform-aware inverse of Path.as_uri(). On POSIX this decodes percent-escapes only; on Windows it also strips the leading slash ahead of the drive letter and restores backslash separators (file:///C:/a/b.png -> C:\a\b.png), which a plain unquote would leave as the invalid /C:/a/b.png.

Parameters:

Name	Type	Description	Default
uri	str	File URI to convert.	required

Returns:

Name	Type	Description
str	str	Decoded local filesystem path in the native form for the current platform.

Raises:

Type	Description
EvalInputError	If the URI is not a file URI or has no path.
EvalUnsupportedOperationError	If the URI names a remote host.