prompt_builder 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6a857e2a0958425d04263986bca11967fb575af1c1e40ada5bee63556447fe0
-  data.tar.gz: 9840a2750ac27e265aea1e25d9290ee3aecb56cd24889d5903b481891a2925db
+  metadata.gz: 81ca025b0770c1b045ba525bc7fb6839a25b2d0b760b06ba85698de84c0a36b7
+  data.tar.gz: e8fc9eded433a202f7b2c6e9c79d0a0f8a9325b156cc884d09e1f7af535679a0
 SHA512:
-  metadata.gz: 70fe6418fdd6865e12ec8babb5d5a7542ff31e93b44e0dfb389c1e0853955d5657bbf3482462e1ec091fca8031ac988bfc70222195a8ad2fd50833eb2542c4a1
-  data.tar.gz: bd0d9abb2cbb42d10d70c8f1d15322cc58a4c88c6401f937a45844fbde2dcf8013b183cf19d206b1e4c0e48cf9c0a03fb3ad5b35c17ed083b12d7c73f00224c6
+  metadata.gz: e5eab3ec44e9c2a958b60d6c8c24dd740c8586eef8e5d05b6d0ab67807bc5526c3946b8ddd50439d60a860fdcc96e7372d637c552d15938383ef36ecfa173486
+  data.tar.gz: b0aaf0e28017996c603101d8fbde94fc4c242ffa42d471caa7cb0bbaad55f812962873237cf839d51755a86d844ec4fe7676516d3ed8c87df322a6bcd33b424c

data/CHANGELOG.md

@@ -4,6 +4,12 @@ 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.4.0
+
+### Added
+
+- `Response.parse` (and the serializer `parse_response` methods) accept an optional `headers:` keyword with the HTTP response headers, for formats that return response metadata in headers rather than in the body. The Converse serializer uses it to populate `Response#id` from the `x-amzn-requestid` request metadata header, since the Converse API does not include a response id in the body. The header name lookup is case-insensitive.
+
 ## 0.3.0
 
 ### Added

data/README.md

@@ -171,6 +171,13 @@ You can also pass a serializer class directly:
 response = PromptBuilder::Response.parse(JSON.parse(response_body), PromptBuilder::Serializers::ChatCompletion)
 ```
 
+`Response.parse` accepts an optional `headers:` keyword with the HTTP response headers, for formats that return response metadata in headers rather than in the body. The Converse API is one of them: Bedrock puts the response id in the `x-amzn-requestid` request metadata header, so pass the headers to populate `response.id` (the header name lookup is case-insensitive):
+
+```ruby
+response = PromptBuilder::Response.parse(JSON.parse(response_body), :converse, headers: http_response_headers)
+response.id # => "6e1d5a7b-..."
+```
+
 The `Response` object provides convenient accessors:
 
 ```ruby

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

data/lib/prompt_builder/response.rb

@@ -158,10 +158,18 @@ module PromptBuilder
       # @param serializer_class [Class, Symbol] a serializer class (e.g. Serializers::ChatCompletion)
       #   or a symbol shorthand (+:open_responses+, +:chat_completion+, +:messages+,
       #   +:gemini+, +:converse+)
+      # @param headers [Hash, #each, nil] the HTTP response headers, for formats
+      #   that return response metadata in headers rather than in the body
+      #   (e.g. the Converse response id)
       # @return [Response]
       # @raise [ArgumentError] if a symbol is given that does not map to a known serializer
-      def parse(hash, serializer_class)
-        Serializers.resolve(serializer_class).parse_response(hash)
+      def parse(hash, serializer_class, headers: nil)
+        serializer = Serializers.resolve(serializer_class)
+        # Send the keyword only when headers are given, so serializer classes
+        # whose parse_response does not accept it keep working.
+        return serializer.parse_response(hash) if headers.nil?
+
+        serializer.parse_response(hash, headers: headers)
       end
 
       # Deserialize a Response from a Hash.

data/lib/prompt_builder/serializers/base.rb

@@ -15,11 +15,19 @@ module PromptBuilder
         end
 
         # Parse a response from the target format into an PromptBuilder::Response.
+        # Format classes that define a nested Response parser delegate to it.
         #
         # @param hash [Hash] the response hash in the target format
+        # @param headers [Hash, #each, nil] the HTTP response headers, for
+        #   formats that return response metadata in headers rather than in
+        #   the body
         # @return [Response] the parsed response
         # @raise [ErrorResponseError] if the payload is an API error envelope
-        def parse_response(hash)
+        def parse_response(hash, headers: nil)
+          if const_defined?(:Response, false)
+            return const_get(:Response, false).parse_response(hash, headers: headers)
+          end
+
           check_error_response!(hash)
           deserialize_response(hash)
         end

data/lib/prompt_builder/serializers/chat_completion.rb

@@ -16,14 +16,6 @@ module PromptBuilder
         def request_payload(session)
           Request.request_payload(session)
         end
-
-        # Parse a Chat Completions response into an PromptBuilder::Response.
-        #
-        # @param hash [Hash] the response hash in Chat Completions format
-        # @return [PromptBuilder::Response] the parsed response
-        def parse_response(hash)
-          Response.parse_response(hash)
-        end
       end
     end
   end

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

@@ -7,7 +7,24 @@ module PromptBuilder
     class Converse < Base
       # Response parser for the Amazon Bedrock Converse API format.
       class Response < Base
+        # The response id header set by Bedrock (the AWS request metadata id).
+        RESPONSE_ID_HEADER = "x-amzn-requestid"
+
         class << self
+          # Parse a Converse response into a PromptBuilder::Response. The
+          # Converse API does not include a response id in the body; Bedrock
+          # returns it in the request metadata headers, so the id is read
+          # from +headers+ when they are given.
+          #
+          # @param hash [Hash] the response hash in Converse format
+          # @param headers [Hash, #each, nil] the HTTP response headers
+          # @return [PromptBuilder::Response] the parsed response
+          # @raise [ErrorResponseError] if the payload is an API error envelope
+          def parse_response(hash, headers: nil)
+            check_error_response!(hash)
+            deserialize_response(hash, headers)
+          end
+
           private
 
           # Bedrock exception bodies carry a top-level "message" (the exception
@@ -25,7 +42,7 @@ module PromptBuilder
             [error_type, message].compact.join(": ")
           end
 
-          def deserialize_response(hash)
+          def deserialize_response(hash, headers = nil)
             require_response_key!(hash, "output")
             require_response_key!(hash, "stopReason")
 
@@ -50,7 +67,7 @@ module PromptBuilder
             content_blocks = message["content"] || []
 
             PromptBuilder::Response.new(
-              id: nil,
+              id: response_id_from_headers(headers),
               object: nil,
               model: nil,
               output: build_output_items(content_blocks),
@@ -61,6 +78,22 @@ module PromptBuilder
             )
           end
 
+          # Find the response id header with a case-insensitive name match.
+          # Header values may be scalars or arrays of values, depending on
+          # the HTTP client the headers come from.
+          def response_id_from_headers(headers)
+            return nil unless headers.respond_to?(:each)
+
+            headers.each do |name, value|
+              next unless name.to_s.casecmp?(RESPONSE_ID_HEADER)
+
+              value = value.first if value.is_a?(Array)
+              value = value.to_s.strip
+              return value unless value.empty?
+            end
+            nil
+          end
+
           def map_stop_reason(reason)
             case reason
             when "end_turn", "tool_use", "stop_sequence"

data/lib/prompt_builder/serializers/converse.rb

@@ -16,14 +16,6 @@ module PromptBuilder
         def request_payload(session)
           Request.request_payload(session)
         end
-
-        # Parse a Converse response into a PromptBuilder::Response.
-        #
-        # @param hash [Hash] the response hash in Converse format
-        # @return [PromptBuilder::Response] the parsed response
-        def parse_response(hash)
-          Response.parse_response(hash)
-        end
       end
     end
   end

data/lib/prompt_builder/serializers/gemini.rb

@@ -16,14 +16,6 @@ module PromptBuilder
         def request_payload(session)
           Request.request_payload(session)
         end
-
-        # Parse a Gemini response into a PromptBuilder::Response.
-        #
-        # @param hash [Hash] the response hash in Gemini format
-        # @return [PromptBuilder::Response] the parsed response
-        def parse_response(hash)
-          Response.parse_response(hash)
-        end
       end
     end
   end

data/lib/prompt_builder/serializers/messages.rb

@@ -16,14 +16,6 @@ module PromptBuilder
         def request_payload(session)
           Request.request_payload(session)
         end
-
-        # Parse a Messages response into an PromptBuilder::Response.
-        #
-        # @param hash [Hash] the response hash in Messages format
-        # @return [PromptBuilder::Response] the parsed response
-        def parse_response(hash)
-          Response.parse_response(hash)
-        end
       end
     end
   end

data/lib/prompt_builder/serializers/open_responses.rb

@@ -16,14 +16,6 @@ module PromptBuilder
         def request_payload(session)
           Request.request_payload(session)
         end
-
-        # Parse an Open Responses response into an PromptBuilder::Response.
-        #
-        # @param hash [Hash] the response hash in Open Responses format
-        # @return [PromptBuilder::Response] the parsed response
-        def parse_response(hash)
-          Response.parse_response(hash)
-        end
       end
     end
   end

metadata

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