typesafe-ai-ruby 0.1.0

data/lib/typesafe/http/net_http_transport.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module HTTP
+    # Default transport built on Net::HTTP with keep-alive connections managed per thread.
+    #
+    # Any object responding to call(request) and returning a Response can replace it,
+    # which is how tests stub the network and how alternative HTTP stacks can be plugged in.
+    class NetHTTPTransport
+      TIMEOUT_ERRORS = [Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Timeout::Error].freeze
+      CONNECTION_ERRORS = [
+        SocketError, SystemCallError, IOError, EOFError, OpenSSL::SSL::SSLError,
+        Net::HTTPBadResponse, Net::ProtocolError
+      ].freeze
+
+      def initialize
+        @managers = {}
+        @mutex = Mutex.new
+      end
+
+      def call(request)
+        manager = connection_manager
+        http = manager.connection_for(request.uri, timeout: request.timeout)
+        wrap_response(http.request(build_request(request)), request)
+      rescue *TIMEOUT_ERRORS => e
+        manager&.discard(request.uri)
+        raise timeout_error(request, e)
+      rescue *CONNECTION_ERRORS => e
+        manager&.discard(request.uri)
+        raise connection_error(request, e)
+      end
+
+      # Close every connection held for any thread.
+      def close
+        @mutex.synchronize do
+          @managers.each_value(&:clear)
+          @managers.clear
+        end
+      end
+
+      # The manager for the calling thread, creating it on first use and releasing
+      # managers whose threads have finished.
+      def connection_manager
+        @mutex.synchronize do
+          @managers.delete_if { |thread, manager| !thread.alive? && (manager.clear || true) }
+          @managers[Thread.current] ||= ConnectionManager.new
+        end
+      end
+
+      private
+
+      def timeout_error(request, error)
+        APITimeoutError.new("#{request.endpoint} timed out after #{request.timeout}s (#{error.class})",
+                            timeout: request.timeout)
+      end
+
+      def connection_error(request, error)
+        APIConnectionError.new("#{request.endpoint} failed: #{error.class}: #{error.message}")
+      end
+
+      def wrap_response(raw, request)
+        Response.new(status: raw.code.to_i, headers: raw.each_header.to_h, body: raw.body, request: request)
+      end
+
+      def build_request(request)
+        klass = request.method == :get ? Net::HTTP::Get : Net::HTTP::Post
+        raw = klass.new(request.uri.request_uri)
+        request.headers.each { |name, value| raw[name] = value }
+        raw.body = request.body if request.body
+        raw
+      end
+    end
+  end
+end

data/lib/typesafe/http/request.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module HTTP
+    # An outgoing HTTP request: method, absolute URI, headers, encoded body and per-attempt timeout.
+    class Request
+      attr_reader :method, :uri, :headers, :body, :timeout
+
+      def initialize(method:, uri:, headers:, body:, timeout:)
+        @method = method
+        @uri = uri
+        @headers = headers.freeze
+        @body = body
+        @timeout = timeout
+        freeze
+      end
+
+      # Method and URL without credentials, query, or fragment.
+      def endpoint
+        port = uri.port == uri.default_port ? "" : ":#{uri.port}"
+        "#{method.to_s.upcase} #{uri.scheme}://#{uri.host}#{port}#{uri.path}"
+      end
+
+      # A copy with additional headers merged in.
+      def with_headers(extra)
+        self.class.new(method: method, uri: uri, headers: headers.merge(extra), body: body, timeout: timeout)
+      end
+    end
+  end
+end

data/lib/typesafe/http/requestor.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module HTTP
+    # Builds requests from a Configuration, sends them through a transport with retries,
+    # logs them, and turns non-2xx responses into APIErrors.
+    class Requestor
+      PROTECTED_HEADERS = [
+        Constants::Headers::AUTHORIZATION, Constants::Headers::ACCEPT, Constants::Headers::USER_AGENT,
+        Constants::Headers::SDK, Constants::Headers::RUNTIME, Constants::Headers::RETRY_COUNT
+      ].map(&:downcase).freeze
+
+      attr_reader :config, :transport
+
+      # sleeper and clock exist so tests can drive the retry loop without waiting.
+      def initialize(config, transport: nil, sleeper: nil, clock: nil)
+        @config = config
+        @transport = transport || config.transport || NetHTTPTransport.new
+        @sleeper = sleeper
+        @clock = clock
+      end
+
+      # Send a POST and return the successful response.
+      def post(path, body:, options: RequestOptions.new)
+        execute(build_request(:post, path, body: body, options: options), options)
+      end
+
+      # Send a GET and return the successful response.
+      def get(path, options: RequestOptions.new)
+        execute(build_request(:get, path, options: options), options)
+      end
+
+      def close
+        transport.close if transport.respond_to?(:close)
+      end
+
+      private
+
+      def execute(request, options)
+        call = CallState.new(request)
+        Instrumentation.notify(:request_begin, call.begin_event)
+        response = retrier_for(options, call).run do |attempt|
+          send_once(attempt.zero? ? request : request.with_headers(Constants::Headers::RETRY_COUNT => attempt.to_s))
+        end
+        Instrumentation.notify(:request_end, call.end_event(response: response))
+        response
+      rescue APIError, APIConnectionError => e
+        Instrumentation.notify(:request_end, call.end_event(error: e))
+        raise
+      end
+
+      def retrier_for(options, call)
+        on_retry = lambda do |error, attempt, delay|
+          call.retried!
+          log_retry(error, attempt, delay)
+        end
+        Retrier.new(retry_policy_for(options), sleeper: @sleeper, clock: @clock, on_retry: on_retry)
+      end
+
+      # Bookkeeping for one client call across its attempts, feeding the instrumentation events.
+      class CallState
+        attr_reader :begin_event
+
+        def initialize(request)
+          @request = request
+          @started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @num_retries = 0
+          @begin_event = Instrumentation::RequestBeginEvent.new(method: request.method, path: request.uri.path)
+        end
+
+        def retried!
+          @num_retries += 1
+        end
+
+        def end_event(response: nil, error: nil)
+          status = response&.status || (error.status if error.is_a?(APIError))
+          request_id = response&.request_id || (error.request_id if error.is_a?(APIError))
+          Instrumentation::RequestEndEvent.new(
+            method: @request.method, path: @request.uri.path, http_status: status,
+            duration: Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started,
+            num_retries: @num_retries, request_id: request_id, error: error, user_data: @begin_event.user_data
+          )
+        end
+      end
+
+      def send_once(request)
+        log_request(request)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        response = transport.call(request)
+        log_response(request, response, started)
+        raise APIError.from_response(response) unless response.success?
+
+        response
+      end
+
+      def retry_policy_for(options)
+        RetryPolicy.from(options.retry_policy, base: config.retry_policy)
+      end
+
+      def build_request(method, path, body: nil, options: RequestOptions.new)
+        encoded = body.nil? ? nil : JSON.generate(body)
+        Request.new(
+          method: method,
+          uri: URI.parse("#{config.base_url}#{path}"),
+          headers: build_headers(options.headers, body: encoded),
+          body: encoded,
+          timeout: options.timeout || config.timeout
+        )
+      end
+
+      def build_headers(extra, body:)
+        headers = strip_protected(config.headers).merge(strip_protected(extra))
+        headers[Constants::Headers::AUTHORIZATION] = "Bearer #{config.api_key}"
+        headers[Constants::Headers::ACCEPT] = Constants::JSON_CONTENT_TYPE
+        headers[Constants::Headers::USER_AGENT] = sdk_identifier
+        headers[Constants::Headers::SDK] = sdk_identifier
+        headers[Constants::Headers::RUNTIME] = Util.runtime
+        headers[Constants::Headers::CONTENT_TYPE] = Constants::JSON_CONTENT_TYPE if body
+        headers
+      end
+
+      def strip_protected(headers)
+        headers.reject { |name, _| PROTECTED_HEADERS.include?(name.downcase) }
+      end
+
+      def sdk_identifier
+        "#{Constants::SDK_NAME}/#{VERSION}"
+      end
+
+      def log_request(request)
+        Logging.debug(config) do
+          "-> #{request.endpoint} headers={#{Logging.format_headers(request.headers)}} body=#{request.body.inspect}"
+        end
+      end
+
+      def log_response(request, response, started)
+        elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+        Logging.info(config) do
+          "#{request.endpoint} -> #{response.status} (#{elapsed}ms) request_id=#{response.request_id || "-"}"
+        end
+        Logging.debug(config) do
+          "<- #{response.status} headers={#{Logging.format_headers(response.headers)}} body=#{response.body.inspect}"
+        end
+      end
+
+      def log_retry(error, attempt, delay)
+        Logging.info(config) do
+          "retry #{attempt + 1} in #{delay.round(3)}s after #{error.class.name.split("::").last}: #{error.message}"
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/http/response.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module HTTP
+    # A raw HTTP response: status, lower-cased headers, body text, and the request that produced it.
+    class Response
+      attr_reader :status, :headers, :body, :request
+
+      def initialize(status:, headers:, body:, request: nil)
+        @status = status
+        @headers = Util.normalize_headers(headers).freeze
+        @body = body.to_s
+        @request = request
+        @json = nil
+        @json_parsed = false
+      end
+
+      # Case-insensitive header lookup.
+      def [](name)
+        headers[name.to_s.downcase]
+      end
+
+      # The x-typesafe-request-id header.
+      def request_id
+        self[Constants::Headers::REQUEST_ID]
+      end
+
+      def success?
+        (200..299).cover?(status)
+      end
+
+      # The parsed JSON body, or nil when the body is not valid JSON.
+      def json
+        return @json if @json_parsed
+
+        @json_parsed = true
+        @json = body.empty? ? nil : JSON.parse(body)
+      rescue JSON::ParserError
+        @json = nil
+      end
+
+      # Server-requested wait in seconds, from retry-after-ms or Retry-After.
+      def retry_after
+        Util.parse_retry_after(headers)
+      end
+    end
+  end
+end

data/lib/typesafe/http/retrier.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module HTTP
+    # Runs a block until it succeeds or the RetryPolicy gives up. The block receives the
+    # attempt number (0 for the first try) and raises APIError or APIConnectionError on failure.
+    # The last error is re-raised when no more retries are allowed or the total budget
+    # would be exceeded by the next delay.
+    class Retrier
+      MONOTONIC = Process::CLOCK_MONOTONIC
+
+      attr_reader :policy
+
+      def initialize(policy, sleeper: nil, clock: nil, random: Kernel, on_retry: nil)
+        @policy = policy
+        @sleeper = sleeper || Kernel.method(:sleep)
+        @clock = clock || -> { Process.clock_gettime(MONOTONIC) }
+        @random = random
+        @on_retry = on_retry
+      end
+
+      def run
+        started = @clock.call
+        attempt = 0
+        loop do
+          return yield(attempt)
+        rescue APIError, APIConnectionError => e
+          delay = retry_delay(e, attempt, started)
+          raise if delay.nil?
+
+          @on_retry&.call(e, attempt, delay)
+          @sleeper.call(delay)
+          attempt += 1
+        end
+      end
+
+      private
+
+      def retry_delay(error, attempt, started)
+        return nil unless attempt < policy.max_retries && retryable?(error)
+
+        delay = policy.delay_for(attempt, headers: error.respond_to?(:headers) ? error.headers : nil, random: @random)
+        return nil if policy.timeout && (@clock.call - started + delay) >= policy.timeout
+
+        delay
+      end
+
+      def retryable?(error)
+        case error
+        when APIError then policy.retry_status?(error.status)
+        when APIConnectionError then policy.retry_error?(error)
+        else false
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/instrumentation.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  # Hooks for observing requests, in the spirit of stripe-ruby's Instrumentation.
+  #
+  #   TypeSafe::Instrumentation.subscribe(:request_end) do |event|
+  #     StatsD.timing("typesafe.request", event.duration, tags: ["status:#{event.http_status}"])
+  #   end
+  #
+  # :request_begin fires once per client call with a RequestBeginEvent; :request_end fires
+  # once per call after any retries with a RequestEndEvent, whether the call succeeded or
+  # raised. Anything stored in the begin event's user_data is available on the end event.
+  module Instrumentation
+    TOPICS = %i[request_begin request_end].freeze
+
+    class RequestBeginEvent
+      attr_reader :method, :path, :user_data
+
+      def initialize(method:, path:)
+        @method = method
+        @path = path
+        @user_data = {}
+      end
+    end
+
+    class RequestEndEvent
+      # HTTP method as a Symbol and the request path.
+      attr_reader :method, :path
+      # Final status code, or nil when no response was received.
+      attr_reader :http_status
+      # Wall time in seconds for the whole call including retries.
+      attr_reader :duration
+      # Retries performed after the first attempt.
+      attr_reader :num_retries
+      # The x-typesafe-request-id of the final response, when present.
+      attr_reader :request_id
+      # The error raised to the caller, or nil on success.
+      attr_reader :error
+      # The Hash from the matching RequestBeginEvent.
+      attr_reader :user_data
+
+      def initialize(method:, path:, http_status:, duration:, num_retries:, request_id:, error:, user_data:)
+        @method = method
+        @path = path
+        @http_status = http_status
+        @duration = duration
+        @num_retries = num_retries
+        @request_id = request_id
+        @error = error
+        @user_data = user_data
+        freeze
+      end
+    end
+
+    @subscribers = TOPICS.to_h { |topic| [topic, {}] }
+    @mutex = Mutex.new
+
+    class << self
+      # Register a block for a topic. Returns the subscription name, which can be
+      # passed to unsubscribe. Subscribing again with the same name replaces the block.
+      def subscribe(topic, name = Object.new, &block)
+        raise ArgumentError, "unknown topic #{topic.inspect}; expected one of #{TOPICS.join(", ")}" unless
+          TOPICS.include?(topic)
+        raise ArgumentError, "a block is required" unless block
+
+        @mutex.synchronize { @subscribers[topic][name] = block }
+        name
+      end
+
+      def unsubscribe(topic, name)
+        @mutex.synchronize { @subscribers.fetch(topic).delete(name) }
+      end
+
+      def notify(topic, event)
+        @mutex.synchronize { @subscribers.fetch(topic).values }.each { |block| block.call(event) }
+      end
+
+      # Remove every subscriber. Mostly useful in tests.
+      def reset!
+        @mutex.synchronize { @subscribers.each_value(&:clear) }
+      end
+    end
+  end
+end

data/lib/typesafe/logging.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  # Logging helpers. The client logs request summaries at info and full headers and bodies
+  # at debug. Credential headers are redacted; bodies are not, so keep debug logging out of
+  # production if state contains sensitive data.
+  module Logging
+    PROGNAME = "typesafe"
+    REDACTED = "[REDACTED]"
+    REDACTED_HEADERS = %w[authorization proxy-authorization x-api-key].freeze
+
+    module_function
+
+    def log?(config, severity)
+      !config.logger.nil? && config.logger_severity <= severity
+    end
+
+    def info(config, &)
+      config.logger.info(PROGNAME, &) if log?(config, Logger::INFO)
+    end
+
+    def debug(config, &)
+      config.logger.debug(PROGNAME, &) if log?(config, Logger::DEBUG)
+    end
+
+    # A copy of the headers with credential values replaced.
+    def redact_headers(headers)
+      headers.to_h do |name, value|
+        [name, REDACTED_HEADERS.include?(name.to_s.downcase) ? REDACTED : value]
+      end
+    end
+
+    def format_headers(headers)
+      redact_headers(headers).map { |name, value| "#{name}: #{value}" }.join(", ")
+    end
+  end
+end

data/lib/typesafe/questions/choice.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module Questions
+    # Picks one option from a set you define. The answer carries the chosen option,
+    # a probability per option, and a confidence.
+    #
+    # For example:
+    #   TypeSafe::Choice.new(
+    #     instructions: "What is the tone?",
+    #     criteria: { calm: nil, frustrated: nil, angry: "Shouting, threats, or profanity" }
+    #   )
+    class Choice < Question
+      TYPE = "choice"
+
+      def initialize(criteria:, instructions: nil)
+        super(TYPE, instructions: instructions, criteria: self.class.normalize_criteria(criteria))
+      end
+
+      def self.normalize_criteria(criteria)
+        raise ValidationError, "Choice criteria must be a non-empty Hash of option => description" unless
+          criteria.is_a?(Hash) && !criteria.empty?
+
+        criteria.each_with_object({}) do |(key, value), result|
+          name = Util.stringify_key(key)
+          raise ValidationError, "Choice option names must not be blank" if name.strip.empty?
+
+          result[name] = value.nil? ? nil : Util.deep_stringify(value)
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/questions/normalizer.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module Questions
+    # Turns user-supplied state and questions into the wire format, validating the obvious
+    # mistakes before a request is sent.
+    module Normalizer
+      TYPES = {
+        Noul::TYPE => Noul, Choice::TYPE => Choice, Score::TYPE => Score
+      }.freeze
+
+      module_function
+
+      def state(state)
+        raise ValidationError, "state must not be nil; pass a String, Hash, or Array" if state.nil?
+
+        value = Util.deep_stringify(state)
+        return value if value.is_a?(String) || value.is_a?(Hash) || value.is_a?(Array)
+
+        raise ValidationError, "state must be a String, Hash, or Array, got #{state.class}"
+      end
+
+      # Questions in wire format.
+      def questions(questions)
+        raise ValidationError, "questions must be a non-empty Hash" unless questions.is_a?(Hash) && !questions.empty?
+
+        questions.each_with_object({}) do |(name, question), result|
+          key = Util.stringify_key(name)
+          raise ValidationError, "question names must not be blank" if key.strip.empty?
+
+          result[key] = question(question, key)
+        end
+      end
+
+      def question(question, name)
+        case question
+        when Question then question.to_h
+        when Hash then raw_question(question, name)
+        else
+          raise ValidationError,
+                "question #{name.inspect} must be a TypeSafe::Noul, Choice, Score, or a Hash with a \"type\" key"
+        end
+      end
+
+      # Validate a raw Hash question. Known types get the same checks as the typed classes;
+      # unknown types and extra keys pass through untouched so new API fields work immediately.
+      def raw_question(hash, name)
+        wire = Util.deep_stringify(hash)
+        type = wire["type"]
+        unless type.is_a?(String) && !type.empty?
+          raise ValidationError,
+                "question #{name.inspect} is missing a \"type\""
+        end
+
+        klass = TYPES[type]
+        wire["criteria"] = klass.normalize_criteria(wire["criteria"]) if klass && requires_criteria?(klass, wire)
+        wire
+      end
+
+      def requires_criteria?(klass, wire)
+        klass != Noul || wire.key?("criteria")
+      end
+    end
+  end
+end

data/lib/typesafe/questions/noul.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module Questions
+    # A yes/no question. The answer is the probability of yes, from 0 to 1.
+    #
+    # For example:
+    #   TypeSafe::Noul.new(
+    #     instructions: "Is this message spam?",
+    #     criteria: { true: "Unsolicited advertising", false: "A real conversation" }
+    #   )
+    class Noul < Question
+      TYPE = "noul"
+      KEYS = %w[true false].freeze
+
+      def initialize(instructions: nil, criteria: nil)
+        super(TYPE, instructions: instructions, criteria: self.class.normalize_criteria(criteria))
+      end
+
+      def self.normalize_criteria(criteria)
+        return nil if criteria.nil?
+        raise ValidationError, "Noul criteria must be a Hash with true/false keys" unless criteria.is_a?(Hash)
+
+        criteria.each_with_object({}) do |(key, value), result|
+          name = key.to_s
+          unless KEYS.include?(name)
+            raise ValidationError,
+                  "Noul criteria keys must be true or false, got #{key.inspect}"
+          end
+
+          result[name] = value.nil? ? nil : Util.deep_stringify(value)
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/questions/question.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module Questions
+    # Base class for the three typed questions. Instances are immutable value objects
+    # that serialize to the wire format through #to_h.
+    class Question
+      # "noul", "choice" or "score".
+      attr_reader :type
+      # What the model should decide.
+      attr_reader :instructions
+      # Type-specific rubric.
+      attr_reader :criteria
+
+      def initialize(type, instructions:, criteria:)
+        @type = type
+        @instructions = instructions.nil? ? nil : Util.deep_stringify(instructions)
+        @criteria = criteria
+        freeze
+      end
+
+      # The request body fragment for this question.
+      def to_h
+        hash = { "type" => type }
+        hash["instructions"] = instructions unless instructions.nil?
+        hash["criteria"] = criteria unless criteria.nil?
+        hash
+      end
+
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+
+      def ==(other)
+        other.is_a?(Question) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      def inspect
+        "#<#{self.class.name} #{to_h.inspect}>"
+      end
+    end
+  end
+end