Class: PromptBuilder::Response

Inherits:
Object
  • Object
show all
Defined in:
lib/prompt_builder/response.rb

Overview

Represents a parsed API response from the Open Responses API. All fields are optional and will be nil if not present in the response.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**attributes) ⇒ Response

Create a new Response.

Parameters:

  • attributes (Hash) —

    response attributes

Options Hash (**attributes):

  • :extra (Hash, nil) —

    provider-specific response metadata that has no canonical Open Responses slot (e.g. Gemini grounding and citation metadata, candidate safety ratings, logprobs results)



136
137
138
139
140
141
142
 
# File 'lib/prompt_builder/response.rb', line 136

def initialize(**attributes)
  FIELDS.each { |f| instance_variable_set(:"@#{f}", coerce_field(f, attributes[f])) }
  @text_config = PromptBuilder.jsonify(attributes[:text_config])
  @output = attributes[:output] || []
  @usage = attributes[:usage]
  @extra = PromptBuilder.jsonify(attributes[:extra])
end

Instance Attribute Details

#background ⇒ Boolean? (readonly)

Returns whether this is a background response.

Returns:

  • (Boolean, nil) —

    whether this is a background response



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#completed_at ⇒ Integer? (readonly)

Returns completion timestamp.

Returns:

  • (Integer, nil) —

    completion timestamp



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#created_at ⇒ Integer? (readonly)

Returns creation timestamp.

Returns:

  • (Integer, nil) —

    creation timestamp



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#error ⇒ Hash? (readonly)

Returns error information.

Returns:

  • (Hash, nil) —

    error information



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#extra ⇒ Object (readonly)

Returns the value of attribute extra.



126
127
128
 
# File 'lib/prompt_builder/response.rb', line 126

def extra
  @extra
end

#frequency_penalty ⇒ Float? (readonly)

Returns the frequency penalty.

Returns:

  • (Float, nil) —

    the frequency penalty



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#id ⇒ String? (readonly)

Returns the response identifier.

Returns:

  • (String, nil) —

    the response identifier



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#incomplete_details ⇒ Hash? (readonly)

Returns details about why the response is incomplete.

Returns:

  • (Hash, nil) —

    details about why the response is incomplete



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#instructions ⇒ String? (readonly)

Returns the system instructions.

Returns:

  • (String, nil) —

    the system instructions



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#max_output_tokens ⇒ Integer? (readonly)

Returns the maximum output tokens.

Returns:

  • (Integer, nil) —

    the maximum output tokens



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#max_tool_calls ⇒ Integer? (readonly)

Returns the maximum number of tool calls.

Returns:

  • (Integer, nil) —

    the maximum number of tool calls



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#metadata ⇒ Hash? (readonly)

Returns arbitrary metadata.

Returns:

  • (Hash, nil) —

    arbitrary metadata



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#model ⇒ String? (readonly)

Returns the model identifier.

Returns:

  • (String, nil) —

    the model identifier



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#object ⇒ String? (readonly)

Returns the object type.

Returns:

  • (String, nil) —

    the object type



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#output ⇒ Array<Items::Base> (readonly)

Returns the output items.

Returns:



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#parallel_tool_calls ⇒ Boolean? (readonly)

Returns whether parallel tool calls are enabled.

Returns:

  • (Boolean, nil) —

    whether parallel tool calls are enabled



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#presence_penalty ⇒ Float? (readonly)

Returns the presence penalty.

Returns:

  • (Float, nil) —

    the presence penalty



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#previous_response_id ⇒ String? (readonly)

Returns the previous response identifier.

Returns:

  • (String, nil) —

    the previous response identifier



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#prompt_cache_key ⇒ String? (readonly)

Returns the prompt cache key.

Returns:

  • (String, nil) —

    the prompt cache key



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#prompt_cache_retention ⇒ String? (readonly)

Returns the prompt cache retention policy.

Returns:

  • (String, nil) —

    the prompt cache retention policy



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#reasoning ⇒ Hash? (readonly)

Returns the reasoning configuration.

Returns:

  • (Hash, nil) —

    the reasoning configuration



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#safety_identifier ⇒ String? (readonly)

Returns the safety identifier.

Returns:

  • (String, nil) —

    the safety identifier



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#service_tier ⇒ String? (readonly)

Returns the service tier.

Returns:

  • (String, nil) —

    the service tier



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#status ⇒ String? (readonly)

Returns the response status.

Returns:

  • (String, nil) —

    the response status



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#store ⇒ Boolean? (readonly)

Returns whether to store the response.

Returns:

  • (Boolean, nil) —

    whether to store the response



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#temperature ⇒ Float? (readonly)

Returns the temperature.

Returns:

  • (Float, nil) —

    the temperature



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#text_config ⇒ Hash? (readonly)

Returns the text configuration.

Returns:

  • (Hash, nil) —

    the text configuration



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#tool_choice ⇒ String, ... (readonly)

Returns the tool choice configuration.

Returns:

  • (String, Hash, nil) —

    the tool choice configuration



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#tools ⇒ Array<Hash>? (readonly)

Returns the tool definitions.

Returns:

  • (Array<Hash>, nil) —

    the tool definitions



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#top_logprobs ⇒ Integer? (readonly)

Returns the number of top log probabilities to return.

Returns:

  • (Integer, nil) —

    the number of top log probabilities to return



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#top_p ⇒ Float? (readonly)

Returns the top_p sampling parameter.

Returns:

  • (Float, nil) —

    the top_p sampling parameter



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#truncation ⇒ String? (readonly)

Returns the truncation strategy.

Returns:

  • (String, nil) —

    the truncation strategy



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

#usage ⇒ Usage? (readonly)

Returns token usage statistics.

Returns:

  • (Usage, nil) —

    token usage statistics



125
 
# File 'lib/prompt_builder/response.rb', line 125

FIELDS.each { |f| attr_reader f }

Class Method Details

.from_h(hash) ⇒ Response

Deserialize a Response from a Hash.

Parameters:

  • hash (Hash) —

    a Hash with string keys from the API response

Returns:



161
162
163
164
165
166
167
 
# File 'lib/prompt_builder/response.rb', line 161

def from_h(hash)
  output = (hash["output"] || []).map { |item| Items::Base.from_h(item) }
  usage = hash["usage"] ? Usage.from_h(hash["usage"]) : nil

  attrs = FIELDS.each_with_object({}) { |f, acc| acc[f] = hash[f.to_s] }
  new(**attrs, text_config: hash["text"], output: output, usage: usage, extra: hash["extra"])
end

.parse(hash, serializer_class) ⇒ Response

Parse a response hash using the given serializer and return a Response.

Parameters:

  • hash (Hash) —

    the API response hash (typically from JSON.parse)

  • serializer_class (Class, Symbol) —

    a serializer class (e.g. Serializers::ChatCompletion) or a symbol shorthand (:open_responses, :chat_completion, :messages, :gemini, :converse)

Returns:

Raises:

  • (ArgumentError) —

    if a symbol is given that does not map to a known serializer



153
154
155
 
# File 'lib/prompt_builder/response.rb', line 153

def parse(hash, serializer_class)
  Serializers.resolve(serializer_class).parse_response(hash)
end

Instance Method Details

#completed? ⇒ Boolean

Check if the response completed successfully.

Returns:

  • (Boolean) 


173
174
175
 
# File 'lib/prompt_builder/response.rb', line 173

def completed?
  @status == "completed"
end

#failed? ⇒ Boolean

Check if the response failed.

Returns:

  • (Boolean) 


180
181
182
 
# File 'lib/prompt_builder/response.rb', line 180

def failed?
  @status == "failed"
end

#has_tool_calls? ⇒ Boolean

Check if the response contains any tool calls.

Returns:

  • (Boolean) 


194
195
196
 
# File 'lib/prompt_builder/response.rb', line 194

def has_tool_calls?
  @output.any? { |item| item.is_a?(Items::FunctionCall) }
end

#incomplete? ⇒ Boolean

Check if the response is incomplete.

Returns:

  • (Boolean) 


187
188
189
 
# File 'lib/prompt_builder/response.rb', line 187

def incomplete?
  @status == "incomplete"
end

#text ⇒ String?

Extract the text from the first output message. Returns the concatenated text of all OutputText content blocks in the first message.

Returns:

  • (String, nil) —

    the text content, or nil if no message with text is found



209
210
211
212
213
214
215
216
217
 
# File 'lib/prompt_builder/response.rb', line 209

def text
  @output.each do |item|
    next unless item.is_a?(Items::Message)

    texts = item.content.select { |c| c.is_a?(Content::OutputText) }
    return texts.map(&:text).join unless texts.empty?
  end
  nil
end

#to_h ⇒ Hash

Serialize to a Hash with string keys. Nil values are omitted.

Returns:

  • (Hash) 


222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/prompt_builder/response.rb', line 222

def to_h
  h = {}
  FIELDS.each do |f|
    val = instance_variable_get(:"@#{f}")
    if BOOLEAN_FIELDS.include?(f)
      h[f.to_s] = val unless val.nil?
    elsif val
      h[f.to_s] = val
    end
  end
  h["text"] = @text_config if @text_config
  h["output"] = @output.map(&:to_h) unless @output.empty?
  h["usage"] = @usage.to_h if @usage
  h["extra"] = @extra if @extra && !@extra.empty?
  h
end

#tool_calls ⇒ Array<Items::FunctionCall>

Get all function call items from the output.

Returns:



201
202
203
 
# File 'lib/prompt_builder/response.rb', line 201

def tool_calls
  @output.select { |item| item.is_a?(Items::FunctionCall) }
end