Class: Legion::Extensions::Llm::Canonical::ToolCall

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

Overview

Canonical tool call with source enum and compliance fields. Ports field vocabulary from Legion::LLM::Types::ToolCall. Source enum per R7: :client | :registry | :special | :extension | :mcp Compliance fields per R8: data_handling_classification, policy_decision arguments is a Hash only (O03a): JSON-string arguments are a provider wire spelling parsed at the provider translator edge (10 U2).

Constant Summary collapse

SOURCE_VALUES = 
%i[client registry special extension mcp].freeze
STATUS_VALUES = 
%i[pending running success error].freeze
BUILD_SITE = 
'Canonical::ToolCall.build'
FROM_HASH_SITE = 
'Canonical::ToolCall.from_hash'
NEW_SITE = 
'Canonical::ToolCall.new'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#arguments ⇒ Object (readonly)

Returns the value of attribute arguments

Returns:

  • (Object) —

    the current value of arguments



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def arguments
  @arguments
end

#category ⇒ Object (readonly)

Returns the value of attribute category

Returns:

  • (Object) —

    the current value of category



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def category
  @category
end

#data_handling_classification ⇒ Object (readonly)

Returns the value of attribute data_handling_classification

Returns:

  • (Object) —

    the current value of data_handling_classification



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def data_handling_classification
  @data_handling_classification
end

#duration_ms ⇒ Object (readonly)

Returns the value of attribute duration_ms

Returns:

  • (Object) —

    the current value of duration_ms



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def duration_ms
  @duration_ms
end

#error ⇒ Object (readonly)

Returns the value of attribute error

Returns:

  • (Object) —

    the current value of error



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def error
  @error
end

#exchange_id ⇒ Object (readonly)

Returns the value of attribute exchange_id

Returns:

  • (Object) —

    the current value of exchange_id



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def exchange_id
  @exchange_id
end

#finished_at ⇒ Object (readonly)

Returns the value of attribute finished_at

Returns:

  • (Object) —

    the current value of finished_at



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def finished_at
  @finished_at
end

#id ⇒ Object (readonly)

Returns the value of attribute id

Returns:

  • (Object) —

    the current value of id



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def id
  @id
end

#metadata ⇒ Object (readonly)

Returns the value of attribute metadata

Returns:

  • (Object) —

    the current value of metadata



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def metadata
  @metadata
end

#name ⇒ Object (readonly)

Returns the value of attribute name

Returns:

  • (Object) —

    the current value of name



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def name
  @name
end

#policy_decision ⇒ Object (readonly)

Returns the value of attribute policy_decision

Returns:

  • (Object) —

    the current value of policy_decision



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def policy_decision
  @policy_decision
end

#result ⇒ Object (readonly)

Returns the value of attribute result

Returns:

  • (Object) —

    the current value of result



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def result
  @result
end

#source ⇒ Object (readonly)

Returns the value of attribute source

Returns:

  • (Object) —

    the current value of source



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def source
  @source
end

#started_at ⇒ Object (readonly)

Returns the value of attribute started_at

Returns:

  • (Object) —

    the current value of started_at



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def started_at
  @started_at
end

#status ⇒ Object (readonly)

Returns the value of attribute status

Returns:

  • (Object) —

    the current value of status



17
18
19
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 17

def status
  @status
end

Class Method Details

.build(name:, id: nil, exchange_id: nil, arguments: nil, source: nil, status: nil, duration_ms: nil, result: nil, error: nil, started_at: nil, finished_at: nil, category: nil, data_handling_classification: nil, policy_decision: nil, metadata: {}) ⇒ Object

Build from keyword args (primary constructor). arguments: nil means "no arguments" and normalizes to {} (documented default, not tolerance).



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 26

def self.build(
  name:, id: nil, exchange_id: nil, arguments: nil, source: nil,
  status: nil, duration_ms: nil, result: nil, error: nil,
  started_at: nil, finished_at: nil, category: nil,
  data_handling_classification: nil, policy_decision: nil, metadata: {}
)
  new(
    id: id || "call_#{SecureRandom.hex(12)}",
    exchange_id: exchange_id,
    name: Strict.expect_type!(name, [::String], self::BUILD_SITE, :name),
    arguments: arguments.nil? ? {} : Strict.expect_type!(arguments, [::Hash], self::BUILD_SITE, :arguments),
    source: normalize_enum!(source, self::SOURCE_VALUES, self::BUILD_SITE, :source),
    status: normalize_enum!(status, self::STATUS_VALUES, self::BUILD_SITE, :status),
    duration_ms: duration_ms,
    result: result,
    error: error,
    started_at: started_at,
    finished_at: finished_at,
    category: category,
    data_handling_classification: data_handling_classification,
    policy_decision: policy_decision,
    metadata: Strict.metadata!(metadata, self::BUILD_SITE)
  )
end

.from_hash(source) ⇒ Object

Build from a Hash (raw provider response or deserialized wire payload).



52
53
54
55
56
57
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 52

def self.from_hash(source)
  Strict.require_hash!(source, self::FROM_HASH_SITE)
  hash = Strict.symbolize_keys(source)
  metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
  build(**hash, metadata:)
end

.normalize_enum!(value, allowed, site, member) ⇒ Object

L6: declared enums validated at construction, in both factories.



60
61
62
63
64
65
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 60

def self.normalize_enum!(value, allowed, site, member)
  return nil if value.nil?

  value_sym = value.is_a?(::String) ? value.to_sym : value
  Strict.enum!(value_sym, allowed, site, member)
end

Instance Method Details

#as_json ⇒ Object

MultiJson/Oj/::JSON callback for unknown types — without this, fallback is obj.to_s which for Data.define returns the #inspect dump and leaks into JSON.



105
106
107
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 105

def as_json(*)
  to_h
end

#error? ⇒ Boolean

Returns:

  • (Boolean) 


94
95
96
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 94

def error?
  status == :error
end

#success? ⇒ Boolean

Returns:

  • (Boolean) 


90
91
92
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 90

def success?
  status == :success
end

#to_h ⇒ Object

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



99
100
101
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 99

def to_h
  super.compact
end

#to_json ⇒ Object 



109
110
111
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 109

def to_json(*)
  to_h.to_json(*)
end

#with_result(result:, status:, duration_ms: nil, finished_at: nil) ⇒ Object

Return a new ToolCall with execution result attached. The strict constructor re-validates every carried member (status enum included) — the escape-hatch .new of the pre-H1 world is gone.



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/legion/extensions/llm/canonical/tool_call.rb', line 70

def with_result(result:, status:, duration_ms: nil, finished_at: nil)
  self.class.new(
    id: id,
    exchange_id: exchange_id,
    name: name,
    arguments: arguments,
    source: source,
    status: status,
    duration_ms: duration_ms,
    result: result,
    error: status == :error ? result : error,
    started_at: started_at,
    finished_at: finished_at || ::Time.now,
    category: category,
    data_handling_classification: data_handling_classification,
    policy_decision: policy_decision,
    metadata: metadata
  )
end