Class: Legion::Extensions::Llm::Canonical::Request

Inherits:
Data
  • Object
show all
Defined in:
lib/legion/extensions/llm/canonical/request.rb

Overview

Canonical request shape — the single contract between client translators and the inference executor. Per R3 and G18.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#caller ⇒ Object (readonly)

Returns the value of attribute caller

Returns:

  • (Object) —

    the current value of caller



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 12

def caller
  @caller
end

#conversation_id ⇒ Object (readonly)

Returns the value of attribute conversation_id

Returns:

  • (Object) —

    the current value of conversation_id



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 12

def conversation_id
  @conversation_id
end

#id ⇒ Object (readonly)

Returns the value of attribute id

Returns:

  • (Object) —

    the current value of id



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 12

def id
  @id
end

#messages ⇒ Object (readonly)

Returns the value of attribute messages

Returns:

  • (Object) —

    the current value of messages



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 12

def messages
  @messages
end

#metadata ⇒ Object (readonly)

Returns the value of attribute metadata

Returns:

  • (Object) —

    the current value of metadata



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 12

def metadata
  @metadata
end

#params ⇒ Object (readonly)

Returns the value of attribute params

Returns:

  • (Object) —

    the current value of params



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 12

def params
  @params
end

#routing ⇒ Object (readonly)

Returns the value of attribute routing

Returns:

  • (Object) —

    the current value of routing



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 12

def routing
  @routing
end

#stream ⇒ Object (readonly)

Returns the value of attribute stream

Returns:

  • (Object) —

    the current value of stream



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 12

def stream
  @stream
end

#system ⇒ Object (readonly)

Returns the value of attribute system

Returns:

  • (Object) —

    the current value of system



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 12

def system
  @system
end

#thinking ⇒ Object (readonly)

Returns the value of attribute thinking

Returns:

  • (Object) —

    the current value of thinking



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 12

def thinking
  @thinking
end

#tool_choice ⇒ Object (readonly)

Returns the value of attribute tool_choice

Returns:

  • (Object) —

    the current value of tool_choice



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 12

def tool_choice
  @tool_choice
end

#tools ⇒ Object (readonly)

Returns the value of attribute tools

Returns:

  • (Object) —

    the current value of tools



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 12

def tools
  @tools
end

Class Method Details

.build(id: nil, messages: nil, system: nil, tools: nil, tool_choice: nil, params: nil, thinking: nil, stream: false, conversation_id: nil, caller: nil, routing: nil, metadata: nil) ⇒ Object

Build from keyword args (primary constructor).



18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 18

def self.build(
  id: nil, messages: nil, system: nil, tools: nil, tool_choice: nil,
  params: nil, thinking: nil, stream: false,
  conversation_id: nil, caller: nil, routing: nil, metadata: nil
)
  # Normalize messages to Canonical::Message array
  msg_array = Array(messages).filter_map do |msg|
    msg.is_a?(Message) ? msg : Message.from_hash(msg)
  end

  # Normalize tools to Hash<name, ToolDefinition>
  tool_hash = normalize_tools(tools)

  # Normalize params
  params_obj = case params
               when Params then params
               when Hash then Params.from_hash(params)
               end

  # Normalize thinking config
  thinking_obj = case thinking
                 when Thinking::Config then thinking
                 when Hash then Thinking::Config.new(**thinking.transform_keys(&:to_sym))
                 end

  new(
    id: id || "req_#{SecureRandom.hex(12)}",
    messages: msg_array,
    system: system,
    tools: tool_hash,
    tool_choice: tool_choice.is_a?(String) ? tool_choice.to_sym : tool_choice,
    params: params_obj,
    thinking: thinking_obj,
    stream: stream,
    conversation_id: conversation_id,
    caller: caller,
    routing: routing || {},
    metadata: metadata || {}
  )
end

.from_hash(source) ⇒ Object

Build from a Hash (raw client request or deserialized wire payload).



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 60

def self.from_hash(source)
  return nil if source.nil?

  h = source.transform_keys(&:to_sym)

  # Extract metadata from unknown keys
  metadata = h[:metadata] || {}
  known_keys = %i[id messages system tools tool_choice params thinking
                  stream conversation_id caller routing metadata]
  (h.keys - known_keys).each do |key|
    metadata[key] = h.delete(key)
  end
  h[:metadata] = metadata

  build(**h)
end

.normalize_tools(tools) ⇒ Object 



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 95

def self.normalize_tools(tools)
  return {} if tools.nil? || tools.empty?

  case tools
  when Hash
    tools.transform_values do |tool|
      tool.is_a?(ToolDefinition) ? tool : ToolDefinition.from_hash(tool)
    end
  when Array
    tools.each_with_object({}) do |tool, hash|
      td = tool.is_a?(ToolDefinition) ? tool : ToolDefinition.from_hash(tool)
      hash[td.name] = td
    end
  else
    {}
  end
end

Instance Method Details

#to_h ⇒ Object

Serialize to a Hash for AMQP/fleet/wire transport.



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/legion/extensions/llm/canonical/request.rb', line 78

def to_h
  {
    id: id,
    messages: messages&.map { |m| m.is_a?(Message) ? m.to_h : m },
    system: system,
    tools: tools&.transform_values { |t| t.is_a?(ToolDefinition) ? t.to_h : t },
    tool_choice: tool_choice,
    params: params&.to_h,
    thinking: thinking&.to_h,
    stream: stream,
    conversation_id: conversation_id,
    caller: caller,
    routing: routing,
    metadata: metadata
  }.compact
end