Documentation
¶
Overview ¶
Package messages provides types and functionality for handling multi-part message content in different formats including text, images, and audio.
Package messages provides a flexible system for handling multi-format message content in AI agent communications. It implements a type-safe, extensible architecture for representing and manipulating messages that can contain text, images, audio, and specialized content types like refusal messages.
Design decisions:
- Type safety: Generic message types ensure compile-time type checking
- Flexible content: Support for both simple string content and complex multi-part messages
- Extensible: Easy to add new content types by implementing ContentPart interface
- JSON interop: Full JSON serialization support with robust error handling
- Memory efficiency: Uses struct{} padding to enforce keyed initialization
- Clear separation: Different content types for user input vs assistant responses
Key concepts:
- ContentOrParts: Represents user messages that can be either simple text or multi-part content (text, images, audio)
- AssistantContentOrParts: Specialized content type for assistant responses, supporting text and refusal messages
- ContentPart: Interface for implementing new content types
- AssistantContentPart: Interface for assistant-specific content types
Example usage:
// Simple text message
msg := messages.ContentOrParts{Content: "Hello, world!"}
// Multi-part message with text and image
msg := messages.ContentOrParts{
Parts: []messages.ContentPart{
messages.Text("Check out this image:"),
messages.Image("https://example.com/image.jpg"),
},
}
// Assistant response with refusal
resp := messages.AssistantContentOrParts{
Parts: []messages.AssistantContentPart{
messages.Refusal("I cannot process that request"),
},
}
The package is designed to be used as part of a larger AI agent system, providing the foundational types needed for structured communication between users and AI agents. It handles serialization details and provides a clean API for working with different types of content.
Package messages provides a messaging system for handling various types of communication between different parts of the application. It includes support for user messages, assistant messages, tool calls, and responses.
Index ¶
- func New() messageBuilder
- type AssistantContentOrParts
- type AssistantContentPart
- type AssistantMessage
- type AudioContentPart
- type ContentOrParts
- type ContentPart
- type ImageContentPart
- type InputAudio
- type InstructionsMessage
- type Message
- type ModelMessage
- type RefusalContentPart
- type Request
- type Response
- type Retry
- type TextContentPart
- type ToolCallData
- type ToolCallMessage
- type ToolResponse
- type UserMessage
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type AssistantContentOrParts ¶
type AssistantContentOrParts struct {
Content string // Raw string content for simple text responses
Parts []AssistantContentPart // Slice of assistant-specific content parts
Refusal string
// contains filtered or unexported fields
}
AssistantContentOrParts represents content that can be either a simple string or a collection of assistant-specific content parts (text or refusal).
func (AssistantContentOrParts) MarshalJSON ¶
func (c AssistantContentOrParts) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler interface for AssistantContentOrParts. Returns the Content as a JSON string if it's non-empty, otherwise returns the Parts as a JSON array. Returns null if both Content and Parts are empty.
func (*AssistantContentOrParts) UnmarshalJSON ¶
func (c *AssistantContentOrParts) UnmarshalJSON(input []byte) error
UnmarshalJSON implements json.Unmarshaler interface for AssistantContentOrParts. Handles both string content and arrays of assistant-specific content parts (text, refusal). Returns an error if the JSON is invalid or contains unknown content part types.
type AssistantContentPart ¶
type AssistantContentPart interface {
// contains filtered or unexported methods
}
AssistantContentPart is an interface that marks structs as valid assistant content parts. Implementations include TextContentPart and RefusalContentPart.
type AssistantMessage ¶
type AssistantMessage struct {
Content AssistantContentOrParts `json:"content,omitempty"`
Refusal string `json:"refusal,omitempty"`
// contains filtered or unexported fields
}
AssistantMessage represents a response from the assistant. It can contain content, multiple content parts, or a refusal message.
func (AssistantMessage) MarshalJSON ¶
func (a AssistantMessage) MarshalJSON() ([]byte, error)
MarshalJSON implements custom JSON marshaling for AssistantMessage
func (*AssistantMessage) UnmarshalJSON ¶
func (a *AssistantMessage) UnmarshalJSON(data []byte) error
UnmarshalJSON implements custom JSON unmarshaling for AssistantMessage
type AudioContentPart ¶
type AudioContentPart struct {
InputAudio InputAudio `json:"input_audio"` // Audio data and format information
// contains filtered or unexported fields
}
AudioContentPart represents an audio content part. It implements the ContentPart interface.
func (AudioContentPart) MarshalJSON ¶
func (i AudioContentPart) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler interface for AudioContentPart. Serializes the audio input data and format with a "type":"audio" field.
func (*AudioContentPart) UnmarshalJSON ¶
func (i *AudioContentPart) UnmarshalJSON(input []byte) error
UnmarshalJSON implements json.Unmarshaler interface for AudioContentPart. Validates and extracts the required 'input_audio' object containing 'data' and 'format' fields.
type ContentOrParts ¶
type ContentOrParts struct {
Content string // Raw string content, used when the message is just text
Parts []ContentPart // Slice of different content parts (text, image, audio)
// contains filtered or unexported fields
}
ContentOrParts represents either a simple string content or a collection of content parts. It provides flexible serialization to handle both single-string messages and multi-part content.
func (ContentOrParts) MarshalJSON ¶
func (c ContentOrParts) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler interface for ContentOrParts. Returns the Content as a JSON string if it's non-empty, otherwise returns the Parts as a JSON array. Returns null if both Content and Parts are empty.
func (*ContentOrParts) UnmarshalJSON ¶
func (c *ContentOrParts) UnmarshalJSON(input []byte) error
UnmarshalJSON implements json.Unmarshaler interface for ContentOrParts. Handles both string content and arrays of different content part types (text, image, audio). Returns an error if the JSON is invalid or contains unknown content part types.
type ContentPart ¶
type ContentPart interface {
// contains filtered or unexported methods
}
ContentPart is an interface that marks structs as valid content parts. Implementations include TextContentPart, ImageContentPart, and AudioContentPart.
func Audio ¶
func Audio(data []byte, format string) ContentPart
Audio creates a new AudioContentPart with the provided raw audio data and format. The format parameter should specify the audio encoding format (e.g., "wav", "mp3"). This is a convenience function for creating audio content parts.
type ImageContentPart ¶
type ImageContentPart struct {
URL string `json:"image_url"` // URL pointing to the image
Detail string `json:"detail"`
// contains filtered or unexported fields
}
ImageContentPart represents an image content part with a URL. It implements the ContentPart interface.
func Image ¶
func Image(url string) ImageContentPart
Image creates a new ImageContentPart with the given URL. This is a convenience function for creating image content parts.
func (ImageContentPart) MarshalJSON ¶
func (i ImageContentPart) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler interface for ImageContentPart. Serializes the image URL with a "type":"image" field.
func (*ImageContentPart) UnmarshalJSON ¶
func (i *ImageContentPart) UnmarshalJSON(input []byte) error
UnmarshalJSON implements json.Unmarshaler interface for ImageContentPart. Validates and extracts the required 'image_url' field from the JSON input.
type InputAudio ¶
type InputAudio struct {
Data []byte `json:"-"` // Raw audio data
Format string `json:"format"` // Audio format specification
// contains filtered or unexported fields
}
InputAudio contains the data and format information for audio content.
func (InputAudio) MarshalJSON ¶
func (i InputAudio) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler interface for InputAudio. Encodes the Data field as base64 in the JSON output.
func (*InputAudio) UnmarshalJSON ¶
func (i *InputAudio) UnmarshalJSON(data []byte) error
UnmarshalJSON implements json.Unmarshaler interface for InputAudio. Decodes the base64 encoded data field from JSON into the Data byte slice.
type InstructionsMessage ¶
type InstructionsMessage struct {
Content string `json:"content"`
// contains filtered or unexported fields
}
InstructionsMessage represents system-level instructions. It contains content that provides guidance or directives to the system.
func (InstructionsMessage) MarshalJSON ¶
func (i InstructionsMessage) MarshalJSON() ([]byte, error)
MarshalJSON implements custom JSON marshaling for InstructionsMessage
func (*InstructionsMessage) UnmarshalJSON ¶
func (i *InstructionsMessage) UnmarshalJSON(data []byte) error
UnmarshalJSON implements custom JSON unmarshaling for InstructionsMessage
type Message ¶
type Message[T ModelMessage] struct { RunID uuid.UUID `json:"run_id,omitempty"` // ID of the run this message belongs to TurnID uuid.UUID `json:"turn_id,omitempty"` // ID of the turn this message belongs to Payload T `json:",inline"` Sender string `json:"sender,omitempty"` Timestamp strfmt.DateTime `json:"timestamp,omitempty"` Meta gjson.Result `json:"meta,omitempty"` // Additional metadata that can be attached to any message type }
Message is a generic container for all message types in the system. It includes common metadata like sender and timestamp alongside the specific message payload.
func (Message[T]) MarshalJSON ¶
MarshalJSON implements custom JSON marshaling for Message[T]
func (*Message[T]) UnmarshalJSON ¶
UnmarshalJSON implements custom JSON unmarshaling for Message[T]
type ModelMessage ¶
type ModelMessage interface {
// contains filtered or unexported methods
}
ModelMessage is a marker interface that all message types must implement. It ensures type safety for message handling throughout the application.
type RefusalContentPart ¶
type RefusalContentPart struct {
Refusal string `json:"refusal"` // The refusal message text
// contains filtered or unexported fields
}
RefusalContentPart represents a content part indicating a refusal message. It implements the AssistantContentPart interface.
func Refusal ¶
func Refusal(reason string) RefusalContentPart
Refusal creates a new RefusalContentPart with the given reason. This is a convenience function for creating refusal messages.
func (RefusalContentPart) MarshalJSON ¶
func (t RefusalContentPart) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler interface for RefusalContentPart. Serializes the refusal content with a "type":"refusal" field.
func (*RefusalContentPart) UnmarshalJSON ¶
func (t *RefusalContentPart) UnmarshalJSON(input []byte) error
UnmarshalJSON implements json.Unmarshaler interface for RefusalContentPart. Validates and extracts the required 'refusal' field from the JSON input.
type Request ¶
type Request interface {
// contains filtered or unexported methods
}
Request is a marker interface that identifies messages that can be used as requests in the system. This includes user messages and tool responses.
type Response ¶
type Response interface {
// contains filtered or unexported methods
}
Response is a marker interface that identifies messages that can be used as responses in the system. This includes assistant messages and tool calls.
type Retry ¶
type Retry struct {
Error error `json:"error"`
ToolName string `json:"tool_name,omitempty"`
ToolCallID string `json:"tool_call_id,omitempty"`
// contains filtered or unexported fields
}
Retry represents a failed tool execution that may need to be retried. It includes error information and details about the failed tool call.
func (Retry) MarshalJSON ¶
MarshalJSON implements custom JSON marshaling for Retry
func (*Retry) UnmarshalJSON ¶
UnmarshalJSON implements custom JSON unmarshaling for Retry
type TextContentPart ¶
type TextContentPart struct {
Text string `json:"text"` // The actual text content
// contains filtered or unexported fields
}
TextContentPart represents a text-only content part. It implements both ContentPart and AssistantContentPart interfaces.
func Text ¶
func Text(text string) TextContentPart
Text creates a new TextContentPart with the given text. This is a convenience function for creating text content parts.
func (TextContentPart) MarshalJSON ¶
func (t TextContentPart) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler interface for TextContentPart. Serializes the text content with a "type":"text" field.
func (*TextContentPart) UnmarshalJSON ¶
func (t *TextContentPart) UnmarshalJSON(input []byte) error
UnmarshalJSON implements json.Unmarshaler interface for TextContentPart. Validates and extracts the required 'text' field from the JSON input.
type ToolCallData ¶
type ToolCallData struct {
ID string `json:"id"`
Name string `json:"name"`
Arguments string `json:"arguments"`
// contains filtered or unexported fields
}
ToolCallData contains the information needed to execute a tool. It includes the tool name and its arguments as a JSON string.
type ToolCallMessage ¶
type ToolCallMessage struct {
ToolCalls []ToolCallData `json:"tool_calls"`
// contains filtered or unexported fields
}
ToolCallMessage represents a request to execute one or more tools.
func (ToolCallMessage) MarshalJSON ¶
func (t ToolCallMessage) MarshalJSON() ([]byte, error)
func (*ToolCallMessage) UnmarshalJSON ¶
func (t *ToolCallMessage) UnmarshalJSON(data []byte) error
UnmarshalJSON implements custom JSON unmarshaling for ToolCallMessage
type ToolResponse ¶
type ToolResponse struct {
ToolName string `json:"tool_name"`
ToolCallID string `json:"tool_call_id"`
Content string `json:"content"`
// contains filtered or unexported fields
}
ToolResponse represents the successful result of a tool execution. It includes the tool name, call ID, and the execution result.
func (ToolResponse) MarshalJSON ¶
func (t ToolResponse) MarshalJSON() ([]byte, error)
MarshalJSON implements custom JSON marshaling for ToolResponse
func (*ToolResponse) UnmarshalJSON ¶
func (t *ToolResponse) UnmarshalJSON(data []byte) error
UnmarshalJSON implements custom JSON unmarshaling for ToolResponse
type UserMessage ¶
type UserMessage struct {
Content ContentOrParts `json:"content"`
// contains filtered or unexported fields
}
UserMessage represents a message from a user. It can contain either simple text content or multiple content parts.
func (UserMessage) MarshalJSON ¶
func (u UserMessage) MarshalJSON() ([]byte, error)
MarshalJSON implements custom JSON marshaling for UserMessage
func (*UserMessage) UnmarshalJSON ¶
func (u *UserMessage) UnmarshalJSON(data []byte) error
UnmarshalJSON implements custom JSON unmarshaling for UserMessage
Source Files