Class: LLM::Message

Inherits:
Object
  • Object
show all
Defined in:
lib/llm/message.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(role, content, extra = {}) ⇒ LLM::Message

Returns a new message

Parameters:

  • role (Symbol)
  • content (String)
  • extra (Hash) (defaults to: {}) 


32
33
34
35
36
37
 
# File 'lib/llm/message.rb', line 32

def initialize(role, content, extra = {})
  @content = content
  @role = normalize_role(role)
  @extra = LLM::Object.from(extra)
  @id = extra[:id] || SecureRandom.uuid_v7
end

Instance Attribute Details

#role ⇒ Symbol (readonly)

Returns the role of the message

Returns:

  • (Symbol) 


8
9
10
 
# File 'lib/llm/message.rb', line 8

def role
  @role
end

#content ⇒ String (readonly)

Returns the content of the message

Returns:

  • (String) 


13
14
15
 
# File 'lib/llm/message.rb', line 13

def content
  @content
end

#extra ⇒ Hash (readonly)

Returns extra context associated with the message

Returns:

  • (Hash) 


18
19
20
 
# File 'lib/llm/message.rb', line 18

def extra
  @extra
end

#id ⇒ String (readonly)

Returns a stable id for this message. It is generated once on creation and restored with the runtime state on load.

Returns:

  • (String) 


24
25
26
 
# File 'lib/llm/message.rb', line 24

def id
  @id
end

Instance Method Details

#inspect ⇒ String

Returns a string representation of the message

Returns:

  • (String) 


252
253
254
255
256
 
# File 'lib/llm/message.rb', line 252

def inspect
  "#<#{LLM::Utils.object_id(self)} " \
  "tool_call=#{tool_calls.any?} role=#{role.inspect} " \
  "content=#{content.inspect} reasoning_content=#{reasoning_content.inspect}>"
end

#created_at ⇒ Time?

Returns the time this message was created, derived from the timestamp embedded in its UUIDv7 id, or nil when it is not.

Returns:

  • (Time, nil) 


43
44
45
 
# File 'lib/llm/message.rb', line 43

def created_at
  @created_at ||= LLM::Utils.timestamp(@id)
end

#to_h ⇒ Hash

Returns a Hash representation of the message.

This is the whole of a message as far as storage is concerned: Context#to_h maps its messages through here, and restore reads them back from the same list. A field that is not named here does not survive a save, so a field the runtime relies on after a restore has to be named.

Tool calls are stored in the abstract form the runtime reasons about - {id, name, arguments} - and never in a provider's wire form. Each request adapter builds its own blocks from that form, which is what lets a conversation saved under one provider be restored under another.

Returns:

  • (Hash) 


62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/llm/message.rb', line 62

def to_h
  {
    id: @id,
    role:,
    content:,
    reasoning_content:,
    compaction: extra.compaction,
    instructions: extra.instructions,
    tools: extra.tool_calls&.map { LLM::Object === _1 ? _1.to_h : _1 },
    usage:
  }.compact.then { preserve_nil_content(_1) }
end

#to_json ⇒ String

Returns:

  • (String) 


77
78
79
 
# File 'lib/llm/message.rb', line 77

def to_json(...)
  LLM.json.dump(to_h, ...)
end

#==(other) ⇒ Boolean Also known as: eql?

Returns true when two objects have the same role and content. The id is ignored, because it identifies a message rather than describing it.

Parameters:

  • other (Object) —

    The other object to compare

Returns:

  • (Boolean) 


88
89
90
91
92
93
94
 
# File 'lib/llm/message.rb', line 88

def ==(other)
  if other.respond_to?(:to_h)
    to_h.except(:id) == other.to_h.except(:id)
  else
    false
  end
end

#contents ⇒ Array<LLM::Function::Return, String>

Returns:



99
100
101
 
# File 'lib/llm/message.rb', line 99

def contents
  [*content].flatten
end

#content! ⇒ Hash

Try to parse JSON content

Returns:

  • (Hash) —

    Returns the parsed content as a Hash



107
108
109
 
# File 'lib/llm/message.rb', line 107

def content!
  LLM.json.load(content)
end

#reasoning_content ⇒ String?

Returns reasoning content associated with the message

Returns:

  • (String, nil) 


114
115
116
 
# File 'lib/llm/message.rb', line 114

def reasoning_content
  extra.reasoning_content
end

#compaction? ⇒ Boolean

Returns true when a message was created by context compaction

Returns:

  • (Boolean) 


121
122
123
 
# File 'lib/llm/message.rb', line 121

def compaction?
  !!extra.compaction
end

#image_url? ⇒ Boolean

Returns true when a message contains an image URL

Returns:

  • (Boolean) 


128
129
130
 
# File 'lib/llm/message.rb', line 128

def image_url?
  image_urls.any?
end

#image_urls ⇒ Array<LLM::Object>

Returns image URL content items from the message

Returns:



135
136
137
 
# File 'lib/llm/message.rb', line 135

def image_urls
  contents.select { LLM::Object === it and it.kind == :image_url }
end

#file? ⇒ Boolean

Returns true when a message contains a local or remote file

Returns:

  • (Boolean) 


142
143
144
 
# File 'lib/llm/message.rb', line 142

def file?
  files.any?
end

#files ⇒ Array<LLM::Object>

Returns local and remote file content items from the message

Returns:



149
150
151
152
 
# File 'lib/llm/message.rb', line 149

def files
  kinds = [:local_file, :remote_file]
  contents.select { LLM::Object === it and kinds.include?(it.kind) }
end

#functions ⇒ Array<LLM::Function>

Returns:



156
157
158
159
160
161
162
163
 
# File 'lib/llm/message.rb', line 156

def functions
  @functions ||= tool_calls.filter_map do |fn|
    function = available_tools.find { _1.name.to_s == fn.name } || LLM::Tool::NotFound(name: fn.name)
    function = function.dup
    function.tap { _1.id = fn.id }
    function.tap { _1.arguments = fn.arguments }
  end
end

#assistant? ⇒ Boolean

Returns true when the message is an assistant message

Returns:

  • (Boolean) 


168
169
170
 
# File 'lib/llm/message.rb', line 168

def assistant?
  role == "assistant" || role == "model"
end

#system? ⇒ Boolean

Returns true when the message is a system message

Returns:

  • (Boolean) 


175
176
177
 
# File 'lib/llm/message.rb', line 175

def system?
  role == "system"
end

#user? ⇒ Boolean

Returns true when the message is a user message

Returns:

  • (Boolean) 


182
183
184
 
# File 'lib/llm/message.rb', line 182

def user?
  role == "user"
end

#tool_call? ⇒ Boolean

Returns true when the message requests a function call

Returns:

  • (Boolean) —

    Returns true when the message requests a function call



189
190
191
 
# File 'lib/llm/message.rb', line 189

def tool_call?
  tool_calls.any?
end

#tool_return? ⇒ Boolean

Returns true when the message represents a function return

Returns:

  • (Boolean) —

    Returns true when the message represents a function return



196
197
198
 
# File 'lib/llm/message.rb', line 196

def tool_return?
  returns.size > 0
end

#returns ⇒ Array<LLM::Function::Return>

Returns:



202
203
204
205
206
207
208
 
# File 'lib/llm/message.rb', line 202

def returns
  if LLM::Function::Return === content
    [content]
  else
    [*content].flatten.grep(LLM::Function::Return)
  end
end

#response ⇒ LLM::Response?

Note:

This method returns a response for assistant messages, and it returns nil for non-assistant messages

Returns the response associated with the message, or nil

Returns:

  • (LLM::Response, nil) —

    Returns the response associated with the message, or nil



216
217
218
 
# File 'lib/llm/message.rb', line 216

def response
  extra.response
end

#annotations ⇒ Array<LLM::Object>

Note:

This method might return annotations for assistant messages, and it returns an empty array for non-assistant messages

Returns annotations associated with the message

Returns:



226
227
228
 
# File 'lib/llm/message.rb', line 226

def annotations
  @annotations ||= LLM::Object.from(extra.annotations || [])
end

#token_usage ⇒ LLM::Usage? Also known as: usage

Note:

This method returns token usage for assistant messages, and it returns nil for non-assistant messages

Returns token usage statistics

Returns:



236
237
238
239
 
# File 'lib/llm/message.rb', line 236

def token_usage
  return nil unless assistant?
  @token_usage ||= LLM::Usage.from(extra.usage || response&.usage)
end

#model ⇒ String?

Returns the model associated with a message

Returns:

  • (String, nil) —

    Returns the model associated with a message



245
246
247
 
# File 'lib/llm/message.rb', line 245

def model
  response&.model
end