typesafe-sdk-ruby 0.6.0 → 0.7.0

data/lib/typesafe/sdk/questions.rb

@@ -2,63 +2,102 @@
 
 module Typesafe
   module SDK
-    # Builders and validation for the three question types.
+    # Builders and validation for the noul, score, choice, and box question types.
     module Questions
+      MAX_SCORE_LEVELS = 10
+      MAX_CHOICE_OPTIONS = 255
+
       module_function
 
-      # Create a yes/no question with optional descriptions for either outcome.
-      #
-      # @param instructions [String, Hash, Array, nil] the question; defaults to `nil`.
-      # @param criteria [Hash, nil] optional descriptions of the yes and no outcomes.
+      # Create a yes/no question. Supply instructions or at least one outcome description.
+      # @param instructions [String, Hash, Array, Image, TextWithAssets, nil]
+      # @param criteria [Hash, nil] optional true/false outcome descriptions.
       def noul(instructions = nil, criteria: nil)
-        { type: "noul", instructions: instructions, criteria: criteria }
+        question = { type: "noul", instructions: instructions, criteria: criteria }
+        validate_noul!(instructions, criteria, "noul")
+        question
       end
 
-      # Create a score question using an ordered rubric.
-      #
-      # @param instructions [String, Hash, Array, nil] the question.
-      # @param criteria [Array] at least two descriptions indexed by score from zero.
+      # Create a score question with 2–10 ordered descriptions. Nil levels are not supported.
+      # An empty string preserves a position without a description.
       def score(instructions, criteria)
-        unless criteria.is_a?(Array)
-          raise TypeSafeError,
-                "Score criteria must be a list of descriptions indexed by score from zero, " \
-                "not a map."
-        end
-
+        validate_score!(criteria, "score")
         { type: "score", instructions: instructions, criteria: criteria }
       end
 
-      # Create a question that selects between named alternatives.
-      #
-      # @param instructions [String, Hash, Array, nil] the question.
-      # @param criteria [Hash] labels mapped to descriptions, or `nil` for undescribed labels.
+      # Create a choice between 1–255 named options; nil leaves a label undescribed.
       def choice(instructions, criteria)
-        if criteria.is_a?(Array)
-          raise TypeSafeError, "Choice criteria must be a map of labels to descriptions, not a list."
-        end
-
+        validate_choice!(criteria, "choice")
         { type: "choice", instructions: instructions, criteria: criteria }
       end
 
-      # Reject empty question sets and score questions without a list of at least two criteria.
+      # Create a question that locates what its instructions describe in the request's image.
+      # Use the `jev-preview` model for box questions.
+      # @param instructions [String, Hash, Array, Image, TextWithAssets, nil] what to locate.
+      def box(instructions = nil)
+        { type: "box", instructions: instructions }
+      end
+
+      STATE_TYPES = [String, Hash, Array, Image, TextWithAssets].freeze
+
+      def validate_state!(state)
+        return if STATE_TYPES.any? { |type| state.is_a?(type) }
+
+        raise TypeSafeError, "`state` must be a string, object, array, or image; nil is not supported."
+      end
+
+      # Validate builders and raw JSON-style questions without altering the caller's data.
       def validate!(questions)
-        raise TypeSafeError, "At least one question is required." if questions.empty?
+        raise TypeSafeError, "At least one question is required." unless questions.is_a?(Hash) && !questions.empty?
 
         questions.each do |name, question|
-          next unless question.is_a?(Hash) && question[:type] == "score"
+          raise TypeSafeError, "Question key cannot be empty." if name.to_s.empty?
+          raise TypeSafeError, "Question must be an object." unless question.is_a?(Hash)
 
-          criteria = question[:criteria]
-          unless criteria.is_a?(Array)
-            raise TypeSafeError,
-                  "Score question \"#{name}\" has criteria that are not a list; " \
-                  "score criteria must be a list of descriptions indexed by score from zero."
+          wire = question.transform_keys(&:to_s)
+          case wire["type"].to_s
+          when "score" then validate_score!(wire["criteria"], name)
+          when "choice" then validate_choice!(wire["criteria"], name)
+          when "noul" then validate_noul!(wire["instructions"], wire["criteria"], name)
           end
-          next unless criteria.length < 2
+        end
+      end
+
+      def validate_noul!(instructions, criteria, name)
+        unless criteria.nil? || criteria.is_a?(Hash)
+          raise TypeSafeError, "Noul question #{name.inspect} criteria must be an object."
+        end
+
+        descriptions = criteria.is_a?(Hash) ? criteria.transform_keys(&:to_s) : {}
+        return unless instructions.nil? && %w[true false].all? { |key| descriptions[key].nil? }
 
+        raise TypeSafeError, "Noul question #{name.inspect} must have instructions or criteria."
+      end
+
+      def validate_score!(criteria, name)
+        unless criteria.is_a?(Array)
           raise TypeSafeError,
-                "Score question \"#{name}\" has #{criteria.length} criteria; " \
-                "at least two scores are required."
+                "Score question #{name.inspect} has criteria that are not a list; " \
+                "score criteria must be a list of descriptions indexed by score from zero."
         end
+        raise TypeSafeError, "Score question #{name.inspect}: at least two scores are required." if criteria.length < 2
+        if criteria.length > MAX_SCORE_LEVELS
+          raise TypeSafeError, "Score question #{name.inspect}: at most #{MAX_SCORE_LEVELS} levels are allowed."
+        end
+        return unless criteria.any?(&:nil?)
+
+        raise TypeSafeError,
+              "Score question #{name.inspect} contains a nil level; use a description or an empty string " \
+              "to preserve its position."
+      end
+
+      def validate_choice!(criteria, name)
+        unless criteria.is_a?(Hash)
+          raise TypeSafeError, "Choice criteria must be a map of labels to descriptions, not a list."
+        end
+        return if criteria.length.between?(1, MAX_CHOICE_OPTIONS)
+
+        raise TypeSafeError, "Choice question #{name.inspect} requires 1–#{MAX_CHOICE_OPTIONS} options."
       end
     end
   end

data/lib/typesafe/sdk/resources/models.rb

@@ -11,11 +11,12 @@ module Typesafe
 
         # List the models available to the account.
         #
-        # @param options [Hash] per-call `timeout`, `retry`, `headers`, and `signal` settings.
-        # @return [Array<ModelCard>]
+        # @param options [Hash] per-call `timeout`, `retry_policy`, `headers`, and `signal` settings.
+        # @param with_response [Boolean] return model cards with HTTP metadata and request ID.
+        # @return [Array<ModelCard>, WithResponse]
         # @raise [TypeSafeError] the response shape is unexpected.
         # @raise [APIError] the server returns a non-2xx response after retries.
-        def list(**options)
+        def list(with_response: false, **options)
           response = @client.request(:get, "/v1/models", **options)
           wire = response.body
           unless wire.is_a?(Hash) && wire["models"].is_a?(Array)
@@ -23,7 +24,8 @@ module Typesafe
                   "Unexpected response shape from GET /v1/models; expected { models: [...] }."
           end
 
-          wire["models"].map { |card| ModelCard.new(card) }
+          result = wire["models"].map { |card| ModelCard.new(card) }
+          with_response ? WithResponse.new(result, response) : result
         end
       end
     end

data/lib/typesafe/sdk/retry.rb

@@ -38,15 +38,15 @@ module Typesafe
         return nil unless headers.respond_to?(:[])
 
         if (ms = headers["retry-after-ms"])
-          parsed = Integer(ms, exception: false)
-          return parsed if parsed && parsed >= 0
+          parsed = Float(ms, exception: false) unless ms.to_s.strip.empty?
+          return parsed if parsed&.finite? && parsed >= 0
         end
 
         raw = headers["retry-after"]
-        return nil if raw.nil?
+        return nil if raw.nil? || raw.to_s.strip.empty?
 
         seconds = Float(raw, exception: false)
-        return (seconds * 1000).round if seconds && seconds >= 0
+        return seconds >= 0 ? seconds * 1000 : nil if seconds&.finite?
 
         date = begin
           Time.parse(raw)

data/lib/typesafe/sdk/types.rb

@@ -2,7 +2,33 @@
 
 module Typesafe
   module SDK
-    # Token usage for a request.
+    # Parsed data together with HTTP metadata, like the JS SDK withResponse() result.
+    class WithResponse
+      attr_reader :data, :response, :request_id
+
+      def initialize(data, response)
+        @data = data
+        @response = response
+        @request_id = response.request_id
+      end
+    end
+
+    # An answer, keeping every field the API returned, including fields not modeled here.
+    class Answer
+      attr_reader :type
+
+      def initialize(data)
+        @data = data
+        @type = data["type"]
+      end
+
+      # The answer as the API returned it, with string keys.
+      def to_h
+        @data.dup
+      end
+    end
+
+    # Token usage for a request. Each count is `nil` when the API did not report it.
     class Usage
       attr_reader :input_tokens, :output_tokens
 
@@ -13,21 +39,21 @@ module Typesafe
     end
 
     # A yes/no answer.
-    class NoulResponse
-      attr_reader :type, :noul
+    class NoulResponse < Answer
+      attr_reader :noul
 
       def initialize(data)
-        @type = data["type"]
+        super
         @noul = data["noul"]
       end
     end
 
     # A selected label with its probabilities.
-    class ChoiceResponse
-      attr_reader :type, :choice, :confidence, :probabilities
+    class ChoiceResponse < Answer
+      attr_reader :choice, :confidence, :probabilities
 
       def initialize(data)
-        @type = data["type"]
+        super
         @choice = data["choice"]
         @confidence = data["confidence"]
         @probabilities = data["probabilities"]
@@ -35,11 +61,11 @@ module Typesafe
     end
 
     # An expected score with its rubric and probabilities.
-    class ScoreResponse
-      attr_reader :type, :score, :confidence, :legend, :probabilities
+    class ScoreResponse < Answer
+      attr_reader :score, :confidence, :legend, :probabilities
 
       def initialize(data)
-        @type = data["type"]
+        super
         @score = data["score"]
         @confidence = data["confidence"]
         @legend = data["legend"]
@@ -47,12 +73,44 @@ module Typesafe
       end
     end
 
+    # A box's edges as fractions of the image's height (`top`, `bottom`) and width
+    # (`left`, `right`), each from zero to one.
+    class BoxCoordinates
+      attr_reader :top, :bottom, :left, :right
+
+      def initialize(data)
+        @top = data["top"]
+        @bottom = data["bottom"]
+        @left = data["left"]
+        @right = data["right"]
+      end
+
+      def to_h
+        { "top" => top, "bottom" => bottom, "left" => left, "right" => right }
+      end
+    end
+
+    # The answer to a box question.
+    class BoxResponse < Answer
+      # Where the instructions' subject is in the image, or `nil` when absent.
+      attr_reader :box
+      # Confidence in the box, from zero to one, or `nil` when the API didn't report it.
+      attr_reader :confidence
+
+      def initialize(data)
+        super
+        @box = data["box"].is_a?(Hash) ? BoxCoordinates.new(data["box"]) : nil
+        @confidence = data["confidence"]
+      end
+    end
+
     # Builds the answer object matching the question type.
     module ResponseFactory
       CLASSES = {
         "noul" => NoulResponse,
         "choice" => ChoiceResponse,
-        "score" => ScoreResponse
+        "score" => ScoreResponse,
+        "box" => BoxResponse
       }.freeze
 
       module_function

data/lib/typesafe/sdk/version.rb

@@ -2,7 +2,8 @@
 
 module Typesafe
   module SDK
-    # Keep in sync with the gemspec version. Checked by the version consistency spec.
-    VERSION = "0.6.0"
+    # Ruby-only fixes use a fourth numeric component; the first three track upstream.
+    VERSION = "0.7.0"
+    UPSTREAM_VERSION = "0.7.0"
   end
 end

data/lib/typesafe-sdk-ruby.rb

@@ -5,6 +5,8 @@ require_relative "typesafe/sdk/env"
 require_relative "typesafe/sdk/logging"
 require_relative "typesafe/sdk/retry"
 require_relative "typesafe/sdk/errors"
+require_relative "typesafe/sdk/assets"
+require_relative "typesafe/sdk/compression"
 require_relative "typesafe/sdk/questions"
 require_relative "typesafe/sdk/http"
 require_relative "typesafe/sdk/types"
@@ -36,5 +38,33 @@ module Typesafe
     def choice(instructions, criteria)
       Questions.choice(instructions, criteria)
     end
+
+    # Create a box question. @see Questions.box
+    def box(instructions = nil)
+      Questions.box(instructions)
+    end
+
+    # Create a PNG or JPEG image asset from file bytes, a Pathname, or an IO.
+    # Use {Image.from_base64} for base64 text. @see Image#initialize
+    def image(data)
+      Image.new(data)
+    end
+
+    # Join text and images into text that carries its images, like JavaScript's `withAssets`
+    # tagged template. Other values are converted with `to_s`, as string interpolation does.
+    #
+    # @example
+    #   Typesafe::SDK.with_assets("Does ", photo, " show the product in ", listing, "?")
+    # @return [TextWithAssets]
+    def with_assets(*parts)
+      TextWithAssets.build(*parts)
+    end
+
+    # Join `values` with `separator` (default `","`, as in JavaScript's `withAssets.join`) into
+    # text that carries the images among them.
+    # @return [TextWithAssets]
+    def join_assets(values, separator = ",")
+      TextWithAssets.join(values, separator)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typesafe-sdk-ruby
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - TypeSafe Ruby SDK Contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-20 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -17,6 +17,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -24,12 +27,15 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 description: |-
   Unofficial Ruby SDK for the TypeSafe AI API (Jev model). Ask named questions about
-  text or structured state and get typed answers: yes/no (noul), choice, and score
-  questions, with retries, timeouts, structured logging, and typed errors.
+  text, structured state, or images and get typed answers: yes/no (noul), choice, score,
+  and box questions, with retries, timeouts, request compression, structured logging, and
+  typed errors.
 email:
-- opensource@typesafe.ai
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -37,8 +43,13 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- docs/COMPATIBILITY.md
+- docs/RELEASING.md
+- docs/UPSTREAM_ISSUES.md
 - lib/typesafe-sdk-ruby.rb
+- lib/typesafe/sdk/assets.rb
 - lib/typesafe/sdk/client.rb
+- lib/typesafe/sdk/compression.rb
 - lib/typesafe/sdk/env.rb
 - lib/typesafe/sdk/errors.rb
 - lib/typesafe/sdk/http.rb
@@ -54,8 +65,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/afurm/typesafe-sdk-ruby/issues
   changelog_uri: https://github.com/afurm/typesafe-sdk-ruby/blob/main/CHANGELOG.md
-  documentation_uri: https://docs.typesafe.ai/
-  homepage_uri: https://github.com/afurm/typesafe-sdk-ruby
+  documentation_uri: https://github.com/afurm/typesafe-sdk-ruby#readme
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/afurm/typesafe-sdk-ruby
 post_install_message: