Module: RubyLLM::Providers::OpenAIResponses::BuiltInTools

Defined in:
lib/ruby_llm/providers/openai_responses/built_in_tools.rb

Overview

Built-in tools support for the OpenAI Responses API. Provides configuration helpers and result parsing for:

  • Web Search

  • File Search

  • Code Interpreter

  • Image Generation

  • MCP (Model Context Protocol)

Class Method Summary collapse

Class Method Details

.code_interpreter(container_type: 'auto') ⇒ Object

Code Interpreter tool configuration

Parameters:

  • container_type (String) (defaults to: 'auto') —

    ‘auto’ or specific container type



42
43
44
45
46
47
 
# File 'lib/ruby_llm/providers/openai_responses/built_in_tools.rb', line 42

def code_interpreter(container_type: 'auto')
  {
    type: 'code_interpreter',
    container: { type: container_type }
  }
end

.computer_use(display_width:, display_height:, environment: 'browser') ⇒ Object

Computer Use tool configuration (preview)

Parameters:

  • display_width (Integer) —

    Display width in pixels

  • display_height (Integer) —

    Display height in pixels

  • environment (String) (defaults to: 'browser') —

    ‘browser’ or ‘mac’ or ‘windows’ or ‘ubuntu’



79
80
81
82
83
84
85
86
 
# File 'lib/ruby_llm/providers/openai_responses/built_in_tools.rb', line 79

def computer_use(display_width:, display_height:, environment: 'browser')
  {
    type: 'computer_use_preview',
    display_width: display_width,
    display_height: display_height,
    environment: environment
  }
end

.extract_citations(content) ⇒ Array<Hash>

Extract all citations from message content

Parameters:

  • content (Array) —

    Message content array

Returns:

  • (Array<Hash>) —

    All citations/annotations



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/ruby_llm/providers/openai_responses/built_in_tools.rb', line 152

def extract_citations(content)
  return [] unless content.is_a?(Array)

  content
    .select { |c| c['type'] == 'output_text' }
    .flat_map { |c| c['annotations'] || [] }
    .map do |annotation|
      {
        type: annotation['type'],
        text: annotation['text'],
        url: annotation['url'],
        title: annotation['title'],
        start_index: annotation['start_index'],
        end_index: annotation['end_index']
      }.compact
    end
end

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

File Search tool configuration

Parameters:

  • vector_store_ids (Array<String>) —

    IDs of vector stores to search

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

    Maximum results to return

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

    Ranking configuration



30
31
32
33
34
35
36
37
38
 
# File 'lib/ruby_llm/providers/openai_responses/built_in_tools.rb', line 30

def file_search(vector_store_ids:, max_num_results: nil, ranking_options: nil)
  tool = {
    type: 'file_search',
    vector_store_ids: Array(vector_store_ids)
  }
  tool[:max_num_results] = max_num_results if max_num_results
  tool[:ranking_options] = ranking_options if ranking_options
  tool
end

.image_generation(partial_images: nil) ⇒ Object

Image Generation tool configuration

Parameters:

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

    Number of partial images during streaming



51
52
53
54
55
 
# File 'lib/ruby_llm/providers/openai_responses/built_in_tools.rb', line 51

def image_generation(partial_images: nil)
  tool = { type: 'image_generation' }
  tool[:partial_images] = partial_images if partial_images
  tool
end

.mcp(server_label:, server_url:, require_approval: 'never', allowed_tools: nil, headers: nil) ⇒ Object

MCP (Model Context Protocol) tool configuration

Parameters:

  • server_label (String) —

    Label for the MCP server

  • server_url (String) —

    URL of the MCP server

  • require_approval (String) (defaults to: 'never') —

    ‘never’, ‘always’, or specific tool patterns

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

    List of allowed tool names

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

    Additional headers for the MCP server



63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/ruby_llm/providers/openai_responses/built_in_tools.rb', line 63

def mcp(server_label:, server_url:, require_approval: 'never', allowed_tools: nil, headers: nil)
  tool = {
    type: 'mcp',
    server_label: server_label,
    server_url: server_url,
    require_approval: require_approval
  }
  tool[:allowed_tools] = allowed_tools if allowed_tools
  tool[:headers] = headers if headers
  tool
end

.parse_code_interpreter_results(output) ⇒ Array<Hash>

Parse code interpreter results from output

Parameters:

  • output (Array) —

    Response output array

Returns:

  • (Array<Hash>) —

    Parsed code interpreter results



121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/ruby_llm/providers/openai_responses/built_in_tools.rb', line 121

def parse_code_interpreter_results(output)
  output
    .select { |item| item['type'] == 'code_interpreter_call' }
    .map do |item|
      {
        id: item['id'],
        code: item['code'],
        results: item['results'] || [],
        container_id: item['container_id']
      }
    end
end

.parse_file_search_results(output) ⇒ Array<Hash>

Parse file search results from output

Parameters:

  • output (Array) —

    Response output array

Returns:

  • (Array<Hash>) —

    Parsed file search results



106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/ruby_llm/providers/openai_responses/built_in_tools.rb', line 106

def parse_file_search_results(output)
  output
    .select { |item| item['type'] == 'file_search_call' }
    .map do |item|
      {
        id: item['id'],
        status: item['status'],
        results: item['results'] || []
      }
    end
end

.parse_image_generation_results(output) ⇒ Array<Hash>

Parse image generation results from output

Parameters:

  • output (Array) —

    Response output array

Returns:

  • (Array<Hash>) —

    Parsed image generation results



137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/ruby_llm/providers/openai_responses/built_in_tools.rb', line 137

def parse_image_generation_results(output)
  output
    .select { |item| item['type'] == 'image_generation_call' }
    .map do |item|
      {
        id: item['id'],
        status: item['status'],
        result: item['result']
      }
    end
end

.parse_web_search_results(output) ⇒ Array<Hash>

Parse web search results from output

Parameters:

  • output (Array) —

    Response output array

Returns:

  • (Array<Hash>) —

    Parsed search results with citations



91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/ruby_llm/providers/openai_responses/built_in_tools.rb', line 91

def parse_web_search_results(output)
  output
    .select { |item| item['type'] == 'web_search_call' }
    .map do |item|
      {
        id: item['id'],
        status: item['status'],
        results: parse_citations(item)
      }
    end
end

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

Web Search tool configuration

Parameters:

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

    ‘low’, ‘medium’, or ‘high’

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

    { type: ‘approximate’, city: ‘…’, country: ‘…’ }



19
20
21
22
23
24
 
# File 'lib/ruby_llm/providers/openai_responses/built_in_tools.rb', line 19

def web_search(search_context_size: nil, user_location: nil)
  tool = { type: 'web_search_preview' }
  tool[:search_context_size] = search_context_size if search_context_size
  tool[:user_location] = user_location if user_location
  tool
end