Module: PromptBuilder

Defined in:
lib/prompt_builder.rb,
lib/prompt_builder/items.rb,
lib/prompt_builder/tools.rb,
lib/prompt_builder/usage.rb,
lib/prompt_builder/errors.rb,
lib/prompt_builder/content.rb,
lib/prompt_builder/session.rb,
lib/prompt_builder/response.rb,
lib/prompt_builder/items/base.rb,
lib/prompt_builder/serializers.rb,
lib/prompt_builder/content/base.rb,
lib/prompt_builder/content/text.rb,
lib/prompt_builder/items/message.rb,
lib/prompt_builder/tool_registry.rb,
lib/prompt_builder/items/reasoning.rb,
lib/prompt_builder/items/compaction.rb,
lib/prompt_builder/serializers/base.rb,
lib/prompt_builder/tools/definition.rb,
lib/prompt_builder/content/input_file.rb,
lib/prompt_builder/content/input_text.rb,
lib/prompt_builder/serializers/gemini.rb,
lib/prompt_builder/content/input_image.rb,
lib/prompt_builder/content/input_video.rb,
lib/prompt_builder/content/output_text.rb,
lib/prompt_builder/items/function_call.rb,
lib/prompt_builder/content/summary_text.rb,
lib/prompt_builder/items/item_reference.rb,
lib/prompt_builder/serializers/converse.rb,
lib/prompt_builder/serializers/messages.rb,
lib/prompt_builder/content/reasoning_text.rb,
lib/prompt_builder/content/refusal_content.rb,
lib/prompt_builder/items/function_call_output.rb,
lib/prompt_builder/serializers/gemini/request.rb,
lib/prompt_builder/serializers/open_responses.rb,
lib/prompt_builder/serializers/chat_completion.rb,
lib/prompt_builder/serializers/gemini/response.rb,
lib/prompt_builder/serializers/converse/request.rb,
lib/prompt_builder/serializers/messages/request.rb,
lib/prompt_builder/serializers/converse/response.rb,
lib/prompt_builder/serializers/messages/response.rb,
lib/prompt_builder/serializers/open_responses/request.rb,
lib/prompt_builder/serializers/chat_completion/request.rb,
lib/prompt_builder/serializers/open_responses/response.rb,
lib/prompt_builder/serializers/chat_completion/response.rb

Overview

Top-level module for the PromptBuilder gem. Provides a DSL for constructing Open Responses API request payloads and parsing responses.

Defined Under Namespace

Modules: Content, Items, Serializers, Tools Classes: Error, InvalidItemError, InvalidStateError, Response, Session, ToolNotFoundError, ToolRegistry, UnsupportedFormatError, Usage

Constant Summary collapse

VERSION = 
File.read(File.join(__dir__, "../VERSION")).strip

Class Method Summary collapse

Class Method Details

.data_url(data, content_type) ⇒ String

Construct a base64-encoded data URL from raw binary data and a content type.

Parameters:

  • data (String) —

    the raw binary data

  • content_type (String) —

    the MIME content type (e.g. “image/png”, “application/pdf”)

Returns:

  • (String) —

    a data URL in the form “data:<content_type>;base64,<encoded_data>”



43
44
45
 
# File 'lib/prompt_builder.rb', line 43

def data_url(data, content_type)
  "data:#{content_type};base64,#{[data].pack("m0")}"
end

.jsonify(value) ⇒ Object

Convert a value to a JSON-safe structure by deep-stringifying Hash keys and converting Symbols to Strings.

Parameters:

  • value (Object) —

    the value to convert

Returns:

  • (Object) —

    the JSON-safe value



25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/prompt_builder.rb', line 25

def jsonify(value)
  case value
  when Hash
    value.each_with_object({}) { |(k, v), h| h[k.to_s] = jsonify(v) }
  when Array
    value.map { |v| jsonify(v) }
  when Symbol
    value.to_s
  else
    value
  end
end

.parse_data_url(url) ⇒ Array(String, String)?

Parse a data URL into its media type and base64-encoded data.

Parameters:

  • url (String, nil) —

    a URL that may be a data URL

Returns:

  • (Array(String, String), nil) —

    a two-element array of [media_type, data] or nil if the URL is not a data URL



52
53
54
55
56
57
 
# File 'lib/prompt_builder.rb', line 52

def parse_data_url(url)
  return nil unless url
  match = url.match(/\Adata:([^;]+);base64,(.*)\z/m)
  return nil unless match
  [match[1], match[2]]
end

.register_tool(name, description: nil, parameters: nil, strict: false) {|Hash| ... } ⇒ Tools::Definition

Register a tool in the global registry.

Parameters:

  • name (String) —

    the tool name

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

    the tool description

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

    the JSON Schema for parameters

  • strict (Boolean) (defaults to: false) —

    whether strict mode is enabled

Yields:

  • (Hash) —

    the parsed arguments when the tool is invoked

Yield Returns:

  • (Object) —

    the tool output (String, Hash, Array, or any object)

Returns:



75
76
77
 
# File 'lib/prompt_builder.rb', line 75

def register_tool(name, description: nil, parameters: nil, strict: false, &handler)
  tool_registry.register(name, description: description, parameters: parameters, strict: strict, &handler)
end

.reset_tool_registry! ⇒ void

This method returns an undefined value.

Reset the global tool registry. Primarily used in tests.



82
83
84
 
# File 'lib/prompt_builder.rb', line 82

def reset_tool_registry!
  @tool_registry = ToolRegistry.new
end

.tool_registry ⇒ ToolRegistry

Returns the global tool registry singleton.

Returns:



62
63
64
 
# File 'lib/prompt_builder.rb', line 62

def tool_registry
  @tool_registry ||= ToolRegistry.new
end