typesafe-sdk-ruby 0.6.0

data/lib/typesafe/sdk/errors.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    # Base class for SDK errors.
+    class TypeSafeError < StandardError
+      def initialize(message = nil, cause: nil)
+        super(message)
+        @cause = cause
+      end
+
+      attr_reader :cause
+    end
+
+    # An unsuccessful HTTP response from the API.
+    class APIError < TypeSafeError
+      MAX_RAW_BODY_IN_MESSAGE = 200
+
+      # HTTP response status code.
+      attr_reader :status
+      # HTTP response headers (a case-insensitive hash).
+      attr_reader :headers
+      # Parsed JSON, response text, or `nil` for an empty body.
+      attr_reader :body
+      # Request ID from `x-typesafe-request-id`, or `nil` when absent.
+      attr_reader :request_id
+
+      def initialize(status, body, headers, message = nil)
+        super(message || APIError.describe(status, body))
+        @status = status
+        @body = body
+        @headers = headers
+        @request_id = headers[Typesafe::SDK::REQUEST_ID_HEADER]
+      end
+
+      def self.describe(status, body)
+        detail = extract_message(body)
+        return "#{status} #{detail}" if detail
+        return "#{status} status code (no body)" if body.nil?
+
+        raw = body.is_a?(String) ? body : JSON.generate(body)
+        raw = "#{raw[0, MAX_RAW_BODY_IN_MESSAGE]}…" if raw.length > MAX_RAW_BODY_IN_MESSAGE
+        "#{status} #{raw}"
+      end
+
+      # Create the error subclass for an HTTP status code.
+      def self.from_response(status, body, headers)
+        klass = status_classes[status]
+        klass ||= InternalServerError if status >= 500
+        return klass.new(status, body, headers) if klass
+
+        new(status, body, headers)
+      end
+
+      def self.status_classes
+        @status_classes ||= {
+          400 => Typesafe::SDK::BadRequestError,
+          401 => Typesafe::SDK::AuthenticationError,
+          403 => Typesafe::SDK::PermissionDeniedError,
+          404 => Typesafe::SDK::NotFoundError,
+          422 => Typesafe::SDK::UnprocessableEntityError,
+          429 => Typesafe::SDK::RateLimitError
+        }.freeze
+      end
+
+      def self.extract_message(body)
+        return body if body.is_a?(String) && !body.empty?
+        return nil unless body.is_a?(Hash)
+
+        error = body["error"]
+        return error if error.is_a?(String)
+        return error["message"] if error.is_a?(Hash) && error["message"].is_a?(String)
+        return body["message"] if body["message"].is_a?(String)
+        return body["detail"] if body["detail"].is_a?(String)
+        return body["detail"]["message"] if body["detail"].is_a?(Hash) && body["detail"]["message"].is_a?(String)
+        return describe_validation_errors(body["detail"]) if body["detail"].is_a?(Array)
+
+        nil
+      end
+
+      # Format validation errors as semicolon-separated `path: message` entries.
+      def self.describe_validation_errors(errors)
+        parts = errors.filter_map do |e|
+          next nil unless e.is_a?(Hash) && e["msg"].is_a?(String)
+
+          loc = e["loc"].is_a?(Array) ? e["loc"].reject { |x| x == "body" }.join(".") : ""
+          loc.empty? ? e["msg"] : "#{loc}: #{e['msg']}"
+        end
+        parts.empty? ? nil : parts.join("; ")
+      end
+    end
+
+    # HTTP 400: the request is invalid.
+    class BadRequestError < APIError; end
+    # HTTP 401: authentication failed.
+    class AuthenticationError < APIError; end
+    # HTTP 403: access is denied.
+    class PermissionDeniedError < APIError; end
+    # HTTP 404: the resource was not found.
+    class NotFoundError < APIError; end
+    # HTTP 422: request validation failed.
+    class UnprocessableEntityError < APIError; end
+
+    # HTTP 429: the rate limit was exceeded.
+    class RateLimitError < APIError
+      # Server retry delay in milliseconds, or `nil` when absent or invalid.
+      def retry_after_ms
+        Typesafe::SDK::Retry.parse_retry_after(@headers)
+      end
+    end
+
+    # HTTP 5xx: the server failed to handle the request.
+    class InternalServerError < APIError; end
+
+    # The request or response-body delivery failed (DNS, TLS, connection closed, etc.).
+    class APIConnectionError < TypeSafeError
+      def initialize(message = "Connection error.", cause: nil)
+        super
+      end
+    end
+
+    # The full response did not arrive within the timeout. A kind of `APIConnectionError`.
+    class APITimeoutError < APIConnectionError
+      # Configured timeout in milliseconds.
+      attr_reader :timeout_ms
+
+      def initialize(timeout_ms, cause: nil)
+        super("Request timed out after #{timeout_ms}ms.", cause: cause)
+        @timeout_ms = timeout_ms
+      end
+    end
+
+    # The caller cancelled the request.
+    class APIUserAbortError < TypeSafeError
+      def initialize(message = "Request was aborted.", cause: nil)
+        super
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/http.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module Typesafe
+  module SDK
+    # A cancellation handle for requests. Thread-safe; call {#cancel} from another thread.
+    class Signal
+      def initialize
+        @mutex = Mutex.new
+        @canceled = false
+      end
+
+      def canceled?
+        @mutex.synchronize { @canceled }
+      end
+
+      def cancel
+        @mutex.synchronize { @canceled = true }
+      end
+
+      # Raise {APIUserAbortError} if canceled.
+      def check!
+        raise APIUserAbortError if canceled?
+      end
+
+      # Wait up to `seconds`, returning early when canceled.
+      def wait(seconds)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+        while !canceled? && (remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)).positive?
+          sleep([remaining, 0.05].min)
+        end
+      end
+    end
+
+    # A parsed HTTP response.
+    class Response
+      attr_reader :status, :headers, :body, :request_id
+
+      def initialize(status:, headers:, body:, request_id:)
+        @status = status
+        @headers = headers
+        @body = body
+        @request_id = request_id
+      end
+
+      def ok?
+        status.between?(200, 299)
+      end
+    end
+
+    # The default HTTP adapter built on `Net::HTTP`.
+    #
+    # Replace it by passing `http:` to {Client} with any object responding to `request`
+    # that returns a {Response} and raises {APIConnectionError}, {APITimeoutError}, or
+    # {APIUserAbortError} on failure.
+    class HTTP
+      # Perform one HTTP round trip.
+      #
+      # @param method [Symbol] `:get` or `:post`.
+      # @param url [String] absolute URL.
+      # @param headers [Hash{String => String}] request headers.
+      # @param body [String, nil] JSON-encoded request body.
+      # @param timeout [Numeric] timeout in seconds.
+      # @param signal [Signal, nil] cancellation handle.
+      # @return [Response]
+      def request(method:, url:, headers:, body:, timeout:, signal:)
+        uri = URI(url)
+        check_signal!(signal)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+
+        request_class = { get: Net::HTTP::Get, post: Net::HTTP::Post }.fetch(method)
+        req = request_class.new(uri.request_uri)
+        headers.each { |name, value| req[name] = value }
+        req.body = body if body
+
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raw = http.request(req)
+        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+        body_text = raw.body.to_s
+        parsed = parse_body(body_text, raw["content-type"])
+        Response.new(
+          status: raw.code.to_i,
+          headers: Headers.new(raw.each_header.to_h),
+          body: parsed,
+          request_id: raw["x-typesafe-request-id"]
+        )
+      rescue APIUserAbortError
+        raise
+      rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
+        raise APITimeoutError.new((timeout * 1000).round, cause: e)
+      rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ETIMEDOUT,
+             SocketError, OpenSSL::SSL::SSLError, EOFError, IOError => e
+        raise APIConnectionError.new("Connection error: #{e.message}", cause: e)
+      end
+
+      private
+
+      def check_signal!(signal)
+        signal&.check!
+      end
+
+      def parse_body(text, content_type)
+        return nil if text.empty?
+
+        if content_type.to_s.include?("application/json")
+          begin
+            return JSON.parse(text)
+          rescue JSON::ParserError
+            return text
+          end
+        end
+        # Be lenient: servers and proxies don't always set content-type.
+        begin
+          JSON.parse(text)
+        rescue JSON::ParserError
+          text
+        end
+      end
+    end
+
+    # Case-insensitive header lookup, matching the JS SDK's `Headers` semantics.
+    class Headers
+      def initialize(hash)
+        @hash = hash.to_h { |k, v| [k.to_s.downcase, v] }
+      end
+
+      def [](name)
+        @hash[name.to_s.downcase]
+      end
+
+      def key?(name)
+        @hash.key?(name.to_s.downcase)
+      end
+
+      def to_h
+        @hash.dup
+      end
+
+      def each(&)
+        @hash.each(&)
+      end
+
+      def ==(other)
+        @hash == (other.is_a?(Headers) ? other.to_h : other)
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/logging.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    # Log verbosity; `off` disables logging.
+    module LogLevel
+      DEBUG = :debug
+      INFO = :info
+      WARN = :warn
+      ERROR = :error
+      OFF = :off
+
+      LEVELS = [DEBUG, INFO, WARN, ERROR, OFF].freeze
+      DEFAULT = WARN
+
+      RANK = { DEBUG => 0, INFO => 1, WARN => 2, ERROR => 3, OFF => 4 }.freeze
+
+      module_function
+
+      # Validate a configured log level, raising {Typesafe::SDK::TypeSafeError} for unknown values.
+      def parse!(value, source)
+        return value if LEVELS.include?(value)
+        return value.to_sym if value.is_a?(String) && LEVELS.include?(value.to_sym)
+
+        raise Typesafe::SDK::TypeSafeError,
+              "Invalid log level #{value.inspect} from #{source}. " \
+              "Expected one of: #{LEVELS.join(', ')}."
+      end
+    end
+
+    # Default logger writing to `$stderr` with the `[typesafe-ai]` prefix.
+    class ConsoleLogger
+      PREFIX = "[typesafe-ai]"
+
+      def initialize(io: $stderr)
+        @io = io
+      end
+
+      %i[debug info warn error].each do |severity|
+        define_method(severity) do |message, **data|
+          @io.puts("#{PREFIX} #{severity.upcase}: #{message}#{format_data(data)}")
+        end
+      end
+
+      private
+
+      def format_data(data)
+        return "" if data.empty?
+
+        " #{data.map { |k, v| "#{k}=#{v.inspect}" }.join(' ')}"
+      end
+    end
+
+    # Filter logger calls to the configured level and above.
+    class LevelLogger
+      attr_reader :sink
+
+      def initialize(sink, level)
+        @sink = sink
+        @rank = LogLevel::RANK.fetch(level)
+      end
+
+      %i[debug info warn error].each do |severity|
+        define_method(severity) do |message, **data|
+          return if LogLevel::RANK.fetch(severity) < @rank
+
+          @sink.public_send(severity, message, **data)
+        end
+      end
+    end
+
+    # Credential headers that retain a key suffix for identification.
+    module Redaction
+      KEY_HEADERS = %w[authorization proxy-authorization x-api-key].freeze
+      OPAQUE_HEADERS = %w[cookie set-cookie].freeze
+
+      module_function
+
+      # Mask a key, preserving its scheme and the last four characters of secrets longer than eight.
+      def redact_key(value)
+        scheme, secret = value.include?(" ") ? value.split(/\s+/, 2) : [nil, value]
+        tail = secret && secret.length > 8 ? secret[-4..] : ""
+        "#{"#{scheme} " if scheme}***#{tail}"
+      end
+
+      def redact(name, value)
+        lower = name.downcase
+        return redact_key(value) if KEY_HEADERS.include?(lower)
+        return "***" if OPAQUE_HEADERS.include?(lower)
+
+        value
+      end
+
+      # Copy headers with known credential values redacted.
+      def redact_headers(headers)
+        headers.to_h { |name, value| [name, redact(name, value)] }
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/questions.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    # Builders and validation for the three question types.
+    module Questions
+      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.
+      def noul(instructions = nil, criteria: nil)
+        { type: "noul", instructions: instructions, criteria: criteria }
+      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.
+      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
+
+        { 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.
+      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
+
+        { type: "choice", instructions: instructions, criteria: criteria }
+      end
+
+      # Reject empty question sets and score questions without a list of at least two criteria.
+      def validate!(questions)
+        raise TypeSafeError, "At least one question is required." if questions.empty?
+
+        questions.each do |name, question|
+          next unless question.is_a?(Hash) && question[:type] == "score"
+
+          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."
+          end
+          next unless criteria.length < 2
+
+          raise TypeSafeError,
+                "Score question \"#{name}\" has #{criteria.length} criteria; " \
+                "at least two scores are required."
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    module Resources
+      # Access to the Models API resource.
+      class Models
+        def initialize(client)
+          @client = client
+        end
+
+        # List the models available to the account.
+        #
+        # @param options [Hash] per-call `timeout`, `retry`, `headers`, and `signal` settings.
+        # @return [Array<ModelCard>]
+        # @raise [TypeSafeError] the response shape is unexpected.
+        # @raise [APIError] the server returns a non-2xx response after retries.
+        def list(**options)
+          response = @client.request(:get, "/v1/models", **options)
+          wire = response.body
+          unless wire.is_a?(Hash) && wire["models"].is_a?(Array)
+            raise TypeSafeError,
+                  "Unexpected response shape from GET /v1/models; expected { models: [...] }."
+          end
+
+          wire["models"].map { |card| ModelCard.new(card) }
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/retry.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    # Request ID header returned by the API.
+    REQUEST_ID_HEADER = "x-typesafe-request-id"
+
+    # Retry defaults, delay calculation, and cancellable waits.
+    module Retry
+      # Default per-attempt timeout in seconds.
+      DEFAULT_TIMEOUT_S = 10
+
+      # Default SDK retry policy.
+      DEFAULT_RETRY_POLICY = {
+        max_retries: 2,
+        backoff_initial_ms: 500,
+        backoff_max_ms: 5_000,
+        backoff_jitter: 0.25,
+        # HTTP 408, 429, and 5xx responses.
+        http_statuses: [408, 429, *(500..599)].freeze,
+        respect_retry_after: true,
+        # Maximum server retry delay before falling back to backoff.
+        max_retry_after_ms: 60_000,
+        api_connection_error: true,
+        api_timeout_error: true
+      }.freeze
+
+      module_function
+
+      # Whether the policy retries an HTTP status code.
+      def retryable_status?(status, policy = DEFAULT_RETRY_POLICY)
+        policy[:http_statuses].include?(status)
+      end
+
+      # Parse `retry-after-ms` or `Retry-After` into milliseconds, preferring `retry-after-ms`.
+      # Returns `nil` when neither header contains a valid delay.
+      def parse_retry_after(headers, now: Time.now)
+        return nil unless headers.respond_to?(:[])
+
+        if (ms = headers["retry-after-ms"])
+          parsed = Integer(ms, exception: false)
+          return parsed if parsed && parsed >= 0
+        end
+
+        raw = headers["retry-after"]
+        return nil if raw.nil?
+
+        seconds = Float(raw, exception: false)
+        return (seconds * 1000).round if seconds && seconds >= 0
+
+        date = begin
+          Time.parse(raw)
+        rescue StandardError
+          nil
+        end
+        return nil if date.nil?
+
+        [(date - now) * 1000, 0].max.round
+      end
+
+      # Calculate the delay in milliseconds for a zero-based retry attempt.
+      # Uses an allowed server delay; otherwise capped exponential backoff with jitter.
+      def retry_delay_ms(attempt, headers = nil, policy = DEFAULT_RETRY_POLICY, random: Random)
+        if policy[:respect_retry_after] && headers
+          retry_after = parse_retry_after(headers)
+          return retry_after if retry_after && retry_after <= policy[:max_retry_after_ms]
+        end
+
+        exponential = [policy[:backoff_initial_ms] * (2**attempt), policy[:backoff_max_ms]].min
+        jitter = 1.0 - (random.rand * policy[:backoff_jitter])
+        (exponential * jitter).round
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/types.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    # Token usage for a request.
+    class Usage
+      attr_reader :input_tokens, :output_tokens
+
+      def initialize(data)
+        @input_tokens = data["input_tokens"]
+        @output_tokens = data["output_tokens"]
+      end
+    end
+
+    # A yes/no answer.
+    class NoulResponse
+      attr_reader :type, :noul
+
+      def initialize(data)
+        @type = data["type"]
+        @noul = data["noul"]
+      end
+    end
+
+    # A selected label with its probabilities.
+    class ChoiceResponse
+      attr_reader :type, :choice, :confidence, :probabilities
+
+      def initialize(data)
+        @type = data["type"]
+        @choice = data["choice"]
+        @confidence = data["confidence"]
+        @probabilities = data["probabilities"]
+      end
+    end
+
+    # An expected score with its rubric and probabilities.
+    class ScoreResponse
+      attr_reader :type, :score, :confidence, :legend, :probabilities
+
+      def initialize(data)
+        @type = data["type"]
+        @score = data["score"]
+        @confidence = data["confidence"]
+        @legend = data["legend"]
+        @probabilities = data["probabilities"]
+      end
+    end
+
+    # Builds the answer object matching the question type.
+    module ResponseFactory
+      CLASSES = {
+        "noul" => NoulResponse,
+        "choice" => ChoiceResponse,
+        "score" => ScoreResponse
+      }.freeze
+
+      module_function
+
+      def build(data)
+        klass = CLASSES[data["type"]]
+        raise TypeSafeError, "Unknown answer type #{data['type'].inspect}." unless klass
+
+        klass.new(data)
+      end
+    end
+
+    # Answers keyed by question name, with model and usage metadata.
+    class SystemOneResult
+      attr_reader :model, :answers, :usage
+
+      def initialize(data)
+        @model = data["model"]
+        @answers = (data["answers"] || {}).transform_values { |a| ResponseFactory.build(a) }
+        @usage = Usage.new(data["usage"] || {})
+      end
+
+      # Access an answer by question name (symbol or string).
+      def [](name)
+        @answers[name.to_s]
+      end
+    end
+
+    # Metadata for an available model.
+    class ModelCard
+      attr_reader :name, :description, :release_date
+
+      def initialize(data)
+        @name = data["name"]
+        @description = data["description"]
+        @release_date = data["release_date"]
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    # Keep in sync with the gemspec version. Checked by the version consistency spec.
+    VERSION = "0.6.0"
+  end
+end