Class: Legion::Extensions::Llm::Canonical::ToolDefinition

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

Overview

Canonical tool definition. Ports field vocabulary from Legion::LLM::Types::ToolDefinition. # -- required for Data.define block scope

Constant Summary collapse

BUILD_SITE = 
'Canonical::ToolDefinition.build'
FROM_HASH_SITE = 
'Canonical::ToolDefinition.from_hash'
NEW_SITE = 
'Canonical::ToolDefinition.new'
NORMALIZE_PARAMETERS_SITE = 
'Canonical::ToolDefinition.normalize_parameters'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#description ⇒ Object (readonly)

Returns the value of attribute description

Returns:

  • (Object) —

    the current value of description



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

def description
  @description
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/tool_definition.rb', line 12

def metadata
  @metadata
end

#name ⇒ Object (readonly)

Returns the value of attribute name

Returns:

  • (Object) —

    the current value of name



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

def name
  @name
end

#parameters ⇒ Object (readonly)

Returns the value of attribute parameters

Returns:

  • (Object) —

    the current value of parameters



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

def parameters
  @parameters
end

#source ⇒ Object (readonly)

Returns the value of attribute source

Returns:

  • (Object) —

    the current value of source



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

def source
  @source
end

Class Method Details

.build(name:, description: '', parameters: nil, source: nil, metadata: {}) ⇒ Object

Build from keyword args (primary constructor). M5: the name is the authoritative client/registry fact — never rewritten, stripped, truncated, or fabricated here; per-dialect name constraints belong to the provider translator edge. source is explicit or absent — never fabricated ({ type: :builtin } is deleted).



33
34
35
36
37
38
39
40
41
 
# File 'lib/legion/extensions/llm/canonical/tool_definition.rb', line 33

def self.build(name:, description: '', parameters: nil, source: nil, metadata: {})
  new(
    name,
    description,
    normalize_parameters(parameters),
    source,
    Strict.metadata!(metadata, self::BUILD_SITE)
  )
end

.description_value!(description, site) ⇒ Object

M5: description is a String; absence is the empty string (the documented no-description value), wrong class raises.



68
69
70
71
72
 
# File 'lib/legion/extensions/llm/canonical/tool_definition.rb', line 68

def self.description_value!(description, site)
  return '' if description.nil?

  Strict.expect_type!(description, [::String], site, :description)
end

.from_hash(source) ⇒ Object

Build from a Hash (raw provider response or deserialized wire payload). Canonical keys only (O03a): edges pass parameters, not input_schema.



45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/legion/extensions/llm/canonical/tool_definition.rb', line 45

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(
    name: hash[:name],
    description: hash[:description],
    parameters: hash[:parameters],
    source: hash[:source],
    metadata:
  )
end

.normalize_parameters(parameters) ⇒ Object 



13
14
15
16
17
18
19
20
21
22
23
24
25
26
 
# File 'lib/legion/extensions/llm/canonical/tool_definition.rb', line 13

def self.normalize_parameters(parameters)
  empty = { type: 'object', properties: {} }
  return empty if parameters.nil?

  Strict.expect_type!(parameters, [::Hash], self::NORMALIZE_PARAMETERS_SITE, :parameters) unless parameters.is_a?(::Hash)

  schema = parameters.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
  return empty if schema.empty?
  return schema if schema.key?(:type)
  return schema.merge(type: 'object') if OBJECT_SCHEMA_KEYWORDS.any? { |k| schema.key?(k) }
  return schema if COMPOSITE_SCHEMA_KEYWORDS.any? { |k| schema.key?(k) }

  { type: 'object', properties: schema }
end

.require_name!(name, site) ⇒ Object

M5: a tool name is authoritative — missing or empty is a contract error, never a fabricated label.

Raises:

  • (ArgumentError) 


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

def self.require_name!(name, site)
  raise ArgumentError, "#{site}: name must be a non-empty String, got #{name.class}: #{name.inspect}" unless name.is_a?(::String) && !name.empty?

  name
end

Instance Method Details

#as_json ⇒ Object

MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.



88
89
90
 
# File 'lib/legion/extensions/llm/canonical/tool_definition.rb', line 88

def as_json(*)
  to_h
end

#input_schema ⇒ Object 



78
79
80
 
# File 'lib/legion/extensions/llm/canonical/tool_definition.rb', line 78

def input_schema
  parameters
end

#params_schema ⇒ Object 



74
75
76
 
# File 'lib/legion/extensions/llm/canonical/tool_definition.rb', line 74

def params_schema
  parameters
end

#to_h ⇒ Object

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



83
84
85
 
# File 'lib/legion/extensions/llm/canonical/tool_definition.rb', line 83

def to_h
  super.compact
end

#to_json ⇒ Object 



92
93
94
 
# File 'lib/legion/extensions/llm/canonical/tool_definition.rb', line 92

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