prompt_builder 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9eee723a908587c28aa7e606b0e6dad45e5958a9d895d29bd42f8d984153d6bc
-  data.tar.gz: ffbfa13cc4bdfacc09ace7fe99a46366847faa501db6710cd51cca7123c106b2
+  metadata.gz: a6a857e2a0958425d04263986bca11967fb575af1c1e40ada5bee63556447fe0
+  data.tar.gz: 9840a2750ac27e265aea1e25d9290ee3aecb56cd24889d5903b481891a2925db
 SHA512:
-  metadata.gz: 40023bf88305a391c88b8a189e2810e27ad5af96b2e5bbf3697296eb9b4f63a360239eed8022c343198ddeff09573874988a33372b40b7c15080603a7588f093
-  data.tar.gz: b9be150ab138503f29f7769f71d1ad8092cef42aa5ba04ecb4d156f070fa5dc9aecdc1995a31fabfa74ab93206d47c1a24428417e2055d999c4473669c335f59
+  metadata.gz: 70fe6418fdd6865e12ec8babb5d5a7542ff31e93b44e0dfb389c1e0853955d5657bbf3482462e1ec091fca8031ac988bfc70222195a8ad2fd50833eb2542c4a1
+  data.tar.gz: bd0d9abb2cbb42d10d70c8f1d15322cc58a4c88c6401f937a45844fbde2dcf8013b183cf19d206b1e4c0e48cf9c0a03fb3ad5b35c17ed083b12d7c73f00224c6

data/CHANGELOG.md

@@ -4,6 +4,32 @@ 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.3.0
+
+### Added
+
+- Response parsers now recognize API error payloads (OpenAI/Gemini `error` envelopes, Anthropic `type: "error"` responses, Bedrock exception bodies) and raise a `PromptBuilder::ErrorResponseError` (a subclass of `UnexpectedPayloadError`) containing the error message reported by the API.
+- `Session.new` accepts a `system:` shorthand that adds a system message, mirroring the existing `input:` shorthand.
+- `Session#clear` resets the conversation — items, `instructions`, and `previous_response_id` — while preserving model configuration and registered tools.
+- `Session#remove_tool` removes a registered tool by name (string or symbol); `Session#clear_tools` removes them all. Both return the removed definitions.
+- `Session#extra=` sets or clears provider-specific extra data after the session has been constructed. Keys are normalized to strings; assigning `nil` clears the data.
+- Message content hashes with a `text` key no longer require a `type` key; the type defaults to `input_text` (or `output_text` on assistant messages).
+- `Items::Message#system?`, `#user?`, and `#assistant?` role predicates.
+- The Converse serializer emits `cachePoint` markers from the `cache_point` extra on tool definitions and `FunctionCallOutput` items, in addition to content blocks.
+- `Session#to_h`/`Session.from_h` now round-trip the response boundary (`response_boundary_index`), and a `response_boundary_index=` setter is available for reconstructing session state.
+- `Session::INITIALIZE_OPTIONS` is now public API: the frozen Array of all keyword options accepted by the constructor, for code that needs to validate or partition an options hash before creating a session.
+
+### Changed
+
+- `Session#extra` always returns a Hash (previously `nil` when unset). The returned Hash is a copy; assign a modified copy back through `Session#extra=` to change it.
+- `Session#to_h` omits `extra` when it is empty.
+- `instructions` is now serialized after system/developer messages instead of before them, matching the Open Responses semantics of `instructions` applying to the current request.
+
+### Fixed
+
+- Serializers silently dropped `Content::Text` content (hashes with `type: "text"`) from messages, system prompts, and tool results; it is now serialized as text everywhere `InputText`/`OutputText` are, including cache markers from content extras. The Messages and Gemini serializers also dropped `OutputText` content from system messages.
+- Tool names are normalized to strings on registration, so registering the same tool by symbol and by string no longer creates duplicate definitions.
+
 ## 0.2.0
 
 ### Added

data/README.md

@@ -48,16 +48,28 @@ session = PromptBuilder::Session.new(
 session.user("What is the capital of France?")
 ```
 
-You can also pass an `input` shorthand to create a user message in one step:
+You can also pass `system` and `input` shorthands to create a system message and a user message in one step (equivalent to calling `session.system(...)` and `session.user(...)`):
 
 ```ruby
 session = PromptBuilder::Session.new(
   model: "gpt-5.4",
+  system: "You are a helpful assistant.",
   input: "What is the capital of France?"
 )
 ```
 
-Passing an option the constructor doesn't recognize (or both halves of an alias pair) raises an `ArgumentError`.
+Passing an option the constructor doesn't recognize raises an `ArgumentError`. The full list of supported constructor options is available as `PromptBuilder::Session::INITIALIZE_OPTIONS`.
+
+#### `instructions` vs. system and developer messages
+
+Although both can be used to steer the model's behavior, `instructions` and system/developer messages are not interchangeable in the Open Responses API:
+
+- `instructions` is a top-level request parameter, not part of the conversation. It is sent with every request, and in the Open Responses API it applies only to the request it accompanies — it is *not* carried over when chaining responses with `previous_response_id`. That makes it safe to change `session.instructions` at any point in a conversation; the new value simply applies from the next request onward.
+- `session.system(...)` and `session.developer(...)` create messages inside the conversation history (the `input` array). They occupy a position in the transcript like any other message, and once the session is chained with `previous_response_id` they become part of the server-stored history and are not re-sent on subsequent requests.
+
+As a rule of thumb, use `instructions` for standing behavior you may want to adjust from request to request, and use system or developer messages when the directive should be a durable part of the conversation record.
+
+When serializing to the other formats this distinction collapses: `instructions` and any system/developer messages are merged together into the target format's single system field (see [Serializer Compatibility](#serializer-compatibility)).
 
 ### Conversation History
 
@@ -71,7 +83,13 @@ session.assistant("Hi there! How can I help you today?")
 session.user("What's the weather like?")
 ```
 
-Messages support the roles `user`, `assistant`, `system`, and `developer`.
+Messages support the roles `user`, `assistant`, `system`, and `developer`. A `Message` exposes `system?`, `user?`, and `assistant?` predicates for checking its role.
+
+Call `session.clear` to reset the conversation: it removes all items and the `instructions`, drops any `previous_response_id`, and returns the session to a fresh local-state start. Model configuration and registered tools are preserved, so the session can be reused for a new conversation.
+
+```ruby
+session.clear   # items and instructions removed; model/config/tools kept
+```
 
 ### Serializing Requests
 
@@ -162,6 +180,13 @@ response.has_tool_calls? # => false
 response.usage           # => #<PromptBuilder::Usage input_tokens=25 output_tokens=12 ...>
 ```
 
+If the payload is an error returned by the API rather than a completion (e.g. an authentication failure, a validation error, or an AWS Coral service envelope), `Response.parse` raises a `PromptBuilder::ErrorResponseError` whose message contains the error reported by the API. Payloads that are neither a completion nor a recognizable error envelope raise a `PromptBuilder::UnexpectedPayloadError` (which `ErrorResponseError` subclasses) including the offending body.
+
+```ruby
+PromptBuilder::Response.parse({"error" => {"type" => "invalid_request_error", "message" => "Incorrect API key provided"}}, :chat_completion)
+# => raises PromptBuilder::ErrorResponseError: the API returned an error: invalid_request_error: Incorrect API key provided
+```
+
 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
@@ -298,6 +323,13 @@ 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.
 
+Remove tools from a session with `remove_tool` (by name; accepts a string or symbol) or `clear_tools` (all at once). `remove_tool` returns the removed `Tools::Definition`, or `nil` if no tool by that name was registered; `clear_tools` returns the removed definitions.
+
+```ruby
+session.remove_tool("weather")   # => removed Tools::Definition, or nil
+session.clear_tools              # => [<removed definitions>]
+```
+
 ### 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.
@@ -418,6 +450,8 @@ session = PromptBuilder::Session.new(
 
 The `extra` attribute on sessions, content blocks, and tool definitions lets you pass provider-specific parameters that are not part of the Open Responses canonical format. Each serializer recognizes a defined set of `extra` keys and maps them to the appropriate location in the target format. Unrecognized keys are silently ignored.
 
+On a session, `extra` is a read/write attribute that can be set at any point in the session's life. On content blocks and tool definitions it is set with keyword arguments at construction time.
+
 #### Session Extra
 
 Pass provider-specific top-level request parameters via `session.extra`:
@@ -471,6 +505,26 @@ session = PromptBuilder::Session.new(
 )
 ```
 
+The same data can be set after the session has been created by assigning to `session.extra`. Keys are normalized to strings, so symbol keys work too.
+
+```ruby
+session = PromptBuilder::Session.new(model: "anthropic.claude-v2")
+
+session.extra # => {}
+
+# Assign the whole hash.
+session.extra = {guardrail_config: {"guardrailIdentifier" => "my-guardrail", "guardrailVersion" => "1"}}
+
+# `extra` returns a copy, so read, modify, and assign it back to change one key.
+session.extra = session.extra.merge("stop_sequences" => ["\n\nHuman:"])
+session.extra = session.extra.except("stop_sequences")
+
+session.extra = nil # clears it
+```
+
+> [!IMPORTANT]
+> `session.extra` never returns `nil` and its keys are always strings. Because the reader returns a copy, mutating it in place has no effect on the session — `session.extra["seed"] = 42` is silently discarded. Assign the modified hash back as shown above.
+
 #### Content Extra
 
 Content blocks support provider-specific attributes via keyword arguments that are captured in the `extra` hash:
@@ -500,6 +554,21 @@ session.user([
     cache_point: true
   )
 ])
+
+# Bedrock Converse: cache_point on tool definitions and tool results
+session.register_tool(
+  "search",
+  description: "Search the knowledge base.",
+  parameters: {"type" => "object", "properties" => {"query" => {"type" => "string"}}},
+  cache_point: true
+)
+session.add_item(
+  PromptBuilder::Items::FunctionCallOutput.new(
+    call_id: "call_1",
+    output: "Search results...",
+    cache_point: true
+  )
+)
 ```
 
 #### Tool Definition Extra
@@ -518,12 +587,14 @@ session.register_tool(
 
 #### Recognized Extra Keys by Serializer
 
+Session extra keys can be supplied to the constructor or assigned later with `session.extra=`.
+
 | Serializer | Session Extra Keys | Content Extra Keys | Tool Extra Keys |
 |:---|:---|:---|:---|
 | **Chat Completions** | `stop`, `seed`, `logit_bias`, `n`, `prediction`, `web_search_options`, `modalities`, `audio` | `file_id`, `media_type` | — |
 | **Messages** | `top_k`, `stop_sequences`, `cache_control` | `cache_control`, `citations`, `file_id`, `media_type` | `cache_control` |
 | **Gemini** | `safety_settings`, `cached_content`, `stop_sequences`, `top_k`, `seed`, `candidate_count`, `response_modalities`, `media_resolution` | `file_id`, `media_type`, `thought_signature` | — |
-| **Converse** | `stop_sequences`, `guardrail_config`, `additional_model_request_fields`, `additional_model_response_field_paths`, `performance_config`, `prompt_variables` | `media_type`, `cache_point` | — |
+| **Converse** | `stop_sequences`, `guardrail_config`, `additional_model_request_fields`, `additional_model_response_field_paths`, `performance_config`, `prompt_variables` | `media_type`, `cache_point` | `cache_point` |
 
 ### Serialization and Persistence
 
@@ -794,7 +865,7 @@ 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 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.
+- 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`). `cache_point` is also recognized on tool definitions (the marker is appended to the `toolConfig.tools` array) and on `FunctionCallOutput` items (the marker is appended after the `toolResult` content block). 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:
@@ -802,7 +873,7 @@ 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` (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.
+- `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` extra on content, tool definitions, and `FunctionCallOutput` items.
 
 ## Installation
 

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/lib/prompt_builder/errors.rb

@@ -19,6 +19,11 @@ module PromptBuilder
   # Raised when a response payload does not match the expected shape.
   class UnexpectedPayloadError < Error; end
 
+  # Raised when a response payload is an error returned by the API rather
+  # than a completion (e.g. an authentication, validation, or throttling
+  # error envelope). The message contains the error reported by the API.
+  class ErrorResponseError < UnexpectedPayloadError; end
+
   # Raised by Response#parsed_json! when the response text is not valid JSON.
   class ParseError < Error; end
 end

data/lib/prompt_builder/items/message.rb

@@ -23,6 +23,24 @@ module PromptBuilder
       # @return [Hash, nil] provider-specific extra data
       attr_reader :extra
 
+      class << self
+        # Deserialize a Message from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [Message]
+        def from_h(hash)
+          content = (hash["content"] || []).map { |c| Content::Base.from_h(c) }
+          new(
+            id: hash["id"],
+            role: hash["role"],
+            status: hash["status"],
+            phase: hash["phase"],
+            content: content,
+            **hash.except("type", "id", "role", "status", "phase", "content").transform_keys(&:to_sym)
+          )
+        end
+      end
+
       # Create a new Message item.
       #
       # @param id [String, nil] the message identifier
@@ -40,22 +58,25 @@ module PromptBuilder
         @extra = extra.transform_keys(&:to_s)
       end
 
-      class << self
-        # Deserialize a Message from a Hash.
-        #
-        # @param hash [Hash] a Hash with string keys
-        # @return [Message]
-        def from_h(hash)
-          content = (hash["content"] || []).map { |c| Content::Base.from_h(c) }
-          new(
-            id: hash["id"],
-            role: hash["role"],
-            status: hash["status"],
-            phase: hash["phase"],
-            content: content,
-            **hash.except("type", "id", "role", "status", "phase", "content").transform_keys(&:to_sym)
-          )
-        end
+      # Check if the message is a system message.
+      #
+      # @return [Boolean]
+      def system?
+        role == "system"
+      end
+
+      # Check if the message is a user message.
+      #
+      # @return [Boolean]
+      def user?
+        role == "user"
+      end
+
+      # Check if the message is an assistant message.
+      #
+      # @return [Boolean]
+      def assistant?
+        role == "assistant"
       end
 
       # Serialize to a Hash with string keys.
@@ -102,6 +123,9 @@ module PromptBuilder
 
       def normalize_hash_content(hash)
         hash = hash.transform_keys(&:to_s)
+        if hash["type"].nil? && hash.key?("text")
+          hash = hash.merge("type" => (assistant? ? "output_text" : "input_text"))
+        end
         unless hash["type"]
           raise InvalidItemError,
             "Content hash is missing required \"type\" key: #{hash.inspect}"

data/lib/prompt_builder/serializers/base.rb

@@ -18,7 +18,9 @@ module PromptBuilder
         #
         # @param hash [Hash] the response hash in the target format
         # @return [Response] the parsed response
+        # @raise [ErrorResponseError] if the payload is an API error envelope
         def parse_response(hash)
+          check_error_response!(hash)
           deserialize_response(hash)
         end
 
@@ -32,6 +34,32 @@ module PromptBuilder
           raise NotImplementedError
         end
 
+        # Detect API error envelopes before parsing so errors surface with the
+        # message reported by the API instead of the generic missing-key error
+        # from require_response_key!. Serializer response classes override
+        # error_response_message to recognize their format's error envelope.
+        #
+        # @param hash [Object] the raw response payload
+        # @return [void]
+        # @raise [ErrorResponseError] if the payload is an API error envelope
+        def check_error_response!(hash)
+          return unless hash.is_a?(Hash)
+
+          message = error_response_message(hash)
+          return if message.nil? || message.empty?
+
+          raise ErrorResponseError, "the API returned an error: #{message}"
+        end
+
+        # Extract a human-readable message from an API error envelope.
+        #
+        # @param _hash [Hash] the raw response payload
+        # @return [String, nil] nil when the payload is not recognized as an
+        #   error envelope
+        def error_response_message(_hash)
+          nil
+        end
+
         # Ensure a response payload is a Hash containing the key that identifies
         # it as a well-formed response for this format. Raised before parsing so
         # malformed bodies (e.g. provider error envelopes) fail loudly with the

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

@@ -27,6 +27,10 @@ module PromptBuilder
       #   supported, and only when +stream+ is set (otherwise it is omitted)
       #
       # Input content restrictions:
+      # - +instructions+ is serialized as a system message inserted after the
+      #   last system/developer message, or first when there are none
+      #   (instructions apply to the current request, matching Open Responses
+      #   semantics)
       # - +InputVideo+ content is not supported in any message (omitted)
       # - +Reasoning+ items are not supported (skipped)
       # - +RefusalContent+ is dropped silently (a parsed Chat Completions
@@ -119,7 +123,8 @@ module PromptBuilder
             end
 
             # Session extra: recognized keys for Chat Completions API
-            apply_session_extra!(h, session.extra) if session.extra
+            extra = session.extra
+            apply_session_extra!(h, extra) unless extra.empty?
 
             h
           end
@@ -138,10 +143,6 @@ module PromptBuilder
           def build_messages(session)
             messages = []
 
-            if session.instructions
-              messages << {"role" => "system", "content" => session.instructions}
-            end
-
             pending_tool_calls = []
             last_assistant_msg = nil
 
@@ -171,9 +172,18 @@ module PromptBuilder
             end
 
             flush_tool_calls!(messages, pending_tool_calls, last_assistant_msg)
+            insert_instructions!(messages, session.instructions) if session.instructions
             messages
           end
 
+          # Instructions apply to the current request (matching Open Responses
+          # semantics), so they are inserted after the last system/developer
+          # message rather than before any of them.
+          def insert_instructions!(messages, instructions)
+            index = messages.rindex { |msg| msg["role"] == "system" || msg["role"] == "developer" }
+            messages.insert(index ? index + 1 : 0, {"role" => "system", "content" => instructions})
+          end
+
           def serialize_message(item)
             # Messages with an unsupported role are silently skipped.
             return nil unless SUPPORTED_MESSAGE_ROLES.include?(item.role)
@@ -198,7 +208,7 @@ module PromptBuilder
 
           def serialize_content(role, content)
             case content
-            when Content::InputText, Content::OutputText
+            when Content::InputText, Content::OutputText, Content::Text
               serialize_text_content(content)
             when Content::InputImage
               # Image content is only supported in user messages; omit otherwise.
@@ -241,7 +251,7 @@ module PromptBuilder
             # are silently omitted.
             content = output.filter_map do |content|
               case content
-              when Content::InputText, Content::OutputText
+              when Content::InputText, Content::OutputText, Content::Text
                 serialize_text_content(content)
               end
             end

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

@@ -16,6 +16,18 @@ module PromptBuilder
         class << self
           private
 
+          # OpenAI errors arrive as {"error" => {"message" => ..., "type" =>
+          # ..., "code" => ...}}; some compatible servers return a bare string
+          # under "error".
+          def error_response_message(hash)
+            error = hash["error"]
+            return nil if error.nil? || hash.key?("choices")
+
+            return error.to_s unless error.is_a?(Hash)
+
+            [error["code"] || error["type"], error["message"]].compact.join(": ")
+          end
+
           def deserialize_response(hash)
             validate_response!(hash)
 

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

@@ -39,6 +39,10 @@ module PromptBuilder
       # - +tool_choice: "none"+ has no Converse representation and is omitted
       #
       # Input content restrictions:
+      # - System and developer messages are hoisted out of conversational order
+      #   into the top-level +system+ parameter, with +instructions+ merged last
+      #   (instructions apply to the current request, matching Open Responses
+      #   semantics)
       # - +Reasoning+ items are silently skipped
       # - +RefusalContent+ is dropped silently (a parsed response refusal can
       #   stay in session history without breaking subsequent request_payload calls)
@@ -68,8 +72,11 @@ module PromptBuilder
       # - 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.
+      # extra on system/message content, tool definitions (appended to the
+      # +toolConfig.tools+ array), and +FunctionCallOutput+ items (appended to
+      # the message content after the +toolResult+ block). 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",
@@ -164,7 +171,8 @@ module PromptBuilder
             h["toolConfig"] = tool_config if tool_config
 
             # Session extra: recognized keys for Converse API
-            apply_session_extra!(h, session.extra) if session.extra
+            extra = session.extra
+            apply_session_extra!(h, extra) unless extra.empty?
 
             h
           end
@@ -194,8 +202,6 @@ module PromptBuilder
           def build_system(session)
             parts = []
 
-            parts << {"text" => session.instructions} if session.instructions
-
             session.items.each do |item|
               next unless item.is_a?(Items::Message)
               next unless item.role == "system" || item.role == "developer"
@@ -211,6 +217,11 @@ module PromptBuilder
               end
             end
 
+            # Instructions come last: in the Open Responses API they apply to
+            # the current request, so they must follow any system messages
+            # accumulated in the conversation history.
+            parts << {"text" => session.instructions} if session.instructions
+
             parts
           end
 
@@ -249,10 +260,14 @@ module PromptBuilder
                   }]
                 }
               when Items::FunctionCallOutput
-                raw_messages << {
-                  "role" => "user",
-                  "content" => [serialize_tool_result(item, ctx)]
-                }
+                # The Converse ToolResultContentBlock union has no cachePoint
+                # member; the marker must be a sibling content block after the
+                # toolResult block.
+                content = [serialize_tool_result(item, ctx)]
+                if item.extra && item.extra["cache_point"]
+                  content << {"cachePoint" => {"type" => "default"}}
+                end
+                raw_messages << {"role" => "user", "content" => content}
               when Items::Reasoning, Items::Compaction, Items::ItemReference
                 # Reasoning, Compaction, and ItemReference items are not supported
                 # in the request, so ignore them rather than raising an error.
@@ -265,7 +280,7 @@ module PromptBuilder
 
           def serialize_system_content(content)
             case content
-            when Content::InputText
+            when Content::InputText, Content::Text
               {"text" => content.text}
             when Content::OutputText
               validate_output_text!(content)
@@ -293,7 +308,7 @@ module PromptBuilder
 
           def serialize_content(content, role:, ctx: nil)
             case content
-            when Content::InputText, Content::OutputText
+            when Content::InputText, Content::OutputText, Content::Text
               validate_output_text!(content) if content.is_a?(Content::OutputText)
               {"text" => content.text}
             when Content::InputImage
@@ -512,7 +527,7 @@ module PromptBuilder
 
           def serialize_tool_result_content(content, ctx)
             case content
-            when Content::InputText, Content::OutputText
+            when Content::InputText, Content::OutputText, Content::Text
               validate_output_text!(content) if content.is_a?(Content::OutputText)
               {"text" => content.text}
             when Content::InputImage
@@ -610,13 +625,17 @@ module PromptBuilder
           end
 
           def build_tools(session)
-            session.tool_definitions.map do |definition|
+            session.tool_definitions.flat_map do |definition|
               tool_spec = {"name" => definition.name}
               tool_spec["description"] = definition.description if definition.description
               tool_spec["inputSchema"] = {
                 "json" => definition.parameters || {"type" => "object", "properties" => {}}
               }
-              {"toolSpec" => tool_spec}
+              tools = [{"toolSpec" => tool_spec}]
+              # The Converse Tool union type has a cachePoint member, so the
+              # marker is its own entry in the tools array.
+              tools << {"cachePoint" => {"type" => "default"}} if definition.extra["cache_point"]
+              tools
             end
           end
 

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

@@ -10,6 +10,21 @@ module PromptBuilder
         class << self
           private
 
+          # Bedrock exception bodies carry a top-level "message" (the exception
+          # class travels in the x-amzn-ErrorType header) or a top-level
+          # "__type", while misrouted requests get a Coral service envelope
+          # like {"Output" => {"__type" => "..."}, "Version" => "1.0"}.
+          def error_response_message(hash)
+            return nil if hash.key?("output")
+
+            coral_output = hash["Output"].is_a?(Hash) ? hash["Output"] : {}
+            error_type = hash["__type"] || coral_output["__type"]
+            message = hash["message"] || hash["Message"] || coral_output["message"] || coral_output["Message"]
+            return nil unless error_type || message
+
+            [error_type, message].compact.join(": ")
+          end
+
           def deserialize_response(hash)
             require_response_key!(hash, "output")
             require_response_key!(hash, "stopReason")

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

@@ -27,6 +27,12 @@ module PromptBuilder
       # - +truncation+ — server-side context truncation is not supported
       #
       # Input content restrictions:
+      # - System and developer messages are hoisted out of conversational order
+      #   into the top-level +systemInstruction+ field, with +instructions+ merged
+      #   last (instructions apply to the current request, matching Open Responses
+      #   semantics)
+      # - Only text content (+InputText+/+OutputText+/+Text+) survives in system
+      #   and developer messages; other content is silently omitted
       # - +InputImage+ content is only supported in user messages (assistant images are omitted)
       # - +InputImage+ with +image_url+ requires either base64 +data+ or a URL;
       #   content without +image_url+ or +file_id+ raises
@@ -136,7 +142,8 @@ module PromptBuilder
             h["toolConfig"] = tool_config if tool_config
 
             # Session extra: recognized keys for Gemini API
-            apply_session_extra!(h, session.extra) if session.extra
+            extra = session.extra
+            apply_session_extra!(h, extra) unless extra.empty?
 
             # Gemini selects streaming via endpoint (:streamGenerateContent)
             # rather than a request body field, so session.stream is a no-op
@@ -162,19 +169,24 @@ module PromptBuilder
           def build_system_instruction(session)
             parts = []
 
-            if session.instructions
-              parts << {"text" => session.instructions}
-            end
-
             session.items.each do |item|
               next unless item.is_a?(Items::Message)
               next unless item.role == "system" || item.role == "developer"
 
               item.content.each do |content|
-                parts << {"text" => content.text} if content.is_a?(Content::InputText)
+                if content.is_a?(Content::InputText) || content.is_a?(Content::OutputText) || content.is_a?(Content::Text)
+                  parts << {"text" => content.text}
+                end
               end
             end
 
+            # Instructions come last: in the Open Responses API they apply to
+            # the current request, so they must follow any system messages
+            # accumulated in the conversation history.
+            if session.instructions
+              parts << {"text" => session.instructions}
+            end
+
             return nil if parts.empty?
 
             {"parts" => parts}
@@ -274,7 +286,7 @@ module PromptBuilder
               # types are silently omitted.
               text = output.filter_map do |content|
                 case content
-                when Content::InputText, Content::OutputText
+                when Content::InputText, Content::OutputText, Content::Text
                   content.text
                 end
               end.join("\n")
@@ -307,7 +319,7 @@ module PromptBuilder
 
           def serialize_content(content, role:)
             case content
-            when Content::InputText, Content::OutputText
+            when Content::InputText, Content::OutputText, Content::Text
               part = {"text" => content.text}
               if content.extra && content.extra["thought_signature"]
                 part["thoughtSignature"] = content.extra["thought_signature"]

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

@@ -63,6 +63,15 @@ module PromptBuilder
         class << self
           private
 
+          # Gemini errors arrive as
+          # {"error" => {"code" => 400, "message" => ..., "status" => ...}}.
+          def error_response_message(hash)
+            error = hash["error"]
+            return nil unless error.is_a?(Hash) && !hash.key?("candidates")
+
+            [error["status"] || error["code"], error["message"]].compact.join(": ")
+          end
+
           def deserialize_response(hash)
             require_response_key!(hash, "candidates")
             require_response_key!(hash, "modelVersion")

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

@@ -36,6 +36,12 @@ module PromptBuilder
       #   is enabled
       #
       # Input content restrictions:
+      # - System and developer messages are hoisted out of conversational order
+      #   into the top-level +system+ parameter, with +instructions+ merged last
+      #   (instructions apply to the current request, matching Open Responses
+      #   semantics)
+      # - Only text content (+InputText+/+OutputText+/+Text+) survives in system
+      #   and developer messages; other content is silently omitted
       # - +InputVideo+ content is not supported and is omitted
       # - +RefusalContent+ is dropped silently (a parsed refusal can stay in
       #   session history without breaking subsequent request_payload calls)
@@ -115,7 +121,8 @@ module PromptBuilder
             h["stream"] = session.stream unless session.stream.nil?
 
             # Session extra: recognized keys for Messages API
-            apply_session_extra!(h, session.extra) if session.extra
+            extra = session.extra
+            apply_session_extra!(h, extra) unless extra.empty?
 
             output_config = build_output_config(session)
             h["output_config"] = output_config unless output_config.empty?
@@ -279,16 +286,12 @@ module PromptBuilder
           def build_system(session)
             parts = []
 
-            if session.instructions
-              parts << {"type" => "text", "text" => session.instructions}
-            end
-
             session.items.each do |item|
               next unless item.is_a?(Items::Message)
               next unless item.role == "system" || item.role == "developer"
 
               item.content.each do |content|
-                if content.is_a?(Content::InputText)
+                if content.is_a?(Content::InputText) || content.is_a?(Content::OutputText) || content.is_a?(Content::Text)
                   part = {"type" => "text", "text" => content.text}
                   if content.extra && content.extra["cache_control"]
                     part["cache_control"] = content.extra["cache_control"]
@@ -298,6 +301,13 @@ module PromptBuilder
               end
             end
 
+            # Instructions come last: in the Open Responses API they apply to
+            # the current request, so they must follow any system messages
+            # accumulated in the conversation history.
+            if session.instructions
+              parts << {"type" => "text", "text" => session.instructions}
+            end
+
             parts
           end
 
@@ -363,7 +373,7 @@ module PromptBuilder
 
           def serialize_content_block(content, role:)
             case content
-            when Content::InputText
+            when Content::InputText, Content::Text
               {"type" => "text", "text" => content.text}
             when Content::OutputText
               text = {"type" => "text", "text" => content.text}
@@ -492,7 +502,7 @@ module PromptBuilder
           # Document blocks are rejected by the API.
           def serialize_tool_result_content(content)
             case content
-            when Content::InputText, Content::OutputText
+            when Content::InputText, Content::OutputText, Content::Text
               {"type" => "text", "text" => content.text}
             when Content::InputImage
               serialize_content(content, role: "user")

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

@@ -10,6 +10,15 @@ module PromptBuilder
         class << self
           private
 
+          # Anthropic errors arrive as
+          # {"type" => "error", "error" => {"type" => ..., "message" => ...}}.
+          def error_response_message(hash)
+            error = hash["error"]
+            return nil unless error.is_a?(Hash) && !hash.key?("content")
+
+            [error["type"], error["message"]].compact.join(": ")
+          end
+
           def deserialize_response(hash)
             require_response_key!(hash, "content")
             require_response_key!(hash, "stop_reason")

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

@@ -28,6 +28,7 @@ module PromptBuilder
             payload = session.to_h
             items = apply_server_state!(payload, session)
             payload.delete("extra")
+            payload.delete("response_boundary_index")
             strip_extra(payload, items, session.tool_definitions)
             normalize_content_urls!(payload)
             strip_non_replayable_reasoning!(payload)

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

@@ -8,6 +8,16 @@ module PromptBuilder
         class << self
           private
 
+          # Open Responses request errors arrive as a bare {"error" => {...}}
+          # envelope. A failed response object also carries an "error" field,
+          # but it has a "status" and parses into a failed Response instead.
+          def error_response_message(hash)
+            error = hash["error"]
+            return nil unless error.is_a?(Hash) && !hash.key?("status")
+
+            [error["code"] || error["type"], error["message"]].compact.join(": ")
+          end
+
           def deserialize_response(hash)
             require_response_key!(hash, "status")
             require_response_key!(hash, "object")

data/lib/prompt_builder/session.rb

@@ -34,11 +34,17 @@ module PromptBuilder
     private_constant :THINK_EFFORT_LEVELS
 
     # All keyword options accepted by +initialize+.
+    #
+    # This constant is public API — unlike the private field-group constants
+    # above, it must not be marked with +private_constant+. Integrating gems
+    # use it to validate or partition option hashes before constructing a
+    # Session, e.g. +options.slice(*PromptBuilder::Session::INITIALIZE_OPTIONS)+.
+    #
+    # @api public
+    # @return [Array<Symbol>] the supported keyword option names
     INITIALIZE_OPTIONS = (
-      STRING_FIELDS + FLOAT_FIELDS + INTEGER_FIELDS + BOOLEAN_FIELDS + JSONIFY_FIELDS +
-        %i[input extra]
+      STRING_FIELDS + FLOAT_FIELDS + INTEGER_FIELDS + BOOLEAN_FIELDS + JSONIFY_FIELDS + %i[input extra system]
     ).freeze
-    private_constant :INITIALIZE_OPTIONS
 
     # @!attribute [rw] model
     #   @return [String, nil] the model identifier
@@ -122,10 +128,44 @@ module PromptBuilder
     # @return [Integer] the index in +items+ marking the boundary after the last response
     attr_reader :response_boundary_index
 
-    # @return [Hash, nil] provider-specific extra data for serializers.
-    #   Recognized keys vary by target format. Unrecognized keys are silently
-    #   ignored by each serializer.
-    attr_reader :extra
+    # Restore the response boundary, e.g. when deserializing a session. The
+    # value is clamped to the current item count. Normally the boundary is
+    # maintained by +add_response+; use this only to reconstruct state.
+    #
+    # @param index [Integer] the boundary index
+    # @return [Integer]
+    def response_boundary_index=(index)
+      @response_boundary_index = index.to_i.clamp(0, @items.length)
+    end
+
+    # Provider-specific extra data for serializers. Always returns a Hash, empty
+    # when nothing is set. Keys are always Strings.
+    #
+    # The returned Hash is a copy, so mutating it does not change the session.
+    # To add or remove a key, modify a copy and assign it back:
+    #
+    #   session.extra = session.extra.merge("guardrail_config" => {"guardrailIdentifier" => "gr-1"})
+    #
+    # Recognized keys vary by target format. Unrecognized keys are silently
+    # ignored by each serializer.
+    #
+    # @return [Hash] a copy of the provider-specific extra data
+    def extra
+      PromptBuilder.jsonify(@extra)
+    end
+
+    # Replace the provider-specific extra data. Keys are deep-stringified with
+    # +PromptBuilder.jsonify+ and the value is copied, so the assigned Hash is
+    # not shared with the session. Pass +nil+ to clear.
+    #
+    # @param value [Hash, nil] the extra data, or nil to clear it
+    # @return [Hash] the stored extra data
+    # @raise [ArgumentError] if the value is neither a Hash nor nil
+    def extra=(value)
+      raise ArgumentError, "extra must be a Hash" unless value.nil? || value.is_a?(Hash)
+
+      @extra = PromptBuilder.jsonify(value || {})
+    end
 
     class << self
       # Deserialize a Session from a Hash produced by +to_h+ or parsed JSON.
@@ -138,7 +178,7 @@ module PromptBuilder
       def from_h(hash)
         attrs = (STRING_FIELDS + FLOAT_FIELDS + INTEGER_FIELDS + BOOLEAN_FIELDS + JSONIFY_FIELDS)
           .each_with_object({}) { |f, acc| acc[f] = hash[f.to_s] }
-        attrs[:extra] = hash["extra"] if hash["extra"]
+        attrs[:extra] = hash["extra"]
         session = new(**attrs)
 
         Array(hash["input"]).each do |item_hash|
@@ -151,6 +191,8 @@ module PromptBuilder
           session.register_tool(defn.name, description: defn.description, parameters: defn.parameters, strict: defn.strict, **extra)
         end
 
+        session.response_boundary_index = hash["response_boundary_index"] if hash["response_boundary_index"]
+
         session
       end
     end
@@ -158,16 +200,18 @@ 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+ (or +user+) shorthand auto-creates a user message
-    # if provided. Unsupported keyword options raise an ArgumentError.
+    # to +nil+. The +system+ and +input+ shorthands auto-create a system and
+    # user message if provided. Unsupported keyword options raise an ArgumentError.
     #
     # @param attributes [Hash] keyword options; see attribute declarations above
+    # @option attributes [String, nil] :system optional string shorthand; a system
+    #   message is automatically added with this text
     # @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
+    #   serializers; recognized keys vary by target format. Keys are stringified.
+    #   Defaults to an empty Hash and can be replaced later with +extra=+.
+    # @raise [ArgumentError] if an unsupported option is passed
     def initialize(**attributes)
       unsupported = attributes.keys - INITIALIZE_OPTIONS
       unless unsupported.empty?
@@ -177,8 +221,12 @@ module PromptBuilder
       (STRING_FIELDS + FLOAT_FIELDS + INTEGER_FIELDS + BOOLEAN_FIELDS + JSONIFY_FIELDS).each do |f|
         send(:"#{f}=", attributes[f])
       end
-      @extra = PromptBuilder.jsonify(attributes[:extra]) if attributes[:extra]
+
+      self.extra = attributes[:extra]
+
       @items = []
+      system(attributes[:system]) if attributes[:system]
+
       @tool_definitions = {}
       @response_boundary_index = 0
       user(attributes[:input]) if attributes[:input]
@@ -192,6 +240,7 @@ module PromptBuilder
     #  session.user("Hello, how are you?")
     #  session.user(Content::InputText.new(text: "Hello, how are you?"))
     #  session.user(type: "input_text", text: "Hello, how are you?")
+    #  session.user(text: "Hello, how are you?") # type defaults to "input_text"
     #  session.user([
     #    Content::InputText.new(text: "What is in this image?"),
     #    Content::InputImage.new(url: "http://example.com/image.png")
@@ -216,6 +265,10 @@ module PromptBuilder
     #
     # @param content [String, Content::Base, Hash, Array<Content::Base>, Array<Hash>] the message content
     # @return [Items::Message] the added message
+    # @example
+    #  session.system("You are a helpful assistant.")
+    #  session.system(text: "You are a helpful assistant.") # type defaults to "input_text"
+    #  session.system(text: "You are a helpful assistant.", cache_point: true, cache_control: {type: "ephemeral"})
     def system(content)
       add_item(Items::Message.new(role: "system", content: content))
     end
@@ -268,6 +321,19 @@ module PromptBuilder
       @response_boundary_index = @items.length
     end
 
+    # Clear all conversation items and the system instructions, returning the
+    # session to a fresh local-state start. Model configuration and registered
+    # tools are preserved.
+    #
+    # @return [self]
+    def clear
+      @items.clear
+      self.instructions = nil
+      self.previous_response_id = nil
+      @response_boundary_index = 0
+      self
+    end
+
     # Register a tool on this session.
     #
     # @param name [String] the tool name
@@ -284,7 +350,7 @@ module PromptBuilder
         strict: strict,
         **extra
       )
-      @tool_definitions[name] = definition
+      @tool_definitions[name.to_s] = definition
       definition
     end
 
@@ -346,6 +412,31 @@ module PromptBuilder
       end
     end
 
+    # Remove a single registered tool by name. Accepts a string or symbol and
+    # matches regardless of how the tool's key was stored.
+    #
+    # @param name [String, Symbol] the tool name
+    # @return [Tools::Definition, nil] the removed definition, or nil if not found
+    def remove_tool(name)
+      key = name.to_s
+      removed = nil
+      @tool_definitions.delete_if do |k, defn|
+        match = k.to_s == key
+        removed = defn if match
+        match
+      end
+      removed
+    end
+
+    # Remove all registered tools from the session.
+    #
+    # @return [Array<Tools::Definition>] the removed tool definitions
+    def clear_tools
+      removed = @tool_definitions.values
+      @tool_definitions.clear
+      removed
+    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.
@@ -465,6 +556,7 @@ module PromptBuilder
 
       h["input"] = @items.map(&:to_h) unless @items.empty?
       h["previous_response_id"] = @previous_response_id if @previous_response_id
+      h["response_boundary_index"] = @response_boundary_index if @response_boundary_index.positive?
 
       h["tools"] = tool_definitions.map(&:to_h) unless @tool_definitions.empty?
 
@@ -488,7 +580,7 @@ module PromptBuilder
         val = send(f)
         h[f.to_s] = val if val
       }
-      h["extra"] = @extra if @extra
+      h["extra"] = extra unless @extra.empty?
 
       h
     end
@@ -509,7 +601,7 @@ module PromptBuilder
     def config_hash
       h = (STRING_FIELDS + FLOAT_FIELDS + INTEGER_FIELDS + BOOLEAN_FIELDS + JSONIFY_FIELDS - %i[previous_response_id])
         .each_with_object({}) { |f, acc| acc[f] = send(f) }
-      h[:extra] = @extra if @extra
+      h[:extra] = @extra
       h
     end
   end

data/prompt_builder.gemspec

@@ -36,6 +36,4 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.required_ruby_version = ">= 3.0"
-
-  spec.add_development_dependency "bundler"
 end

metadata

@@ -1,28 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prompt_builder
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Brian Durand
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
+dependencies: []
 email:
 - bbdurand@gmail.com
 executables: []