Attachment

Defines the attachment schema.

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.

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

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_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

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.