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