Class: Ask::ProviderTool

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

Overview

Configuration for a provider-defined or provider-executed tool.

Provider tools are built-in capabilities that the LLM provider offers natively — web search, file search, code execution, image generation, and so on. They are not implemented by user code but by the provider itself.

Examples:

Configuring a provider-executed web search

Ask::ProviderTool.new(
  id: "openai.web_search",
  name: "web_search",
  description: "Search the internet",
  args: { search_context_size: "medium" }
)

Using shorthand factory methods

Ask::ProviderTool.web_search(search_context_size: "high")
Ask::ProviderTool.file_search(max_num_results: 10)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id:, name:, description: "", args: {}) ⇒ ProviderTool

Returns a new instance of ProviderTool.



45
46
47
48
49
50
51
 
# File 'lib/ask/provider_tool.rb', line 45

def initialize(id:, name:, description: "", args: {})
  @id = id
  @name = name
  @description = description
  @args = args.dup.freeze
  freeze
end

Instance Attribute Details

#args ⇒ Hash (readonly)

Returns provider-specific configuration arguments.

Returns:

  • (Hash) —

    provider-specific configuration arguments



33
34
35
 
# File 'lib/ask/provider_tool.rb', line 33

def args
  @args
end

#description ⇒ String (readonly)

Returns human-readable description.

Returns:

  • (String) —

    human-readable description



30
31
32
 
# File 'lib/ask/provider_tool.rb', line 30

def description
  @description
end

#id ⇒ String (readonly)

Returns fully qualified tool identifier (e.g. "openai.web_search").

Returns:

  • (String) —

    fully qualified tool identifier (e.g. "openai.web_search")



24
25
26
 
# File 'lib/ask/provider_tool.rb', line 24

def id
  @id
end

#name ⇒ String (readonly)

Returns short tool name.

Returns:

  • (String) —

    short tool name



27
28
29
 
# File 'lib/ask/provider_tool.rb', line 27

def name
  @name
end

Class Method Details

.code_interpreter(file_ids: nil) ⇒ Object

OpenAI code interpreter tool.

Parameters:

  • file_ids (Array<String>, nil) (defaults to: nil) —

    IDs of files to make available



78
79
80
81
 
# File 'lib/ask/provider_tool.rb', line 78

def code_interpreter(file_ids: nil)
  args = file_ids ? { file_ids: file_ids } : {}
  new(id: "openai.code_interpreter", name: "code_interpreter", description: "Execute Python code in a sandboxed environment", args: args)
end

.file_search(vector_store_ids:, max_num_results: nil) ⇒ Object

OpenAI file search tool. Requires a vector store.

Parameters:

  • vector_store_ids (Array<String>) —

    IDs of vector stores to search

  • max_num_results (Integer, nil) (defaults to: nil) —

    maximum number of results



69
70
71
72
73
74
 
# File 'lib/ask/provider_tool.rb', line 69

def file_search(vector_store_ids:, max_num_results: nil)
  args = { vector_store_ids: vector_store_ids }.tap do |h|
    h[:max_num_results] = max_num_results if max_num_results
  end
  new(id: "openai.file_search", name: "file_search", description: "Search through uploaded files", args: args)
end

.web_search(search_context_size: nil, user_location: nil, allowed_domains: nil) ⇒ Object

OpenAI web search tool.

Parameters:

  • search_context_size (String, nil) (defaults to: nil) —

    "low", "medium", or "high"

  • user_location (Hash, nil) (defaults to: nil) —

    approximate location { type: "approximate", country: "US", ... }



57
58
59
60
61
62
63
64
 
# File 'lib/ask/provider_tool.rb', line 57

def web_search(search_context_size: nil, user_location: nil, allowed_domains: nil)
  args = {}.tap do |h|
    h[:search_context_size] = search_context_size if search_context_size
    h[:user_location] = user_location if user_location
    h[:allowed_domains] = allowed_domains if allowed_domains
  end
  new(id: "openai.web_search", name: "web_search", description: "Search the internet for current information", args: args)
end

Instance Method Details

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

Equality based on id + args.



85
86
87
88
 
# File 'lib/ask/provider_tool.rb', line 85

def ==(other)
  return false unless other.is_a?(ProviderTool)
  id == other.id && args == other.args
end

#hash ⇒ Object 



91
92
93
 
# File 'lib/ask/provider_tool.rb', line 91

def hash
  [id, args].hash
end

#provider_executed? ⇒ Boolean

Returns true if the provider handles execution on its side.

Returns:

  • (Boolean) —

    true if the provider handles execution on its side



36
37
38
 
# File 'lib/ask/provider_tool.rb', line 36

def provider_executed?
  true
end

#provider_tool? ⇒ Boolean

Returns true — marks this as a provider tool for routing.

Returns:

  • (Boolean) —

    true — marks this as a provider tool for routing



41
42
43
 
# File 'lib/ask/provider_tool.rb', line 41

def provider_tool?
  true
end