oumi.core.types

Types module for the Oumi (Open Universal Machine Intelligence) library.

This module provides custom types and exceptions used throughout the Oumi framework.

Exceptions:

HardwareException: Exception raised for hardware-related errors.

Example

>>> from oumi.core.types import HardwareException
>>> try:
...     # Some hardware-related operation
...     pass
... except HardwareException as e:
...     print(f"Hardware error occurred: {e}")

Note

This module is part of the core Oumi framework and is used across various components to ensure consistent error handling and type definitions.

class oumi.core.types.ContentItem(*, type: Type, content: str | None = None, binary: bytes | None = None)

Bases: BaseModel

A sub-part of Message.content.

For example, a multimodal message from USER may include two ContentItem-s: one for text, and another for image.

Note

Either content or binary must be provided when creating an instance.

__repr__() → str

Returns a string representation of the message item.

binary: bytes | None

Optional binary data for the message content item, used for image data.

One of content or binary must be provided.

The field is required for IMAGE_BINARY, and can be optionally populated for IMAGE_URL, IMAGE_PATH in which case it must be the loaded bytes of the image specified in the content field.

The field must be None for TEXT.

content: str | None

Optional text content of the content item.

One of content or binary must be provided.

is_image() → bool

Checks if the item contains an image.

is_text() → bool

Checks if the item contains text.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'binary': FieldInfo(annotation=Union[bytes, NoneType], required=False, default=None), 'content': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'type': FieldInfo(annotation=Type, required=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

model_post_init(_ContentItem__context) → None

Post-initialization method for the ContentItem model.

This method is automatically called after the model is initialized. Performs additional validation e.g., to ensure that either content or binary is provided for the message.

Raises:

ValueError – If fields are set to invalid or inconsistent values.

type: Type

The type of the content (e.g., text, image path, image URL).

class oumi.core.types.ContentItemCounts(total_items: int, text_items: int, image_items: int)

Bases: NamedTuple

Contains counts of content items in a message by type.

image_items: int

The number of image content items in a message.

text_items: int

The number of text content items in a message.

total_items: int

The total number of content items in a message.

class oumi.core.types.Conversation(*, conversation_id: str | None = None, messages: list[Message], metadata: dict[str, Any] = {})

Bases: BaseModel

Represents a conversation, which is a sequence of messages.

__getitem__(idx: int) → Message

Gets the message at the specified index.

Parameters:

idx (int) – The index of the message to retrieve.

Returns:

The message at the specified index.

Return type:

Any

__repr__() → str

Returns a string representation of the conversation.

append_id_to_string(s: str) → str

Appends conversation ID to a string.

Can be useful for log or exception errors messages to allow users to identify relevant conversation.

conversation_id: str | None

Optional unique identifier for the conversation.

This attribute can be used to assign a specific identifier to the conversation, which may be useful for tracking or referencing conversations in a larger context.

filter_messages(role: Role | None = None) → list[Message]

Gets all messages in the conversation, optionally filtered by role.

Parameters:

role – The role to filter messages by. If None, returns all messages.

Returns:

A list of all messages matching the criteria.

Return type:

List[Message]

first_message(role: Role | None = None) → Message | None

Gets the first message in the conversation, optionally filtered by role.

Parameters:

role – The role to filter messages by. If None, considers all messages.

Returns:

The first message matching the criteria,

or None if no messages are found.

Return type:

Optional[Message]

classmethod from_dict(data: dict) → Conversation

Converts a dictionary to a conversation.

classmethod from_json(data: str) → Conversation

Converts a JSON string to a conversation.

last_message(role: Role | None = None) → Message | None

Gets the last message in the conversation, optionally filtered by role.

Parameters:

role – The role to filter messages by. If None, considers all messages.

Returns:

The last message matching the criteria,

or None if no messages are found.

Return type:

Optional[Message]

messages: list[Message]

List of Message objects that make up the conversation.

metadata: dict[str, Any]

Optional metadata associated with the conversation.

This attribute allows for storing additional information about the conversation in a key-value format. It can be used to include any relevant contextual data.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'conversation_id': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'messages': FieldInfo(annotation=list[Message], required=True), 'metadata': FieldInfo(annotation=dict[str, Any], required=False, default={})}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

to_dict()

Converts the conversation to a dictionary.

to_json() → str

Converts the conversation to a JSON string.

exception oumi.core.types.HardwareException

Bases: Exception

An exception thrown for invalid hardware configurations.

class oumi.core.types.Message(*, id: str | None = None, content: str | list[ContentItem], role: Role)

Bases: BaseModel

A message in a conversation.

This class represents a single message within a conversation, containing various attributes such as role, content, identifier.

__repr__() → str

Returns a string representation of the message.

compute_flattened_text_content(separator=' ') → str

Joins contents of all text items.

contains_image_content_items_only() → bool

Checks if the message contains only image items.

At least one image item is required.

contains_images() → bool

Checks if the message contains at least one image.

contains_single_image_content_item_only() → bool

Checks if the message contains exactly 1 image item, and nothing else.

contains_single_text_content_item_only() → bool

Checks if the message contains exactly 1 text item, and nothing else.

These are the most common and simple messages, and may need special handling.

contains_text() → bool

Checks if the message contains at least one text item.

contains_text_content_items_only() → bool

Checks if the message contains only text items.

At least one text item is required.

content: str | list[ContentItem]

Content of the message.

For text messages, content can be set to a string value. For multimodal messages, content should be a list of content items of potentially different types e.g., text and image.

property content_items: list[ContentItem]

Returns a list of text content items.

count_content_items() → ContentItemCounts

Counts content items by type.

id: str | None

Optional unique identifier for the message.

This attribute can be used to assign a specific identifier to the message, which may be useful for tracking or referencing messages within a conversation.

Returns:

The unique identifier of the message, if set; otherwise None.

Return type:

Optional[str]

property image_content_items: list[ContentItem]

Returns a list of image content items.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'content': FieldInfo(annotation=Union[str, list[ContentItem]], required=True), 'id': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'role': FieldInfo(annotation=Role, required=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

model_post_init(_Message__context) → None

Post-initialization method for the Message model.

This method is automatically called after the model is initialized. It performs additional validation to ensure that either content or binary is provided for the message.

Raises:

ValueError – If both content and binary are None.

role: Role

The role of the entity sending the message (e.g., user, assistant, system).

property text_content_items: list[ContentItem]

Returns a list of text content items.

class oumi.core.types.Role(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Role of the entity sending the message.

ASSISTANT = 'assistant'

Represents an assistant message in the conversation.

SYSTEM = 'system'

Represents a system message in the conversation.

TOOL = 'tool'

Represents a tool message in the conversation.

USER = 'user'

Represents a user message in the conversation.

__str__() → str

Return the string representation of the Role enum.

Returns:

The string value of the Role enum.

Return type:

str

class oumi.core.types.TemplatedMessage(*, template: str, role: Role)

Bases: BaseModel

Represents a templated message.

This class is used to create messages with dynamic content using a template. The template can be rendered with variables to produce the final message content.

property content: str

Renders the content of the message.

property message: Message

Returns the message in oumi format.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'role': FieldInfo(annotation=Role, required=True), 'template': FieldInfo(annotation=str, required=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

role: Role

The role of the message sender (e.g., USER, ASSISTANT, SYSTEM).

template: str

The template string used to generate the message content.

class oumi.core.types.Type(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Type of the message.

IMAGE_BINARY = 'image_binary'

Represents an image stored as binary data.

IMAGE_PATH = 'image_path'

Represents an image referenced by its file path.

IMAGE_URL = 'image_url'

Represents an image referenced by its URL.

TEXT = 'text'

Represents a text message.

__str__() → str

Return the string representation of the Type enum.

Returns:

The string value of the Type enum.

Return type:

str