prompt_builder 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e762383ea51918fa77b5962f0137775551a37da1c228a37d24364011c8d21f73
-  data.tar.gz: 64e2a4e22feb0a8e0e5752f4807b79452c3cb700dd8b5740500f11cbe0b4217e
+  metadata.gz: 9eee723a908587c28aa7e606b0e6dad45e5958a9d895d29bd42f8d984153d6bc
+  data.tar.gz: ffbfa13cc4bdfacc09ace7fe99a46366847faa501db6710cd51cca7123c106b2
 SHA512:
-  metadata.gz: b7eb3a4806f9cd7a24e00652659b7a5d641ae5877187bd714afd0e4eaa86c7a7901eebcfdf11202497d0b98cce03f9a0fec10f1840883f91b4b87be3a9f2c387
-  data.tar.gz: 2b731def4d25b2233b208d3fb3d8867ee17cce9356cb84b3d57d3d3043116af5eb55ca7888de00c329c3637b209bbc70ea11dada040bc5f97f9701c85a0fa8ee
+  metadata.gz: 40023bf88305a391c88b8a189e2810e27ad5af96b2e5bbf3697296eb9b4f63a360239eed8022c343198ddeff09573874988a33372b40b7c15080603a7588f093
+  data.tar.gz: b9be150ab138503f29f7769f71d1ad8092cef42aa5ba04ecb4d156f070fa5dc9aecdc1995a31fabfa74ab93206d47c1a24428417e2055d999c4473669c335f59

data/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.2.0
+
+### Added
+
+- `Session#use_tools` copies tool definitions from a `ToolRegistry` (the global registry by default) onto the session by name, raising a `ToolNotFoundError` for unknown names.
+- `Session#json_output` configures JSON Schema structured output without writing the raw `text.format` wire hash by hand.
+- `Session#think` configures reasoning portably across serializers via `effort:` or `budget_tokens:`; `think(false)` clears the configuration.
+- `Response#parsed_json` parses the response text as JSON (stripping fenced ```json wrappers), returning `nil` when it cannot be parsed; `Response#parsed_json!` raises a `ParseError` including the raw text instead.
+- `Response.from_text` synthesizes a completed assistant text response for canned answers, cached responses, and tests.
+- `PromptBuilder::ParseError` error class.
+
+### Changed
+
+- `Session.new` raises an `ArgumentError` when passed an unsupported keyword option instead of silently ignoring it.
+- The Messages serializer raises an `UnsupportedFormatError` when `session.max_output_tokens` is not set, since the Messages API requires the `max_tokens` parameter.
+- Serializers now raise an `UnsupportedFormatError` for missing fields their target API requires instead of emitting an invalid payload: Chat Completions, Converse, and Open Responses require `session.model`; Chat Completions requires at least one message; Gemini requires a non-empty `contents` array.
+- The Messages serializer raises an `UnsupportedFormatError` when thinking is enabled with a `budget_tokens` that is not less than `max_output_tokens`, matching the Anthropic API requirement that `max_tokens` be greater than the thinking budget.
+- The Converse serializer warns once per process when `session.reasoning` is set instead of silently dropping it (the Converse endpoint has no reasoning parameter).
+
 ## 0.1.2
 
 ### Fixed

data/README.md

@@ -57,6 +57,8 @@ session = PromptBuilder::Session.new(
 )
 ```
 
+Passing an option the constructor doesn't recognize (or both halves of an alias pair) raises an `ArgumentError`.
+
 ### Conversation History
 
 Build up a multi-turn conversation by adding messages:
@@ -160,6 +162,52 @@ response.has_tool_calls? # => false
 response.usage           # => #<PromptBuilder::Usage input_tokens=25 output_tokens=12 ...>
 ```
 
+You can also synthesize a plain-text response without calling an API — useful for canned answers (e.g. halting an agent loop), cached responses, and tests:
+
+```ruby
+response = PromptBuilder::Response.from_text("Authentication failed.",
+  model: llm_response.model, usage: llm_response.usage)
+response.text        # => "Authentication failed."
+response.completed?  # => true
+```
+
+### Structured Output
+
+Use `json_output` to request JSON Schema structured output and `parsed_json` to read it back:
+
+```ruby
+schema = {
+  "type" => "object",
+  "properties" => {"answer" => {"type" => "string"}},
+  "required" => ["answer"]
+}
+
+session.json_output(schema, name: "response", strict: true)
+payload = session.request_payload(:messages)  # works with all five serializers
+
+# After parsing the API response:
+data = response.parsed_json    # => {"answer" => "..."} or nil if the text isn't valid JSON
+data = response.parsed_json!   # raises PromptBuilder::ParseError (including the raw text) instead
+```
+
+`parsed_json` strips fenced ```` ```json ```` wrappers, a common provider quirk. `json_output` is sugar for setting `session.text` to the canonical `format` wire hash, so direct `session.text = {...}` assignment keeps working.
+
+### Reasoning / Extended Thinking
+
+Use `think` to configure reasoning portably; each serializer maps it to its native parameter:
+
+```ruby
+session.think(effort: :medium)       # portable across serializers
+session.think(budget_tokens: 8_000)  # explicit token budget where supported
+session.think(false)                 # clear the reasoning configuration
+```
+
+- `effort:` (one of `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) maps to `output_config.effort` (Messages), `reasoning_effort` (Chat Completions), `thinkingConfig.thinkingLevel` (Gemini), and `reasoning.effort` (Open Responses). Levels a target API doesn't accept are omitted.
+- `budget_tokens:` maps to `thinking.budget_tokens` (Messages) and `thinkingConfig.thinkingBudget` (Gemini); effort-based APIs ignore it. The Messages serializer raises an `UnsupportedFormatError` at `request_payload` time when `max_output_tokens` is not greater than the budget, since the Anthropic API requires `max_tokens > budget_tokens`.
+- The Converse API has no reasoning parameter; the serializer warns once per process and omits the configuration.
+
+Direct `session.reasoning = {...}` assignment keeps working for provider-specific keys (e.g. Anthropic's `display`, Gemini's `summary`).
+
 ### Agentic Tool Loops
 
 You can register tool definitions on a session, add API responses to the conversation, and manually append tool outputs to build an agentic loop:
@@ -240,6 +288,16 @@ end
 session.register_tools(PromptBuilder.tool_registry)
 ```
 
+Use `use_tools` to attach a subset of registry tools by name without copying schemas by hand. Unknown names raise a `ToolNotFoundError`, so a typo fails fast instead of producing a silently absent tool:
+
+```ruby
+session.use_tools("weather", "traffic_conditions")   # from PromptBuilder.tool_registry
+session.use_tools                                     # all tools in the registry
+session.use_tools(:weather, registry: my_registry)    # explicit registry
+```
+
+Tool definitions are *copied* onto the session in all cases, so later registry changes don't affect the session and the tools survive `to_h`/`from_h` round-trips.
+
 ### Content Types
 
 Message content can be a plain string or an array of structured content objects for multi-modal input. Content can be provided as raw Hashes or as `PromptBuilder::Content` objects.
@@ -481,6 +539,9 @@ restored_session = PromptBuilder::Session.from_h(hash)
 
 This makes it straightforward to persist conversation state in a database or cache between requests.
 
+> [!WARNING]
+> `to_h` is the persistence format, not a request payload. It retains provider-specific `extra` data and non-replayable items that APIs reject. Send the output of `request_payload(serializer)` to APIs, and use `to_h`/`from_h` only for storage.
+
 ## Serializer Compatibility
 
 The Open Responses format is the canonical data model for this gem. When serializing to other formats, some features may not be available because either the target API does not support them or because the Open Responses format does not expose parameters unique to the target API. If you attempt to use a feature that is not supported by a particular serializer, it will be silently omitted from the serialized output.
@@ -601,6 +662,8 @@ For Messages specifically:
 
 ### Chat Completions-specific notes
 
+Serializing a session without `model` set, or one that produces no messages at all, raises a `PromptBuilder::UnsupportedFormatError`.
+
 Request-side mappings worth calling out:
 
 | Canonical field / value | Chat Completions mapping |
@@ -631,6 +694,8 @@ Response-side behavior and limitations:
 
 ### Anthropic Messages-specific mappings
 
+The Messages API requires the `max_tokens` parameter, which is populated from `session.max_output_tokens`. Serializing a session without `max_output_tokens` set raises a `PromptBuilder::UnsupportedFormatError`.
+
 A few features map between the canonical Open Responses format and the Messages API in non-obvious ways:
 
 | Canonical field / value | Messages mapping |
@@ -654,6 +719,8 @@ Built-in tool response content blocks (`server_tool_use`, `web_search_tool_resul
 
 ### Gemini-specific notes
 
+Serializing a session without `model` set (the model belongs in the request URL, but it is validated at serialization time), or one that produces an empty `contents` array, raises a `PromptBuilder::UnsupportedFormatError`.
+
 Request-side mappings worth calling out:
 
 | Canonical field / value | Gemini mapping |
@@ -697,6 +764,8 @@ Response-side limitations:
 
 ### Converse-specific notes
 
+Serializing a session without `model` set (populates the required `modelId` parameter) raises a `PromptBuilder::UnsupportedFormatError`.
+
 Request-side restrictions worth calling out:
 
 | Canonical field / value | Converse mapping |

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.2.0

data/lib/prompt_builder/errors.rb

@@ -18,4 +18,7 @@ module PromptBuilder
 
   # Raised when a response payload does not match the expected shape.
   class UnexpectedPayloadError < Error; end
+
+  # Raised by Response#parsed_json! when the response text is not valid JSON.
+  class ParseError < Error; end
 end

data/lib/prompt_builder/response.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module PromptBuilder
   # Represents a parsed API response from the Open Responses API.
   # All fields are optional and will be nil if not present in the response.
@@ -173,6 +175,23 @@ module PromptBuilder
         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
+
+      # Synthesize a Response containing a single assistant text message.
+      # Useful for canned answers (halt messages, cached responses) and tests
+      # without assembling Items::Message and Content::OutputText by hand.
+      #
+      # @param text [String] the assistant message text
+      # @param status [String] the response status
+      # @param attributes [Hash] any other Response attributes (e.g. +model+,
+      #   +usage+, +id+)
+      # @return [Response]
+      # @example
+      #   PromptBuilder::Response.from_text("Authentication failed.",
+      #     model: llm_response.model, usage: llm_response.usage)
+      def from_text(text, status: "completed", **attributes)
+        message = Items::Message.new(role: "assistant", content: [Content::OutputText.new(text: text)])
+        new(status: status, output: [message], **attributes)
+      end
     end
 
     # Check if the response completed successfully.
@@ -224,6 +243,40 @@ module PromptBuilder
       nil
     end
 
+    # Parse the response text as JSON, for use with structured output
+    # (see +Session#json_output+). Strips a fenced ```json wrapper when
+    # present — a common provider quirk. Returns nil when the response has
+    # no text or the text is not valid JSON; use +parsed_json!+ to raise
+    # instead.
+    #
+    # @return [Hash, Array, Object, nil] the parsed JSON value, or nil
+    def parsed_json
+      raw = text
+      return nil unless raw
+
+      begin
+        JSON.parse(strip_json_fences(raw))
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    # Parse the response text as JSON, raising when it cannot be parsed.
+    #
+    # @return [Hash, Array, Object] the parsed JSON value
+    # @raise [ParseError] if the response has no text or the text is not
+    #   valid JSON; the error message includes the raw text
+    def parsed_json!
+      raw = text
+      raise ParseError, "Response has no text output to parse as JSON" unless raw
+
+      begin
+        JSON.parse(strip_json_fences(raw))
+      rescue JSON::ParserError => e
+        raise ParseError, "Response text is not valid JSON (#{e.message}); raw text: #{raw}"
+      end
+    end
+
     # Serialize to a Hash with string keys. Nil values are omitted.
     #
     # @return [Hash]
@@ -246,6 +299,12 @@ module PromptBuilder
 
     private
 
+    def strip_json_fences(raw)
+      stripped = raw.strip
+      match = stripped.match(/\A```(?:json)?\s*\n(.*?)\n?```\z/m)
+      match ? match[1] : stripped
+    end
+
     def coerce_field(field, value)
       return value if value.nil?
 

data/lib/prompt_builder/serializers/chat_completion/request.rb

@@ -5,6 +5,11 @@ module PromptBuilder
     class ChatCompletion < Base
       # Request serializer for the OpenAI Chat Completions API format.
       #
+      # Required session fields (an UnsupportedFormatError is raised when missing):
+      # - +model+
+      # - at least one message (+instructions+ or a conversation item that
+      #   serializes to a message)
+      #
       # === Unsupported Open Responses features
       #
       # These session fields are not supported and are silently omitted from the
@@ -62,8 +67,14 @@ module PromptBuilder
 
           def serialize_request(session)
             h = {}
-            h["model"] = session.model if session.model
-            h["messages"] = build_messages(session)
+            raise UnsupportedFormatError, "Chat Completions format requires session.model" unless session.model
+
+            h["model"] = session.model
+            messages = build_messages(session)
+            if messages.empty?
+              raise UnsupportedFormatError, "Chat Completions format requires at least one message"
+            end
+            h["messages"] = messages
             h["temperature"] = session.temperature if session.temperature
             h["top_p"] = session.top_p if session.top_p
             h["presence_penalty"] = session.presence_penalty if session.presence_penalty

data/lib/prompt_builder/serializers/converse/request.rb

@@ -8,6 +8,9 @@ module PromptBuilder
     class Converse < Base
       # Request serializer for the Amazon Bedrock Converse API format.
       #
+      # Required session fields (an UnsupportedFormatError is raised when missing):
+      # - +model+ — populates the required +modelId+ parameter
+      #
       # === Unsupported Open Responses features
       #
       # These session fields are not supported and are silently omitted from the
@@ -19,7 +22,8 @@ module PromptBuilder
       # - +parallel_tool_calls+ — parallel tool call control is not supported
       # - +presence_penalty+ — not supported by the Converse API
       # - +prompt_cache_key+ / +prompt_cache_retention+ — explicit prompt cache keys are not supported
-      # - +reasoning+ — extended thinking is not supported on the Converse endpoint
+      # - +reasoning+ — extended thinking is not supported on the Converse endpoint;
+      #   a warning is issued (once per process) when +session.reasoning+ is set
       # - +safety_identifier+ — no equivalent user-safety field on the Converse endpoint
       # - +store+ — server-side response storage is not supported
       # - +stream+ — SSE streaming is handled outside the Converse request payload
@@ -110,6 +114,13 @@ module PromptBuilder
         }.freeze
 
         class << self
+          # Reset the once-per-process reasoning warning. Primarily used in tests.
+          #
+          # @return [void]
+          def reset_reasoning_warning!
+            @reasoning_warning_issued = false
+          end
+
           private
 
           def serialize_request(session)
@@ -118,7 +129,11 @@ module PromptBuilder
             ctx = {document_name_counts: Hash.new(0)}
 
             h = {}
-            h["modelId"] = session.model if session.model
+            raise UnsupportedFormatError, "Converse format requires session.model" unless session.model
+
+            warn_reasoning_unsupported! if session.reasoning
+
+            h["modelId"] = session.model
 
             system = build_system(session)
             h["system"] = system unless system.empty?
@@ -154,6 +169,16 @@ module PromptBuilder
             h
           end
 
+          # The Converse endpoint has no reasoning/extended thinking parameter,
+          # so the reasoning config is dropped. Warn once per process instead of
+          # dropping it silently.
+          def warn_reasoning_unsupported!
+            return if @reasoning_warning_issued
+
+            @reasoning_warning_issued = true
+            warn "PromptBuilder: session.reasoning is not supported by the Converse format and was omitted from the request payload"
+          end
+
           def apply_session_extra!(h, extra)
             if extra.key?("stop_sequences")
               inference_config = h["inferenceConfig"] ||= {}

data/lib/prompt_builder/serializers/gemini/request.rb

@@ -7,6 +7,11 @@ module PromptBuilder
     class Gemini < Base
       # Request serializer for the Google Gemini API format.
       #
+      # Required session fields (an UnsupportedFormatError is raised when missing):
+      # - +model+ — not part of the payload (it belongs in the request URL) but
+      #   validated so an incomplete session fails at serialization time
+      # - at least one user/model message (the +contents+ array must not be empty)
+      #
       # === Unsupported Open Responses features
       #
       # These session fields are not supported and are silently omitted from the
@@ -115,7 +120,11 @@ module PromptBuilder
             system_instruction = build_system_instruction(session)
             h["systemInstruction"] = system_instruction if system_instruction
 
-            h["contents"] = build_contents(session)
+            contents = build_contents(session)
+            if contents.empty?
+              raise UnsupportedFormatError, "Gemini format requires at least one user/model message"
+            end
+            h["contents"] = contents
 
             generation_config = build_generation_config(session)
             h["generationConfig"] = generation_config unless generation_config.empty?

data/lib/prompt_builder/serializers/messages/request.rb

@@ -5,6 +5,10 @@ module PromptBuilder
     class Messages < Base
       # Request serializer for the Anthropic Messages API format.
       #
+      # Required session fields (an UnsupportedFormatError is raised when missing):
+      # - +model+
+      # - +max_output_tokens+ — populates the required +max_tokens+ parameter
+      #
       # === Unsupported Open Responses features
       #
       # These session fields are not supported and are silently omitted from the
@@ -27,7 +31,9 @@ module PromptBuilder
       # - +service_tier+ — only +auto+ and +standard_only+ are accepted
       # - +text+ — +format.type=json_schema+ is mapped to +output_config.format+
       # - +reasoning+ — +budget_tokens+, +display+, +effort+, and +type+ are forwarded;
-      #   +temperature+ must be unset and +top_p+ must be >= 0.95 when reasoning is enabled
+      #   +temperature+ must be unset, +top_p+ must be >= 0.95, and
+      #   +max_output_tokens+ must be greater than +budget_tokens+ when reasoning
+      #   is enabled
       #
       # Input content restrictions:
       # - +InputVideo+ content is not supported and is omitted
@@ -95,7 +101,11 @@ module PromptBuilder
             raise UnsupportedFormatError, "Messages format requires session.model" unless session.model
 
             h["model"] = session.model
-            h["max_tokens"] = session.max_output_tokens if session.max_output_tokens
+            unless session.max_output_tokens
+              raise UnsupportedFormatError,
+                "Messages format requires session.max_output_tokens to populate the required max_tokens field"
+            end
+            h["max_tokens"] = session.max_output_tokens
             h["temperature"] = session.temperature if session.temperature
             h["top_p"] = session.top_p if session.top_p
             effective_metadata = build_effective_metadata(session)
@@ -249,6 +259,12 @@ module PromptBuilder
           def validate_thinking_compatibility!(session, thinking)
             return unless thinking
 
+            budget = thinking["budget_tokens"]
+            if budget && session.max_output_tokens && session.max_output_tokens <= budget
+              raise UnsupportedFormatError,
+                "Messages format requires max_output_tokens (max_tokens) to be greater than reasoning.budget_tokens"
+            end
+
             if session.temperature
               raise UnsupportedFormatError,
                 "Messages format does not support temperature when thinking is enabled"

data/lib/prompt_builder/serializers/open_responses/request.rb

@@ -4,6 +4,9 @@ module PromptBuilder
   module Serializers
     class OpenResponses < Base
       # Request serializer for the OpenAI Open Responses API format.
+      #
+      # Required session fields (an UnsupportedFormatError is raised when missing):
+      # - +model+
       class Request < Base
         # Content extra keys that are part of the Open Responses API schema and
         # must survive extra-stripping (the canonical content classes have no
@@ -20,6 +23,8 @@ module PromptBuilder
           # @param session [Session] the session to export
           # @return [Hash] the serialized request payload
           def request_payload(session)
+            raise UnsupportedFormatError, "Open Responses format requires session.model" unless session.model
+
             payload = session.to_h
             items = apply_server_state!(payload, session)
             payload.delete("extra")

data/lib/prompt_builder/session.rb

@@ -27,6 +27,19 @@ module PromptBuilder
     JSONIFY_FIELDS = %i[include tool_choice metadata text stream_options reasoning].freeze
     private_constant :JSONIFY_FIELDS
 
+    # Effort levels accepted by +think+. This is the union of the levels
+    # recognized across serializers; each serializer omits levels its target
+    # API does not support.
+    THINK_EFFORT_LEVELS = %w[minimal low medium high xhigh max].freeze
+    private_constant :THINK_EFFORT_LEVELS
+
+    # All keyword options accepted by +initialize+.
+    INITIALIZE_OPTIONS = (
+      STRING_FIELDS + FLOAT_FIELDS + INTEGER_FIELDS + BOOLEAN_FIELDS + JSONIFY_FIELDS +
+        %i[input extra]
+    ).freeze
+    private_constant :INITIALIZE_OPTIONS
+
     # @!attribute [rw] model
     #   @return [String, nil] the model identifier
     # @!attribute [rw] instructions
@@ -145,14 +158,22 @@ module PromptBuilder
     # Create a new Session with the given options.
     # Accepts keyword arguments for all typed field groups (STRING_FIELDS,
     # FLOAT_FIELDS, INTEGER_FIELDS, BOOLEAN_FIELDS, JSONIFY_FIELDS); all default
-    # to +nil+. The +input+ shorthand auto-creates a user message if provided.
+    # to +nil+. The +input+ (or +user+) shorthand auto-creates a user message
+    # if provided. Unsupported keyword options raise an ArgumentError.
     #
     # @param attributes [Hash] keyword options; see attribute declarations above
     # @option attributes [String, nil] :input optional string shorthand; a user
     #   message is automatically added with this text
     # @option attributes [Hash, nil] :extra provider-specific extra data for
     #   serializers; recognized keys vary by target format
+    # @raise [ArgumentError] if an unsupported option is passed or aliased
+    #   options are passed together
     def initialize(**attributes)
+      unsupported = attributes.keys - INITIALIZE_OPTIONS
+      unless unsupported.empty?
+        raise ArgumentError, "unsupported option#{"s" if unsupported.size > 1}: #{unsupported.join(", ")}"
+      end
+
       (STRING_FIELDS + FLOAT_FIELDS + INTEGER_FIELDS + BOOLEAN_FIELDS + JSONIFY_FIELDS).each do |f|
         send(:"#{f}=", attributes[f])
       end
@@ -286,6 +307,118 @@ module PromptBuilder
       end
     end
 
+    # Copy tool definitions from a ToolRegistry onto this session by name.
+    # With no names, all tools in the registry are copied (same as
+    # +register_tools+). Definitions are copied, so later registry changes do
+    # not affect the session and the tools survive +to_h+/+from_h+ round-trips.
+    #
+    # @param names [Array<String, Symbol>] the tool names to copy; empty for all
+    # @param registry [ToolRegistry, nil] the registry to copy from; defaults
+    #   to the global +PromptBuilder.tool_registry+
+    # @return [Array<Tools::Definition>] the definitions registered on the session
+    # @raise [ToolNotFoundError] if a name is not registered in the registry
+    # @example
+    #   session.use_tools("weather", "traffic_conditions")
+    #   session.use_tools                                  # all registry tools
+    #   session.use_tools(:weather, registry: my_registry)
+    def use_tools(*names, registry: nil)
+      registry ||= PromptBuilder.tool_registry
+      raise ArgumentError, "registry must be an instance of ToolRegistry" unless registry.is_a?(ToolRegistry)
+
+      definitions = if names.empty?
+        registry.definitions
+      else
+        names.map do |name|
+          registry.definition_for(name.to_s) ||
+            raise(ToolNotFoundError, "No tool registered with name: #{name.to_s.inspect}")
+        end
+      end
+
+      definitions.map do |defn|
+        extra = defn.extra.transform_keys(&:to_sym)
+        register_tool(
+          defn.name,
+          description: defn.description,
+          parameters: defn.parameters,
+          strict: defn.strict,
+          **extra
+        )
+      end
+    end
+
+    # Configure JSON Schema structured output. Writes the canonical
+    # +text.format+ wire hash consumed by all serializers, preserving any
+    # other +text+ keys (e.g. +verbosity+) already set.
+    #
+    # @param schema [Hash] the JSON Schema for the response
+    # @param name [String] the schema name
+    # @param strict [Boolean, nil] whether strict schema adherence is requested;
+    #   omitted from the format when nil
+    # @param description [String, nil] an optional schema description
+    # @return [Hash] the resulting +text+ configuration
+    # @example
+    #   session.json_output({"type" => "object", "properties" => {...}}, strict: true)
+    def json_output(schema, name: "response", strict: nil, description: nil)
+      format = {"type" => "json_schema", "name" => name.to_s, "schema" => schema}
+      format["strict"] = strict unless strict.nil?
+      format["description"] = description.to_s if description
+      self.text = (text || {}).merge("format" => format)
+    end
+
+    # Configure reasoning/extended thinking portably across serializers.
+    # Stores a normalized +reasoning+ configuration; each serializer maps it
+    # to its native parameter:
+    #
+    # - +effort+ — Messages (+output_config.effort+), Chat Completions
+    #   (+reasoning_effort+), Gemini (+thinkingConfig.thinkingLevel+), and
+    #   Open Responses (+reasoning.effort+)
+    # - +budget_tokens+ — Messages (+thinking.budget_tokens+) and Gemini
+    #   (+thinkingConfig.thinkingBudget+); ignored by effort-based APIs
+    # - Converse supports neither and warns once at serialization time
+    #
+    # Pass either +effort+ or +budget_tokens+, not both — providers reject
+    # requests that set both controls. Direct +session.reasoning = {...}+
+    # assignment keeps working for provider-specific keys.
+    #
+    # @param enabled [Boolean] pass +false+ to clear the reasoning configuration
+    # @param effort [String, Symbol, nil] a portable effort level; one of
+    #   +minimal+, +low+, +medium+, +high+, +xhigh+, +max+ (unsupported levels
+    #   are omitted by serializers whose target API does not accept them)
+    # @param budget_tokens [Integer, nil] an explicit thinking token budget
+    # @return [Hash, nil] the resulting +reasoning+ configuration
+    # @raise [ArgumentError] if neither or both of +effort+ and +budget_tokens+
+    #   are given when enabling, or the values are invalid
+    # @example
+    #   session.think(effort: :medium)       # portable across serializers
+    #   session.think(budget_tokens: 8_000)  # explicit where supported
+    #   session.think(false)                 # disable
+    def think(enabled = true, effort: nil, budget_tokens: nil)
+      unless enabled
+        raise ArgumentError, "cannot combine think(false) with effort or budget_tokens" if effort || budget_tokens
+
+        return self.reasoning = nil
+      end
+
+      if effort && budget_tokens
+        raise ArgumentError, "pass either effort or budget_tokens, not both"
+      elsif effort.nil? && budget_tokens.nil?
+        raise ArgumentError, "think requires effort: or budget_tokens:"
+      end
+
+      if effort
+        effort = effort.to_s
+        unless THINK_EFFORT_LEVELS.include?(effort)
+          raise ArgumentError, "effort must be one of: #{THINK_EFFORT_LEVELS.join(", ")}"
+        end
+        self.reasoning = {"effort" => effort}
+      else
+        budget_tokens = Integer(budget_tokens)
+        raise ArgumentError, "budget_tokens must be positive" unless budget_tokens.positive?
+
+        self.reasoning = {"budget_tokens" => budget_tokens}
+      end
+    end
+
     # Return all tool definitions registered on this session.
     #
     # @return [Array<Tools::Definition>] all tool definitions

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prompt_builder
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Brian Durand