prompt_builder 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2572a48b69686a8b061f84fd174dfc164adbfe0c613894bfcbb26fd0039d5108
-  data.tar.gz: c5382987c1d85d31b6cef3f6bb90cc1e4491d1e27d1dd2587d08f2d099360c4f
+  metadata.gz: 9eee723a908587c28aa7e606b0e6dad45e5958a9d895d29bd42f8d984153d6bc
+  data.tar.gz: ffbfa13cc4bdfacc09ace7fe99a46366847faa501db6710cd51cca7123c106b2
 SHA512:
-  metadata.gz: 75ac02437e15581cf45c13c592605b6434c0634141bda6d86324e87bb65c59502e1de00f7459c49fb6b3f432a8a2ec2c5487eab4f73de1609c26625bdb37c510
-  data.tar.gz: 3c39ea80cbdb488a63926357601ce47b97cd5940c8ee95742b31b4df30e4b4519cf98dec931e11929ddb80569a0a469736a37aa6337af44dc53092f433051714
+  metadata.gz: 40023bf88305a391c88b8a189e2810e27ad5af96b2e5bbf3697296eb9b4f63a360239eed8022c343198ddeff09573874988a33372b40b7c15080603a7588f093
+  data.tar.gz: b9be150ab138503f29f7769f71d1ad8092cef42aa5ba04ecb4d156f070fa5dc9aecdc1995a31fabfa74ab93206d47c1a24428417e2055d999c4473669c335f59

data/CHANGELOG.md

@@ -4,6 +4,40 @@ 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
+
+- `Session#add_function_call_output` raised a `NameError`; it now correctly builds an `Items::FunctionCallOutput`.
+- Provider-specific `extra` data on items, content blocks, and tool definitions (e.g. `cache_control`, `cache_point`, `thought_signature`, `media_type`) leaked into Open Responses request payloads and would be rejected as unknown parameters. It is now stripped from `request_payload(:open_responses)`.
+- The Messages serializer emitted all `OutputText.annotations` as text-block `citations`, including annotation shapes from other providers (e.g. Chat Completions `url_citation`) that the Anthropic API rejects. Only valid Anthropic citation types are now emitted.
+- The Chat Completions serializer emitted tool messages with an empty content array when a tool result contained no text content; it now collapses to an empty string.
+- The Chat Completions response parser duplicated message-level `annotations` and `logprobs` onto every text block; they are now attached only to the first.
+- `PromptBuilder.parse_data_url` now accepts data URLs with media type parameters (e.g. `data:text/plain;charset=utf-8;base64,...`).
+
+### Added
+
+- `Response#provider_data` as an alias for `Response#extra`.
+
 ## 0.1.1
 
 ### Changed

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:
@@ -78,11 +80,11 @@ Once you've built a session, serialize it to a request payload for the API you w
 **Open Responses API**:
 
 ```ruby
-payload = session.to_h
-# or
 payload = session.request_payload(:open_responses)
 ```
 
+Note that `session.to_h` is *not* a request payload — it is the persistence format used by `Session.from_h` and keeps provider-specific `extra` data, canonical `url` content keys, and non-replayable items that the Open Responses API would reject. Always build request payloads through `request_payload`.
+
 **OpenAI Chat Completions API**:
 
 ```ruby
@@ -117,7 +119,7 @@ uri = URI("https://api.openai.com/v1/responses")
 request = Net::HTTP::Post.new(uri)
 request["Authorization"] = "Bearer #{api_key}"
 request["Content-Type"] = "application/json"
-request.body = JSON.generate(session.to_h)
+request.body = JSON.generate(session.request_payload(:open_responses))
 
 response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
   http.request(request)
@@ -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.
@@ -535,7 +596,7 @@ The following table shows which session configuration fields are supported by ea
 ⁹ `RefusalContent` blocks are dropped silently by all request serializers so a parsed refusal can sit in session history without breaking subsequent `request_payload` calls. A message left empty after stripping is omitted entirely.
 ¹⁰ Chat Completions sends `InputFile` as a `{"type": "file", "file": {...}}` content block. `file_id` (Files API) and base64 data URL (with optional `filename`/`media_type`) are supported. A URL-only `InputFile` (non-data URL) is omitted because Chat Completions has no remote-URL form for files.
 ¹¹ `OutputText.annotations` (e.g. URL citations from `web_search_options`) are parsed onto the assistant message and round-trip through session history, but are dropped silently on Chat Completions and Converse request serialization since those formats have no request-side equivalent. `OutputText.logprobs` is likewise dropped.
-¹² Messages text-block `citations` are parsed into `OutputText.annotations` and emitted back as `citations` when serializing Messages history. Document/tool-result citation opt-ins are still not modeled.
+¹² Messages text-block `citations` are parsed into `OutputText.annotations` and emitted back as `citations` when serializing Messages history. Annotations from other providers (e.g. a Chat Completions `url_citation`) are silently dropped since they are not valid Anthropic citation shapes. Document/tool-result citation opt-ins are still not modeled.
 ¹³ Converse `requestMetadata` only accepts string key/value pairs. This serializer stringifies scalar metadata values and silently omits nested arrays or objects.
 
 ### Features Not Accessible Through Open Responses
@@ -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 |
@@ -617,7 +680,7 @@ Request-side mappings worth calling out:
 | `InputFile` with data URL (+ optional `filename`/`media_type`) | `{"type": "file", "file": {"filename": ..., "file_data": "data:<media_type>;base64,..."}}` |
 | `InputImage` with data URL (+ `media_type`) | `{"type": "image_url", "image_url": {"url": "data:<media_type>;base64,..."}}` |
 
-Unsupported Chat Completions request features not exposed by this gem include audio input/output (`audio`, `modalities`, `input_audio` content), `web_search_options`, custom tools, `tool_choice: {"type": "allowed_tools", ...}`, `seed`, `stop`, `logit_bias`, `n`, `prediction`, and the deprecated `functions`, `function_call`, `max_tokens`, and `user` fields. Use the modern canonical fields when available (`tools`, `tool_choice`, `max_output_tokens`, `safety_identifier`, `prompt_cache_key`).
+Chat Completions request features with no canonical Open Responses field are available through `session.extra` (`stop`, `seed`, `logit_bias`, `n`, `prediction`, `web_search_options`, `modalities`, `audio`). Features not exposed at all include `input_audio` content blocks, custom tools, `tool_choice: {"type": "allowed_tools", ...}`, and the deprecated `functions`, `function_call`, `max_tokens`, and `user` fields. Use the modern canonical fields when available (`tools`, `tool_choice`, `max_output_tokens`, `safety_identifier`, `prompt_cache_key`).
 
 Response-side behavior and limitations:
 
@@ -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 |
@@ -676,7 +743,7 @@ Content and message restrictions:
 - Assistant messages map to `role: "model"`; consecutive same-role turns are merged automatically.
 - `InputImage`, `InputFile`, and `InputVideo` are only supported in user messages; the same content on an assistant message is omitted.
 - `InputImage` accepts any URL, a base64 data URL (with required `media_type`), or a Files API `file_id`.
-- `InputFile` accepts any URL, a base64 data URL, or `file_id`. `media_type` is required when not inferable from a `filename` or URL extension. Recognized extensions: `pdf`, `txt`, `md`/`markdown`, `html`/`htm`, `csv`, `json`, `xml`, `rtf`.
+- `InputFile` accepts any URL, a base64 data URL, or `file_id`. `media_type` is required when not inferable from a `filename` or URL extension. Recognized extensions cover documents (`pdf`, `txt`, `md`/`markdown`, `html`/`htm`, `csv`, `json`, `xml`, `rtf`), images (`png`, `jpg`/`jpeg`, `webp`, `heic`, `heif`), audio (`mp3`, `wav`, `aiff`, `aac`, `ogg`, `flac`), and video (`mp4`, `mov`, `webm`, `mpeg`/`mpg`).
 - `InputVideo` requires a URL; raw bytes are not modeled.
 - `RefusalContent` is dropped silently so a parsed Chat Completions refusal can sit in session history without breaking subsequent serialization.
 - `Reasoning` items round-trip via `parts[].thought` with `thoughtSignature` preserved. `redacted_thinking`, `summary`, and unknown reasoning block types are silently skipped.
@@ -689,7 +756,7 @@ Response-side limitations:
 
 - Unknown response `Part` shapes (`inlineData`, `fileData`, `executableCode`, `codeExecutionResult`, `videoMetadata`, server-side `toolCall`/`toolResponse`, or any `Part` without a recognized content key) are silently skipped.
 - Only `candidates[0]` is parsed. When `candidateCount > 1`, additional candidates are dropped (their index is preserved on `provider_data`).
-- Function-call `id` from the response is dropped; the parser synthesizes `gemini_call_<seed>_<n>` so multiple calls in one response share a deterministic seed.
+- Function-call `id` from the response is preserved when present; otherwise the parser synthesizes `gemini_call_<seed>_<n>` so multiple calls in one response share a deterministic seed.
 - `finishReason` mappings: `STOP` → `completed`; `MAX_TOKENS` → `incomplete`; `SAFETY`, `RECITATION`, `OTHER`, `BLOCKLIST`, `PROHIBITED_CONTENT`, `SPII`, `MALFORMED_FUNCTION_CALL`, `IMAGE_SAFETY`, `LANGUAGE`, `UNEXPECTED_TOOL_CALL`, `TOO_MANY_TOOL_CALLS`, `MODEL_ARMOR` → `failed`. `FINISH_REASON_UNSPECIFIED` is treated as nil.
 - An empty `candidates` array combined with `promptFeedback.blockReason` is mapped to `failed`.
 - `usageMetadata.cachedContentTokenCount`, `toolUsePromptTokenCount`, `promptTokensDetails`, `cacheTokensDetails`, and `toolUsePromptTokensDetails` populate `response.usage.input_tokens_details`. `thoughtsTokenCount` and `candidatesTokensDetails` populate `response.usage.output_tokens_details`.
@@ -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 |
@@ -725,14 +794,15 @@ Content and message restrictions:
 - `FunctionCall.arguments` must parse to a JSON object; non-object JSON values raise (Bedrock's `toolUse.input` requires an object).
 - `FunctionCallOutput.output` content supports `InputText`/`OutputText`, `InputImage`, `InputFile`, and `InputVideo`, mapping to Converse `text`, `image`, `document`, and `video` tool result blocks. Converse also supports `json` and `searchResult` tool result blocks, but this gem has no canonical content types for them, so unsupported content is omitted. `FunctionCallOutput.status` is mapped: `completed` → `success`, `failed`/`incomplete` → `error`, anything else passes through or is dropped.
 - `tool_choice: "none"` and `tool_choice` without registered tools are both omitted.
-- Converse API request features not exposed by this gem include `stopSequences`, `additionalModelRequestFields`, `additionalModelResponseFieldPaths`, `guardrailConfig` / `guardContent`, `cachePoint`, Prompt Management `promptVariables`, audio blocks, `searchResult` blocks, and `performanceConfig.latency`.
+- Converse API request features with no canonical Open Responses field are available through `session.extra` (`stop_sequences`, `guardrail_config`, `additional_model_request_fields`, `additional_model_response_field_paths`, `performance_config`, `prompt_variables`) and content `extra` (`cache_point`). Features not exposed at all include `guardContent`, audio blocks, and `searchResult` blocks.
+- The serialized payload includes `modelId` as a convenience; the Converse REST endpoint takes the model id in the URL path (`/model/{modelId}/converse`), and AWS REST-JSON services ignore unrecognized body members. Remove it from the body if you prefer a strictly minimal payload.
 
 Response-side limitations:
 
 - Unknown content block keys (e.g. `citationsContent`, `guardContent`) are silently skipped.
 - `metrics.latencyMs`, `trace` (guardrail and prompt-router trace events), `additionalModelResponseFields`, `performanceConfig`, and the raw `serviceTier` object are exposed on `response.provider_data`. `response.service_tier` is also populated from `serviceTier.type`.
-- `stopReason` mappings: `end_turn` / `tool_use` / `stop_sequence` → `completed`, `max_tokens` / `model_context_window_exceeded` → `incomplete`, `guardrail_intervened` / `content_filtered` / `malformed_model_output` / `malformed_tool_use` → `failed`. Unlike the Messages serializer, the matched stop sequence text is not surfaced separately because Converse does not echo it back unless you request provider-specific fields through `additionalModelResponseFieldPaths`, which this gem cannot emit.
-- `usage.cacheReadInputTokens` and `usage.cacheWriteInputTokens` populate `response.usage.input_tokens_details["cached_tokens"]` and `["cache_creation_input_tokens"]`. Cache writes still require `cachePoint` markers in the request, which this gem cannot produce.
+- `stopReason` mappings: `end_turn` / `tool_use` / `stop_sequence` → `completed`, `max_tokens` / `model_context_window_exceeded` → `incomplete`, `guardrail_intervened` / `content_filtered` / `malformed_model_output` / `malformed_tool_use` → `failed`. Unlike the Messages serializer, the matched stop sequence text is not surfaced separately because Converse does not echo it back unless you request provider-specific fields through `additionalModelResponseFieldPaths` (available via the `additional_model_response_field_paths` session extra; the requested fields appear on `response.provider_data`).
+- `usage.cacheReadInputTokens` and `usage.cacheWriteInputTokens` populate `response.usage.input_tokens_details["cached_tokens"]` and `["cache_creation_input_tokens"]`. Cache writes require `cachePoint` markers in the request, which are emitted via the `cache_point` content extra.
 
 ## Installation
 

data/VERSION

@@ -1 +1 @@
-0.1.1
+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.
@@ -125,6 +127,14 @@ module PromptBuilder
     FIELDS.each { |f| attr_reader f }
     attr_reader :text_config, :output, :usage, :extra
 
+    # @!method provider_data
+    #   Provider-specific response metadata with no canonical Open Responses
+    #   slot (e.g. Gemini grounding metadata, Chat Completions system_fingerprint).
+    #   Alias for +extra+.
+    #
+    #   @return [Hash, nil]
+    alias_method :provider_data, :extra
+
     BOOLEAN_FIELDS.each { |f| alias_method("#{f}?", f) }
 
     # Create a new Response.
@@ -165,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.
@@ -216,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]
@@ -238,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
@@ -228,12 +239,16 @@ module PromptBuilder
 
             # Only text content is supported in tool output; other content types
             # are silently omitted.
-            output.filter_map do |content|
+            content = output.filter_map do |content|
               case content
               when Content::InputText, Content::OutputText
                 serialize_text_content(content)
               end
             end
+
+            # Chat Completions rejects tool messages with an empty content
+            # array; collapse to an empty string like the other serializers.
+            content.empty? ? "" : content
           end
 
           def flush_tool_calls!(messages, pending_tool_calls, last_assistant_msg = nil)

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

@@ -36,6 +36,10 @@ module PromptBuilder
                   content: [Content::RefusalContent.new(refusal: message["refusal"])]
                 )
               elsif message["content"].is_a?(Array)
+                # logprobs and annotations are reported once per message, so
+                # attach them to the first text block only to avoid duplicating
+                # them across blocks on round-trip.
+                first_text_block = true
                 contents = message["content"].each_with_object([]) do |block, acc|
                   case block["type"]
                   when "text", nil
@@ -44,9 +48,10 @@ module PromptBuilder
 
                     acc << Content::OutputText.new(
                       text: text,
-                      logprobs: logprobs_content,
-                      annotations: annotations
+                      logprobs: first_text_block ? logprobs_content : [],
+                      annotations: first_text_block ? annotations : []
                     )
+                    first_text_block = false
                   when "refusal"
                     acc << Content::RefusalContent.new(refusal: block["refusal"]) if block["refusal"]
                   else

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
@@ -55,15 +59,17 @@ module PromptBuilder
       # === Features in Converse not available through Open Responses
       #
       # The following Converse parameters cannot be set through the Open Responses
-      # canonical format:
-      # - +stopSequences+ — custom stop sequences
-      # - Guardrail policies (+guardrailConfig+)
-      # - Per-model passthrough fields (+additionalModelRequestFields+)
-      # - Requested provider response fields (+additionalModelResponseFieldPaths+)
-      # - Cross-region routing via inference profiles
-      # - +performanceConfig+ latency settings beyond +serviceTier+
-      # - Prompt management variables (+promptVariables+)
-      # - Prompt caching markers (+cachePoint+)
+      # canonical format but are recognized via session +extra+ keys:
+      # - +stopSequences+ — custom stop sequences (+stop_sequences+)
+      # - Guardrail policies (+guardrail_config+)
+      # - Per-model passthrough fields (+additional_model_request_fields+)
+      # - Requested provider response fields (+additional_model_response_field_paths+)
+      # - +performanceConfig+ latency settings (+performance_config+)
+      # - Prompt management variables (+prompt_variables+)
+      #
+      # Prompt caching markers (+cachePoint+) are emitted via the +cache_point+
+      # content extra. Cross-region routing via inference profiles is selected
+      # through the model id and needs no request field.
       class Request < Base
         IMAGE_MEDIA_TYPE_FORMATS = {
           "image/jpeg" => "jpeg",
@@ -108,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)
@@ -116,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?
@@ -152,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
@@ -76,6 +82,17 @@ module PromptBuilder
         SUPPORTED_THINKING_TYPES = ["adaptive", "disabled", "enabled"].freeze
         SUPPORTED_TOOL_CHOICE_TYPES = ["any", "auto", "none", "tool"].freeze
 
+        # Citation types accepted by the Messages API on text blocks. Annotations
+        # parsed from other providers (e.g. Chat Completions url_citation) have
+        # no Anthropic equivalent and are silently dropped.
+        SUPPORTED_CITATION_TYPES = [
+          "char_location",
+          "content_block_location",
+          "page_location",
+          "search_result_location",
+          "web_search_result_location"
+        ].freeze
+
         class << self
           private
 
@@ -84,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)
@@ -238,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"
@@ -340,7 +367,8 @@ module PromptBuilder
               {"type" => "text", "text" => content.text}
             when Content::OutputText
               text = {"type" => "text", "text" => content.text}
-              text["citations"] = content.annotations unless content.annotations.empty?
+              citations = serialize_citations(content.annotations)
+              text["citations"] = citations unless citations.empty?
               text
             when Content::InputImage
               # Assistant image content is not supported; omit it.
@@ -424,6 +452,16 @@ module PromptBuilder
             end
           end
 
+          # Only annotations that are valid Anthropic citation objects can be
+          # replayed as citations. Annotations from other providers (e.g. a
+          # Chat Completions url_citation) are silently dropped so a
+          # cross-provider session history doesn't produce an invalid request.
+          def serialize_citations(annotations)
+            annotations.select do |annotation|
+              annotation.is_a?(Hash) && SUPPORTED_CITATION_TYPES.include?(annotation["type"])
+            end
+          end
+
           # FunctionCallOutput.status values that map to tool_result.is_error.
           # "incomplete" and "failed" cover the OR canonical statuses; "error"
           # is accepted as a convenience alias.

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

@@ -4,17 +4,31 @@ 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
+        # dedicated attribute for them).
+        CANONICAL_EXTRA_KEYS = {
+          "input_file" => ["file_id"].freeze,
+          "input_image" => ["file_id"].freeze
+        }.freeze
+        private_constant :CANONICAL_EXTRA_KEYS
+
         class << self
           # Export a session to Open Responses API request payload.
           #
           # @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
-            apply_server_state!(payload, session)
+            items = apply_server_state!(payload, session)
             payload.delete("extra")
-            strip_extra(payload)
+            strip_extra(payload, items, session.tool_definitions)
             normalize_content_urls!(payload)
             strip_non_replayable_reasoning!(payload)
             strip_output_only_fields!(payload)
@@ -28,36 +42,78 @@ module PromptBuilder
           # When the session is in server-state mode, replace the full input
           # array with only items added after the last response boundary and
           # include previous_response_id for the API to resolve history.
+          # Returns the item objects backing the payload's input array.
           def apply_server_state!(payload, session)
-            return if session.local_state?
+            return session.items if session.local_state?
 
             payload.delete("input")
-            new_items = session.items[session.response_boundary_index..]
-            payload["input"] = new_items.map(&:to_h) if new_items && !new_items.empty?
+            new_items = session.items[session.response_boundary_index..] || []
+            payload["input"] = new_items.map(&:to_h) unless new_items.empty?
+            new_items
           end
 
-          # Walk the payload and remove any "extra" keys from items, content
-          # blocks, and tool definitions since they are not part of the Open
-          # Responses API schema.
-          def strip_extra(payload)
+          # Remove provider-specific extra data from items, content blocks, and
+          # tool definitions since it is not part of the Open Responses API
+          # schema. Items, content blocks, and tool definitions serialize their
+          # extras flat into the hash, so the extra keys must be looked up on
+          # the backing objects rather than removed as a nested "extra" key.
+          def strip_extra(payload, items, tool_definitions)
             input = payload["input"]
             if input.is_a?(Array)
-              input.each do |item|
-                next unless item.is_a?(Hash)
+              input.each_with_index do |item_hash, index|
+                next unless item_hash.is_a?(Hash)
+
+                item = items[index]
+                next unless item
 
-                item.delete("extra")
+                strip_extra_keys!(item_hash, item.extra)
 
-                if item["type"] == "function_call_output" && item["output"].is_a?(Array)
-                  strip_extra_from_blocks!(item["output"])
-                else
-                  content = item["content"]
-                  strip_extra_from_blocks!(content) if content.is_a?(Array)
+                case item
+                when Items::Message
+                  strip_extra_from_blocks!(item_hash["content"], item.content)
+                when Items::FunctionCallOutput
+                  strip_extra_from_blocks!(item_hash["output"], item.output) if item.output.is_a?(Array)
                 end
               end
             end
 
             tools = payload["tools"]
-            strip_extra_from_blocks!(tools) if tools.is_a?(Array)
+            if tools.is_a?(Array)
+              tools.each_with_index do |tool_hash, index|
+                next unless tool_hash.is_a?(Hash)
+
+                definition = tool_definitions[index]
+                strip_extra_keys!(tool_hash, definition.extra) if definition
+              end
+            end
+          end
+
+          def strip_extra_from_blocks!(blocks, contents)
+            return unless blocks.is_a?(Array)
+
+            blocks.each_with_index do |block, index|
+              next unless block.is_a?(Hash)
+
+              content = contents[index]
+              next unless content.respond_to?(:extra)
+
+              keep = CANONICAL_EXTRA_KEYS.fetch(block["type"], [])
+              strip_extra_keys!(block, content.extra, keep: keep)
+            end
+          end
+
+          def strip_extra_keys!(hash, extra, keep: [])
+            return unless extra.is_a?(Hash)
+
+            extra.each_key do |key|
+              # "type" is canonical on every item and content block; an extra
+              # named "type" never survives serialization, so deleting it here
+              # would corrupt the block.
+              next if key == "type"
+              next if keep.include?(key)
+
+              hash.delete(key)
+            end
           end
 
           # Convert canonical "url" keys back to Open Responses API keys:
@@ -201,14 +257,6 @@ module PromptBuilder
             normalized.empty? ? nil : normalized
           end
 
-          def strip_extra_from_blocks!(blocks)
-            blocks.each do |block|
-              next unless block.is_a?(Hash)
-
-              block.delete("extra")
-            end
-          end
-
           # Normalize text.format for the Responses API. If the format uses
           # the Chat Completions nested json_schema sub-object, flatten it
           # so name/schema/strict/description sit directly under format.

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
@@ -210,10 +231,10 @@ module PromptBuilder
     # Add a tool call output to the conversation.
     #
     # @param call_id [String] the tool call identifier
-    # @param result [String, Hash, Array, Content::Base, nil] the tool call result
-    # @return [Items::FunctionOutput] the added function output item
+    # @param result [String, Array<Content::Base, Hash>, nil] the tool call result
+    # @return [Items::FunctionCallOutput] the added function call output item
     def add_function_call_output(call_id:, result:)
-      add_item(Items::FunctionOutput.new(call_id: call_id, result: result))
+      add_item(Items::FunctionCallOutput.new(call_id: call_id, output: result))
     end
 
     # Add a raw item to the conversation.
@@ -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

data/lib/prompt_builder.rb

@@ -44,14 +44,16 @@ module PromptBuilder
       "data:#{content_type};base64,#{[data].pack("m0")}"
     end
 
-    # Parse a data URL into its media type and base64-encoded data.
+    # Parse a data URL into its media type and base64-encoded data. Media type
+    # parameters (e.g. "data:text/plain;charset=utf-8;base64,...") are allowed
+    # and excluded from the returned media type.
     #
     # @param url [String, nil] a URL that may be a data URL
     # @return [Array(String, String), nil] a two-element array of +[media_type, data]+
-    #   or nil if the URL is not a data URL
+    #   or nil if the URL is not a base64-encoded data URL
     def parse_data_url(url)
       return nil unless url
-      match = url.match(/\Adata:([^;]+);base64,(.*)\z/m)
+      match = url.match(/\Adata:([^;,]+)(?:;[^,]*)?;base64,(.*)\z/m)
       return nil unless match
       [match[1], match[2]]
     end

metadata

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