Class: Ask::Message

Inherits:
Object
  • Object
show all
Defined in:
lib/ask/conversation.rb

Overview

A single message in a conversation. Immutable after creation. Valid roles are: :system, :user, :assistant, :tool.

Constant Summary collapse

VALID_ROLES = 
%i[system user assistant tool].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(role:, content: nil, name: nil, tool_call_id: nil, tool_calls: nil, metadata: {}) ⇒ Message

Returns a new instance of Message.



27
28
29
30
31
32
33
34
35
36
 
# File 'lib/ask/conversation.rb', line 27

def initialize(role:, content: nil, name: nil, tool_call_id: nil, tool_calls: nil, metadata: {})
  @role = normalize_role!(role)
  @content = content
  @name = normalize_name(name)
  @tool_call_id = tool_call_id
  @tool_calls = tool_calls
  @metadata = metadata.dup.freeze
  validate!
  freeze
end

Instance Attribute Details

#content ⇒ String? (readonly)

Returns message text content.

Returns:

  • (String, nil) —

    message text content



13
14
15
 
# File 'lib/ask/conversation.rb', line 13

def content
  @content
end

#metadata ⇒ Hash (readonly)

Returns arbitrary metadata attached to this message.

Returns:

  • (Hash) —

    arbitrary metadata attached to this message



25
26
27
 
# File 'lib/ask/conversation.rb', line 25

def metadata
  @metadata
end

#name ⇒ String? (readonly)

Returns optional participant name (for multi-agent scenarios).

Returns:

  • (String, nil) —

    optional participant name (for multi-agent scenarios)



16
17
18
 
# File 'lib/ask/conversation.rb', line 16

def name
  @name
end

#role ⇒ Symbol (readonly)

Returns message role (:system, :user, :assistant, :tool).

Returns:

  • (Symbol) —

    message role (:system, :user, :assistant, :tool)



10
11
12
 
# File 'lib/ask/conversation.rb', line 10

def role
  @role
end

#tool_call_id ⇒ String? (readonly)

Returns tool call ID this message is responding to.

Returns:

  • (String, nil) —

    tool call ID this message is responding to



19
20
21
 
# File 'lib/ask/conversation.rb', line 19

def tool_call_id
  @tool_call_id
end

#tool_calls ⇒ Array<Hash>? (readonly)

Returns tool calls included in this message.

Returns:

  • (Array<Hash>, nil) —

    tool calls included in this message



22
23
24
 
# File 'lib/ask/conversation.rb', line 22

def tool_calls
  @tool_calls
end

Instance Method Details

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

Returns true if role, content, name, and tool metadata all match.

Returns:

  • (Boolean) —

    true if role, content, name, and tool metadata all match



102
103
104
105
106
107
108
 
# File 'lib/ask/conversation.rb', line 102

def ==(other)
  return false unless other.is_a?(Message)

  @role == other.role && @content == other.content &&
    @name == other.name && @tool_call_id == other.tool_call_id &&
    @tool_calls == other.tool_calls
end

#assistant? ⇒ Boolean

Returns true if role is :assistant.

Returns:

  • (Boolean) —

    true if role is :assistant



51
 
# File 'lib/ask/conversation.rb', line 51

def assistant? = @role == :assistant

#hash ⇒ Object 



111
112
113
 
# File 'lib/ask/conversation.rb', line 111

def hash
  [@role, @content, @name, @tool_call_id, @tool_calls].hash
end

#inspect ⇒ String

Returns:

  • (String) 


116
117
118
 
# File 'lib/ask/conversation.rb', line 116

def inspect
  "#<Ask::Message role=#{@role.inspect} content=#{@content && @content.length > 57 ? @content[0,57].inspect + "..." : @content.inspect}>"
end

#system? ⇒ Boolean

Returns true if role is :system.

Returns:

  • (Boolean) —

    true if role is :system



45
 
# File 'lib/ask/conversation.rb', line 45

def system? = @role == :system

#to_h ⇒ Hash

Convert to a hash suitable for provider wire format serialization. Omits nil-valued keys. Tool calls are converted from internal Hash format (=> object with .id, .name, .arguments) to the provider API Array format ([type:, function: {name:, arguments:}]).

Returns:

  • (Hash) 


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
 
# File 'lib/ask/conversation.rb', line 61

def to_h
  base = { role: @role }
  base[:content] = @content if @content
  base[:name] = @name if @name
  base[:tool_call_id] = @tool_call_id if @tool_call_id

  if @tool_calls
    base[:tool_calls] = @tool_calls.is_a?(Array) ? @tool_calls : @tool_calls.map do |id_val, tc|
      tc_id = if tc.respond_to?(:id)
        tc.id
      elsif tc.is_a?(Hash)
        tc[:id] || tc["id"] || id_val
      else
        id_val
      end

      tc_name = if tc.respond_to?(:name)
        tc.name
      elsif tc.is_a?(Hash)
        tc.dig(:function, :name) || tc.dig("function", "name") || tc[:name] || tc["name"] || id_val
      else
        id_val
      end

      tc_args = if tc.respond_to?(:arguments)
        tc.arguments.is_a?(String) ? tc.arguments : JSON.generate(tc.arguments)
      elsif tc.is_a?(Hash)
        raw = tc.dig(:function, :arguments) || tc.dig("function", "arguments") || tc[:arguments] || tc["arguments"] || "{}"
        raw.is_a?(String) ? raw : JSON.generate(raw)
      else
        "{}"
      end

      { id: tc_id, type: "function", function: { name: tc_name, arguments: tc_args } }
    end
  end

  base
end

#tool? ⇒ Boolean

Returns true if role is :tool.

Returns:

  • (Boolean) —

    true if role is :tool



54
 
# File 'lib/ask/conversation.rb', line 54

def tool? = @role == :tool

#tool_call? ⇒ Boolean

Returns true if this message contains tool calls.

Returns:

  • (Boolean) —

    true if this message contains tool calls



39
 
# File 'lib/ask/conversation.rb', line 39

def tool_call? = @tool_calls&.any? == true

#tool_result? ⇒ Boolean

Returns true if this is a tool result message.

Returns:

  • (Boolean) —

    true if this is a tool result message



42
 
# File 'lib/ask/conversation.rb', line 42

def tool_result? = !@tool_call_id.nil?

#user? ⇒ Boolean

Returns true if role is :user.

Returns:

  • (Boolean) —

    true if role is :user



48
 
# File 'lib/ask/conversation.rb', line 48

def user? = @role == :user