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
ValueError	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.

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.

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 — 5xx responses and network/timeout errors — are retried regardless of the config's exception settings; 4xx responses 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
ValueError	On a 4xx response (permanent), or on a 5xx/network failure once retries are exhausted.

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.

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.

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.

Parameters:

Name	Type	Description	Default
uri	str	HTTP(S) URI to download.	required
retry_config	RetryConfig | None	Controls retry count and backoff. Defaults to no retries (max_retries=0). Only transient failures -- 5xx responses and network/timeout errors -- are retried; 4xx responses fail immediately.	None

Returns:

Name	Type	Description
bytes	bytes	Downloaded response body.

Raises:

Type	Description
ValueError	On a 4xx response, or on a 5xx/network failure once retries are exhausted.

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.