Attachment

Attachment schema package.

Exports all attachment-related classes and constants for backward compatibility.

Attachment

Bases: BaseModel

Defines a file attachment schema.

Attributes:

Name	Type	Description
data	bytes	The content data of the file attachment.
filename	str	The filename of the file attachment.
mime_type	str	The mime type of the file attachment.
extension	str	The extension of the file attachment.
url	str | None	The URL of the file attachment. Defaults to None.
metadata	dict[str, Any]	The metadata of the file attachment. Defaults to an empty dictionary.
provider_config	dict[ModelProvider, dict[str, Any]]	The per-provider configuration for this attachment. Defaults to an empty dictionary.
context_config	ContextConfig | None	Configuration for rendering selected attachment context fields as adjacent text content when used as LM inputs. Defaults to None.

__repr__()

Return string representation of the Attachment.

Returns:

Name	Type	Description
str	str	The string representation of the Attachment.

__str__()

Return string representation of the Attachment.

Returns:

Name	Type	Description
str	str	The string representation of the Attachment.

configure_context(*, placement=ContextPlacement.AFTER, fields=None, metadata_keys=None, template=DEFAULT_CONTEXT_TEMPLATE)

Configure selected attachment context fields to render as LM prompt text.

Attachment context remains unused unless this method is called with renderable fields. When configured, LM invokers render selected fields as adjacent text content.

Parameters:

Name	Type	Description	Default
placement	ContextPlacement	Where to insert rendered context relative to the attachment. Defaults to ContextPlacement.AFTER.	AFTER
fields	list[ContextField] | None	Context fields to include. Supports attachment descriptor fields (filename, mime_type, url) and metadata. Defaults to None, which renders no context.	None
metadata_keys	list[str] | None	Metadata keys to include when metadata is selected in fields. Defaults to None, which includes all metadata when metadata is selected.	None
template	str	Template string for custom context formatting. Supported placeholders: {context_json}, {filename}, {mime_type}, {url}, {metadata_json}. Defaults to DEFAULT_CONTEXT_TEMPLATE.	DEFAULT_CONTEXT_TEMPLATE

Returns:

Name	Type	Description
Self	Self	This attachment with context configured.

from_base64(base64_data, filename=None, metadata=None) classmethod

Creates an Attachment from a base64 string.

Parameters:

Name	Type	Description	Default
base64_data	str	The base64 string of the file.	required
filename	str | None	The filename of the file. Defaults to None, in which case the filename will be derived from the mime type.	None
metadata	dict[str, Any] | None	The metadata of the file attachment. Defaults to None, in which case an empty dictionary will be used.	None

Returns:

Name	Type	Description
Attachment	Attachment	The instantiated Attachment.

from_bytes(bytes, filename=None, metadata=None) classmethod

Creates an Attachment from bytes.

Parameters:

Name	Type	Description	Default
bytes	bytes	The bytes of the file.	required
filename	str | None	The filename of the file. Defaults to None, in which case the filename will be derived from the extension.	None
metadata	dict[str, Any] | None	The metadata of the file attachment. Defaults to None, in which case an empty dictionary will be used.	None

Returns:

Name	Type	Description
Attachment	Attachment	The instantiated Attachment.

from_data_url(data_url, filename=None, metadata=None) classmethod

Creates an Attachment from a data URL (data:[mime/type];base64,[bytes]).

Parameters:

Name	Type	Description	Default
data_url	str	The data URL of the file.	required
filename	str | None	The filename of the file. Defaults to None, in which case the filename will be derived from the mime type.	None
metadata	dict[str, Any] | None	The metadata of the file attachment. Defaults to None, in which case an empty dictionary will be used.	None

Returns:

Name	Type	Description
Attachment	Attachment	The instantiated Attachment.

from_path(path, filename=None, metadata=None) classmethod

Creates an Attachment from a path.

Parameters:

Name	Type	Description	Default
path	str	The path to the file.	required
filename	str | None	The filename of the file. Defaults to None, in which case the filename will be derived from the path.	None
metadata	dict[str, Any] | None	The metadata of the file attachment. Defaults to None, in which case an empty dictionary will be used.	None

Returns:

Name	Type	Description
Attachment	Attachment	The instantiated Attachment.

from_url(url, filename=None, metadata=None) classmethod

Creates an Attachment from a URL.

Parameters:

Name	Type	Description	Default
url	str	The URL of the file.	required
filename	str | None	The filename of the file. Defaults to None, in which case the filename will be derived from the URL.	None
metadata	dict[str, Any] | None	The metadata of the file attachment. Defaults to None, in which case an empty dictionary will be used.	None

Returns:

Name	Type	Description
Attachment	Attachment	The instantiated Attachment.

to_base64()

Converts the Attachment to a base64 string.

Returns:

Name	Type	Description
str	str	The base64 string of the Attachment.

Raises:

Type	Description
ValueError	If the Attachment data is empty.

to_context_contents()

Return this attachment with optional adjacent context text.

Returns:

Type	Description
list[Self | str]	list[Self | str]: Attachment with optional adjacent context text: 1. [self] when no context is configured or selected 2. [context, self] for before placement 3. [self, context] for after placement

Note

template="" produces an empty-string context that is included (not suppressed), resulting in [self, ""] or ["", self].

to_data_url()

Converts the Attachment to a data URL.

Returns:

Name	Type	Description
str	str	The data URL of the Attachment.

Raises:

Type	Description
ValueError	If the Attachment mime type or data is empty.

with_kwargs(provider, **kwargs)

Merge provider-specific options into this attachment and return self.

Parameters:

Name	Type	Description	Default
provider	ModelProvider | str	The provider to configure.	required
**kwargs	Any	The provider-specific options to merge in.	{}

Returns:

Name	Type	Description
Attachment	Self	This attachment, with the provider-specific options merged in.

write_to_file(path=None)

Writes the Attachment to a file.

Parameters:

Name	Type	Description	Default
path	str | None	The path to the file. Defaults to None, in which case the filename will be used as the path.	None

ContextConfig

Bases: BaseModel

Defines selected attachment fields rendered for LM invokers.

Attributes:

Name	Type	Description
placement	ContextPlacement	Where to insert rendered context relative to the attachment. Defaults to ContextPlacement.AFTER.
fields	list[ContextField] | None	Context fields to include. Supports attachment descriptor fields (filename, mime_type, url) and metadata. Defaults to None, which renders no context.
metadata_keys	list[str] | None	Metadata keys to include when metadata is selected in fields. Defaults to None, which includes all metadata when metadata is included in fields.
template	str	The template to use for rendering the context. Supported template placeholders: - {context_json}: JSON string of attachment descriptor fields and metadata - {filename}: filename of the attachment - {mime_type}: mime type of the attachment - {url}: url of the attachment - {metadata_json}: JSON string of attachment metadata Defaults to DEFAULT_CONTEXT_TEMPLATE.

ContextPlacement

Bases: StrEnum

Defines where attachment context is inserted relative to the attachment.

HTTPConfig

HTTP request configuration constants.

Key

Field names for model validators.

URLAttachment

Bases: Attachment

Defines a URL attachment schema for external file references.

This class is used to represent a file attachment that exists at an external URL (e.g., CDN). The file is NOT downloaded locally; instead, the URL is passed directly to the provider for remote processing.

Attributes:

Name	Type	Description
data	bytes	The content data of the file attachment. Always empty for URL attachments.
filename	str	The filename of the file attachment. Defaults to an empty string when not provided.
url	str	The URL of the external file.
mime_type	str	The MIME type of the file (e.g., 'video/mp4', 'image/jpeg').
extension	str	The extension of the file attachment derived from the MIME type.
metadata	dict[str, Any]	Additional metadata about the file. Defaults to an empty dictionary.

__repr__()

Return string representation of the URLAttachment.

Returns:

Name	Type	Description
str	str	The string representation of the URLAttachment.

__str__()

Return string representation of the URLAttachment.

Returns:

Name	Type	Description
str	str	The string representation of the URLAttachment.

UploadedAttachment

Bases: Attachment

Defines an uploaded file attachment schema.

This class is used to represent a file attachment that has been uploaded to a certain LM provider's files management capabilities. It is recognized through the id attribute, which content depends on the nature of the LM provider's files management capabilities. It could be an ID, a URL, etc.

Attributes:

Name	Type	Description
id	str	The identifier of the uploaded file.
provider	str	The provider that stores and manages the uploaded file.
data	bytes	The content data of the file attachment. Defaults to an empty bytes object.
filename	str	The filename of the file attachment.
mime_type	str	The mime type of the file attachment.
extension	str	The extension of the file attachment.
url	str | None	The URL of the file attachment. Defaults to None.
metadata	dict[str, Any]	The metadata of the file attachment. Defaults to an empty dictionary.

__repr__()

Return string representation of the UploadedAttachment.

Returns:

Name	Type	Description
str	str	The string representation of the UploadedAttachment.

__str__()

Return string representation of the UploadedAttachment.

Returns:

Name	Type	Description
str	str	The string representation of the UploadedAttachment.