Skip to content

base

A module for defining base classes for each completion type.

SparkChatCompletionMessages = RootModel[List[SparkChatCompletionMessage]] module-attribute

A root model representing a list of SparkChatCompletionMessage objects.

This model is used to represent an entire conversation or a series of messages in a chat completion context. It provides a convenient way to handle multiple messages as a single entity while maintaining Pydantic's validation and serialization capabilities.

Usage 
messages = SparkChatCompletionMessages(root=[
    SparkChatCompletionMessage(role="user", content="Hello"),
    SparkChatCompletionMessage(role="assistant", content="Hi there!")
])

SparkChatCompletionMessage

Bases: BaseModel

A Spark-serializable chat completion message that can be used for any role in a conversation.

This class provides a flexible structure for representing messages in a chat completion context, supporting various roles (user, assistant, system, tool) and additional attributes like image URLs and tool calls.

Attributes:

Name Type Description
role Literal['user', 'assistant', 'system', 'tool']

The role of the message sender.
content Optional[str]

The text content of the message.
image_urls Optional[List[ImageURLPD]]

List of image URLs associated with the message.
name Optional[str]

The name of the entity associated with the message.
tool_calls Optional[List[ChatCompletionMessageToolCallParamPD]]

Tool calls made in the message (for 'assistant' role).
tool_call_id Optional[str]

The ID of the tool call (for 'tool' role).
cache_control Optional[bool]

Whether to use Anthropic's prompt caching feature (beta).

The class provides methods to format the message for different roles and serialize it to OpenAI-compatible types.

Source code in spark_instructor/types/base.py 
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
class SparkChatCompletionMessage(BaseModel):
    """A Spark-serializable chat completion message that can be used for any role in a conversation.

    This class provides a flexible structure for representing messages in a chat completion context,
    supporting various roles (user, assistant, system, tool) and additional attributes like image URLs
    and tool calls.

    Attributes:
        role (Literal["user", "assistant", "system", "tool"]): The role of the message sender.
        content (Optional[str]): The text content of the message.
        image_urls (Optional[List[ImageURLPD]]): List of image URLs associated with the message.
        name (Optional[str]): The name of the entity associated with the message.
        tool_calls (Optional[List[ChatCompletionMessageToolCallParamPD]]): Tool calls made in the message (for 'assistant' role).
        tool_call_id (Optional[str]): The ID of the tool call (for 'tool' role).
        cache_control (Optional[bool]): Whether to use Anthropic's prompt caching feature (beta).

    The class provides methods to format the message for different roles and serialize it to OpenAI-compatible types.
    """  # noqa: E501

    role: Literal["user", "assistant", "system", "tool"] = Field("user", description="The role of the message.")
    content: Optional[str] = Field(None, description="The text content of the message.")
    image_urls: Optional[List[ImageURLPD]] = Field(None, description="The image urls of the message.")  # type: ignore
    name: Optional[str] = Field(None, description="The name of the relevant chat entity")
    tool_calls: Optional[List[ChatCompletionMessageToolCallParamPD]] = Field(  # type: ignore
        None, description="The tool calls of the message (`assistant` role only)"
    )
    tool_call_id: Optional[str] = Field(None, description="The tool call id of the message (`tool` role only).")
    cache_control: Optional[bool] = Field(None, description="Whether to use Anthropic cache control.")

    def content_formatted(self) -> List[Union[ChatCompletionContentPartTextParam, ChatCompletionContentPartImageParam]]:
        """Format the message content, including any images, into a list of content parts.

        This method prepares the message content for use in API calls, handling both text and image content.

        Returns:
            List[Union[ChatCompletionContentPartTextParam, ChatCompletionContentPartImageParam]]:
                A list of formatted content parts, including text and images.
        """
        results: List[Union[ChatCompletionContentPartTextParam, ChatCompletionContentPartImageParam]] = (
            []
            if not self.image_urls
            else [
                ChatCompletionContentPartImageParam(image_url=format_image_url_pd(image_url), type="image_url")
                for image_url in self.image_urls
            ]
        )
        if self.content:
            results.append(ChatCompletionContentPartTextParam(text=self.content, type="text"))
        return results

    def as_user(self, string_only: bool = False) -> ChatCompletionUserMessageParam:
        """Format the message as a user message.

        This method prepares the message for use as a user input in a chat completion.

        Args:
            string_only (bool): If True, return only the text content for messages with images.

        Returns:
            ChatCompletionUserMessageParam: The formatted user message.
        """
        if self.name:
            if string_only and self.content:
                return ChatCompletionUserMessageParam(content=self.content, role="user", name=self.name)
            return ChatCompletionUserMessageParam(content=self.content_formatted(), role="user", name=self.name)
        if string_only and self.content:
            return ChatCompletionUserMessageParam(content=self.content, role="user")
        return ChatCompletionUserMessageParam(content=self.content_formatted(), role="user")

    def as_assistant(self) -> ChatCompletionAssistantMessageParam:
        """Format the message as an assistant message.

        This method prepares the message for use as an assistant response in a chat completion,
        including any tool calls if present.

        Returns:
            ChatCompletionAssistantMessageParam: The formatted assistant message.
        """
        if self.name:
            if self.tool_calls:
                return ChatCompletionAssistantMessageParam(
                    content=self.content,
                    role="assistant",
                    name=self.name,
                    tool_calls=[call.model_dump() for call in self.tool_calls],  # type: ignore
                )
            return ChatCompletionAssistantMessageParam(content=self.content, role="assistant", name=self.name)
        if self.tool_calls:
            return ChatCompletionAssistantMessageParam(
                content=self.content,
                role="assistant",
                tool_calls=[call.model_dump() for call in self.tool_calls],  # type: ignore
            )
        return ChatCompletionAssistantMessageParam(content=self.content, role="assistant")

    def as_system(self) -> ChatCompletionSystemMessageParam:
        """Format the message as a system message.

        This method prepares the message for use as a system instruction in a chat completion.

        Returns:
            ChatCompletionSystemMessageParam: The formatted system message.

        Raises:
            AssertionError: If the content is empty.
        """
        assert self.content, "`content` must not be empty"
        if self.name:
            return ChatCompletionSystemMessageParam(content=self.content, role="system", name=self.name)
        return ChatCompletionSystemMessageParam(content=self.content, role="system")

    def as_tool(self) -> ChatCompletionToolMessageParam:
        """Format the message as a tool message.

        This method prepares the message for use as a tool response in a chat completion.

        Returns:
            ChatCompletionToolMessageParam: The formatted tool message.

        Raises:
            AssertionError: If either content or tool_call_id is empty.
        """
        assert self.content and self.tool_call_id, "`content` and `tool_call_id` must not be empty"
        return ChatCompletionToolMessageParam(content=self.content, role="tool", tool_call_id=self.tool_call_id)

    def __call__(self, *args, string_only: bool = False, **kwargs) -> ChatCompletionMessageParam:
        """Serialize the message to an OpenAI-compatible type.

        This method allows the object to be called directly, returning the appropriate
        message type based on the role.

        Args:
            string_only (bool): If True, return only the text content.
                The resulting user message will only have string content.
            *args: Variable length argument list.
            **kwargs: Arbitrary keyword arguments.

        Returns:
            ChatCompletionMessageParam: The serialized message in OpenAI-compatible format.
        """
        if self.role == "system":
            return self.as_system()
        if self.role == "user":
            return self.as_user(string_only=string_only)
        if self.role == "assistant":
            return self.as_assistant()
        return self.as_tool()

__call__(*args, string_only=False, **kwargs)

Serialize the message to an OpenAI-compatible type.

This method allows the object to be called directly, returning the appropriate message type based on the role.

Parameters:

Name Type Description Default
string_only bool

If True, return only the text content. The resulting user message will only have string content.

 False
*args

Variable length argument list.

 ()
**kwargs

Arbitrary keyword arguments.

 {}

Returns:

Name Type Description
ChatCompletionMessageParam ChatCompletionMessageParam

The serialized message in OpenAI-compatible format.
Source code in spark_instructor/types/base.py 
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def __call__(self, *args, string_only: bool = False, **kwargs) -> ChatCompletionMessageParam:
    """Serialize the message to an OpenAI-compatible type.

    This method allows the object to be called directly, returning the appropriate
    message type based on the role.

    Args:
        string_only (bool): If True, return only the text content.
            The resulting user message will only have string content.
        *args: Variable length argument list.
        **kwargs: Arbitrary keyword arguments.

    Returns:
        ChatCompletionMessageParam: The serialized message in OpenAI-compatible format.
    """
    if self.role == "system":
        return self.as_system()
    if self.role == "user":
        return self.as_user(string_only=string_only)
    if self.role == "assistant":
        return self.as_assistant()
    return self.as_tool()

as_assistant()

Format the message as an assistant message.

This method prepares the message for use as an assistant response in a chat completion, including any tool calls if present.

Returns:

Name Type Description
ChatCompletionAssistantMessageParam ChatCompletionAssistantMessageParam

The formatted assistant message.
Source code in spark_instructor/types/base.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def as_assistant(self) -> ChatCompletionAssistantMessageParam:
    """Format the message as an assistant message.

    This method prepares the message for use as an assistant response in a chat completion,
    including any tool calls if present.

    Returns:
        ChatCompletionAssistantMessageParam: The formatted assistant message.
    """
    if self.name:
        if self.tool_calls:
            return ChatCompletionAssistantMessageParam(
                content=self.content,
                role="assistant",
                name=self.name,
                tool_calls=[call.model_dump() for call in self.tool_calls],  # type: ignore
            )
        return ChatCompletionAssistantMessageParam(content=self.content, role="assistant", name=self.name)
    if self.tool_calls:
        return ChatCompletionAssistantMessageParam(
            content=self.content,
            role="assistant",
            tool_calls=[call.model_dump() for call in self.tool_calls],  # type: ignore
        )
    return ChatCompletionAssistantMessageParam(content=self.content, role="assistant")

as_system()

Format the message as a system message.

This method prepares the message for use as a system instruction in a chat completion.

Returns:

Name Type Description
ChatCompletionSystemMessageParam ChatCompletionSystemMessageParam

The formatted system message.

Raises:

Type Description
AssertionError

If the content is empty.
Source code in spark_instructor/types/base.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
def as_system(self) -> ChatCompletionSystemMessageParam:
    """Format the message as a system message.

    This method prepares the message for use as a system instruction in a chat completion.

    Returns:
        ChatCompletionSystemMessageParam: The formatted system message.

    Raises:
        AssertionError: If the content is empty.
    """
    assert self.content, "`content` must not be empty"
    if self.name:
        return ChatCompletionSystemMessageParam(content=self.content, role="system", name=self.name)
    return ChatCompletionSystemMessageParam(content=self.content, role="system")

as_tool()

Format the message as a tool message.

This method prepares the message for use as a tool response in a chat completion.

Returns:

Name Type Description
ChatCompletionToolMessageParam ChatCompletionToolMessageParam

The formatted tool message.

Raises:

Type Description
AssertionError

If either content or tool_call_id is empty.
Source code in spark_instructor/types/base.py 
152
153
154
155
156
157
158
159
160
161
162
163
164
def as_tool(self) -> ChatCompletionToolMessageParam:
    """Format the message as a tool message.

    This method prepares the message for use as a tool response in a chat completion.

    Returns:
        ChatCompletionToolMessageParam: The formatted tool message.

    Raises:
        AssertionError: If either content or tool_call_id is empty.
    """
    assert self.content and self.tool_call_id, "`content` and `tool_call_id` must not be empty"
    return ChatCompletionToolMessageParam(content=self.content, role="tool", tool_call_id=self.tool_call_id)

as_user(string_only=False)

Format the message as a user message.

This method prepares the message for use as a user input in a chat completion.

Parameters:

Name Type Description Default
string_only bool

If True, return only the text content for messages with images.

 False

Returns:

Name Type Description
ChatCompletionUserMessageParam ChatCompletionUserMessageParam

The formatted user message.
Source code in spark_instructor/types/base.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def as_user(self, string_only: bool = False) -> ChatCompletionUserMessageParam:
    """Format the message as a user message.

    This method prepares the message for use as a user input in a chat completion.

    Args:
        string_only (bool): If True, return only the text content for messages with images.

    Returns:
        ChatCompletionUserMessageParam: The formatted user message.
    """
    if self.name:
        if string_only and self.content:
            return ChatCompletionUserMessageParam(content=self.content, role="user", name=self.name)
        return ChatCompletionUserMessageParam(content=self.content_formatted(), role="user", name=self.name)
    if string_only and self.content:
        return ChatCompletionUserMessageParam(content=self.content, role="user")
    return ChatCompletionUserMessageParam(content=self.content_formatted(), role="user")

content_formatted()

Format the message content, including any images, into a list of content parts.

This method prepares the message content for use in API calls, handling both text and image content.

Returns:

Type Description
List[Union[ChatCompletionContentPartTextParam, ChatCompletionContentPartImageParam]]

List[Union[ChatCompletionContentPartTextParam, ChatCompletionContentPartImageParam]]: A list of formatted content parts, including text and images.
Source code in spark_instructor/types/base.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def content_formatted(self) -> List[Union[ChatCompletionContentPartTextParam, ChatCompletionContentPartImageParam]]:
    """Format the message content, including any images, into a list of content parts.

    This method prepares the message content for use in API calls, handling both text and image content.

    Returns:
        List[Union[ChatCompletionContentPartTextParam, ChatCompletionContentPartImageParam]]:
            A list of formatted content parts, including text and images.
    """
    results: List[Union[ChatCompletionContentPartTextParam, ChatCompletionContentPartImageParam]] = (
        []
        if not self.image_urls
        else [
            ChatCompletionContentPartImageParam(image_url=format_image_url_pd(image_url), type="image_url")
            for image_url in self.image_urls
        ]
    )
    if self.content:
        results.append(ChatCompletionContentPartTextParam(text=self.content, type="text"))
    return results

format_image_url_pd(image_url_pd)

Format the ImageURLPD object into an ImageURL object.

Source code in spark_instructor/types/base.py 
33
34
35
36
37
38
def format_image_url_pd(image_url_pd: BaseModel) -> ImageURL:
    """Format the ImageURLPD object into an ImageURL object."""
    model_dump = image_url_pd.model_dump()
    if not model_dump["detail"]:
        return ImageURL(url=model_dump["url"])
    return ImageURL(url=model_dump["url"], detail=model_dump["detail"])