trading_agent.attachments.attachment

One file the user sent with a message: a picture or a document.

The file itself stays in the desk's uploads folder. An attachment is what travels with the message and is written into events: the file's name, type and size, where it is stored, and for a document, where its text is and how long it is.

Typical usage example:

note = attachment.describe_for_model() dictionary = attachment.to_json_dictionary()

AttachmentKind

Bases: StrEnum

What sort of file an attachment is.

Attachment dataclass

Attachment(attachment_id, desk, kind, file_name, media_type, size_bytes, path, desk_path, text_desk_path, text_characters, page_count, problem, created_at)

One stored upload.

Attributes:

Name	Type	Description
attachment_id	str	A unique identifier, also the name of the folder the upload is stored in.
desk	str	The desk it was sent to.
kind	AttachmentKind	A picture, which the model looks at, or a document, which the model reads as text.
file_name	str	The file's name as the user sent it.
media_type	str	The file's media type, such as image/png or application/pdf.
size_bytes	int	The file's size.
path	str	The stored file, as an absolute path.
desk_path	str	The stored file relative to the desk folder, as the desk's tools take it.
text_desk_path	str | None	For a document whose text was read, that text file relative to the desk folder, otherwise None.
text_characters	int | None	How many characters of text the document holds, or None.
page_count	int | None	How many pages a PDF has, or None for other files.
problem	str	Why a document's text could not be read, or an empty string.
created_at	str	When it was stored, as an ISO 8601 string in UTC.

is_image property

is_image

Whether the attachment is a picture.

describe_for_model

describe_for_model()

The note the desk reads about this attachment in the message.

Returns:

Type	Description
str	One bracketed line saying what was attached and how to use it.

Source code in src/trading_agent/attachments/attachment.py

def describe_for_model(self) -> str:
    """The note the desk reads about this attachment in the message.

    Returns:
        str: One bracketed line saying what was attached and how to use it.
    """
    size = self._readable_size()
    if self.is_image:
        return f'[Picture attached: {self.file_name} ({size}), saved at {self.desk_path}. It is shown to you with this message.]'
    if self.text_desk_path is None:
        return f'[Document attached: {self.file_name} ({size}), saved at {self.desk_path}. Its text could not be read: {self.problem}]'
    length = f'{self.text_characters:,} characters'
    if self.page_count is not None:
        length = f'{self.page_count} pages, {length}'
    return f'[Document attached: {self.file_name} ({size}; {length}). Its text is at {self.text_desk_path}, labelled as data from outside trading-agent; read it with read_file. The original is {self.desk_path}.]'

to_json_dictionary

to_json_dictionary()

Converts the attachment to a dictionary that json.dumps can write.

Returns:

Type	Description
dict[str, Any]	Every field, with the kind as its name.

Source code in src/trading_agent/attachments/attachment.py

def to_json_dictionary(self) -> dict[str, Any]:
    """Converts the attachment to a dictionary that json.dumps can write.

    Returns:
        dict[str, Any]: Every field, with the kind as its name.
    """
    dictionary = dataclasses.asdict(self)
    dictionary['kind'] = str(self.kind)
    return dictionary

from_json_dictionary classmethod

from_json_dictionary(dictionary)

Reads an attachment written by to_json_dictionary.

Parameters:

Name	Type	Description	Default
dictionary	dict[str, Any]	The fields.	required

Returns:

Type	Description
Attachment	The attachment.

Raises:

Type	Description
KeyError	A field is missing.
ValueError	The kind is not one this version knows.

Source code in src/trading_agent/attachments/attachment.py

@classmethod
def from_json_dictionary(cls, dictionary: dict[str, Any]) -> Self:
    """Reads an attachment written by to_json_dictionary.

    Args:
        dictionary (dict[str, Any]): The fields.

    Returns:
        Attachment: The attachment.

    Raises:
        KeyError: A field is missing.
        ValueError: The kind is not one this version knows.
    """
    fields = dict(dictionary)
    fields['kind'] = AttachmentKind(fields['kind'])
    return cls(**fields)

stored_file

stored_file()

The stored file.

Returns:

Type	Description
Path	The absolute path of the uploaded file.

Source code in src/trading_agent/attachments/attachment.py

def stored_file(self) -> Path:
    """The stored file.

    Returns:
        Path: The absolute path of the uploaded file.
    """
    return Path(self.path)