typesafe-ai-ruby 0.1.0

data/lib/typesafe/util.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "time"
+
+module TypeSafe
+  # Internal helpers shared across the gem. Not part of the public API.
+  module Util
+    RETRY_AFTER_MS_HEADER = "retry-after-ms"
+    RETRY_AFTER_HEADER = "retry-after"
+    NUMERIC = /\A\d+(?:\.\d+)?\z/
+
+    module_function
+
+    # True for nil or whitespace-only strings.
+    def blank?(value)
+      value.nil? || (value.respond_to?(:strip) && value.strip.empty?)
+    end
+
+    # Read an environment variable, treating blank values as unset.
+    def env_value(env, name)
+      value = env[name]
+      blank?(value) ? nil : value.strip
+    end
+
+    # Headers with lower-cased names and string values.
+    def normalize_headers(headers)
+      (headers || {}).each_with_object({}) do |(name, value), result|
+        result[name.to_s.downcase] = value.is_a?(Array) ? value.join(", ") : value.to_s
+      end
+    end
+
+    # Convert a value into plain JSON-compatible Ruby: string keys, no symbols, finite floats.
+    # Objects responding to as_json are converted through it. Anything else raises.
+    def deep_stringify(value)
+      case value
+      when String, Integer, true, false, nil then value
+      when Symbol then value.to_s
+      when Float then finite_float(value)
+      when Hash, Array then stringify_container(value)
+      else convert_object(value)
+      end
+    end
+
+    def stringify_container(value)
+      return value.map { |v| deep_stringify(v) } if value.is_a?(Array)
+
+      value.each_with_object({}) { |(k, v), h| h[stringify_key(k)] = deep_stringify(v) }
+    end
+
+    def finite_float(value)
+      raise ValidationError, "non-finite Float #{value} cannot be encoded as JSON" unless value.finite?
+
+      value
+    end
+
+    def stringify_key(key)
+      case key
+      when String then key
+      when Symbol, Integer, true, false then key.to_s
+      else raise ValidationError, "cannot use #{key.class} as a JSON object key"
+      end
+    end
+
+    def convert_object(value)
+      unless value.respond_to?(:as_json)
+        raise ValidationError,
+              "cannot encode #{value.class} as JSON; pass a String, Hash, Array, or an object responding to as_json"
+      end
+
+      converted = value.as_json
+      raise ValidationError, "#{value.class}#as_json returned itself and cannot be encoded" if converted.equal?(value)
+
+      deep_stringify(converted)
+    end
+
+    # Parse retry-after-ms (preferred) or Retry-After (seconds or HTTP-date) into seconds.
+    def parse_retry_after(headers)
+      normalized = normalize_headers(headers)
+      ms = normalized[RETRY_AFTER_MS_HEADER]
+      return ms.to_f / 1000.0 if ms&.match?(NUMERIC)
+
+      raw = normalized[RETRY_AFTER_HEADER]
+      return nil if raw.nil?
+      return raw.to_f if raw.match?(NUMERIC)
+
+      delta = Time.httpdate(raw) - Time.now
+      delta.positive? ? delta : 0.0
+    rescue ArgumentError
+      nil
+    end
+
+    # A short human-readable rendering of an error body for exception messages.
+    def summarize_body(body, limit: 200)
+      text = case body
+             when nil then ""
+             when Hash then summarize_hash(body)
+             when String then body.strip
+             else JSON.generate(body)
+             end
+      text.length > limit ? "#{text[0, limit]}..." : text
+    end
+
+    def summarize_hash(body)
+      error = body["error"]
+      return error if error.is_a?(String)
+      return error["message"] if error.is_a?(Hash) && error["message"].is_a?(String)
+
+      %w[message detail].each do |key|
+        value = body[key]
+        return value.is_a?(String) ? value : JSON.generate(value) if value
+      end
+      JSON.generate(body)
+    end
+
+    # The runtime identifier sent in X-TypeSafe-Runtime.
+    def runtime
+      "ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})"
+    end
+  end
+
+  # A Hash whose string keys can also be looked up with symbols.
+  class IndifferentHash < Hash
+    def self.from(hash)
+      new.tap { |result| hash.each { |key, value| result[key] = value } }
+    end
+
+    def [](key)
+      super(convert(key))
+    end
+
+    def []=(key, value)
+      super(convert(key), value)
+    end
+
+    def fetch(key, ...)
+      super(convert(key), ...)
+    end
+
+    def key?(key)
+      super(convert(key))
+    end
+    alias has_key? key?
+    alias include? key?
+    alias member? key?
+
+    def dig(key, *rest)
+      super(convert(key), *rest)
+    end
+
+    private
+
+    def convert(key)
+      key.is_a?(Symbol) ? key.to_s : key
+    end
+  end
+end

data/lib/typesafe/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  VERSION = "0.1.0"
+end

data/lib/typesafe-ai-ruby.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name so that Bundler's automatic require works.
+require_relative "typesafe"

data/lib/typesafe.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+require "logger"
+require "net/http"
+require "openssl"
+require "uri"
+
+require_relative "typesafe/version"
+require_relative "typesafe/constants"
+require_relative "typesafe/util"
+require_relative "typesafe/errors"
+require_relative "typesafe/logging"
+require_relative "typesafe/instrumentation"
+require_relative "typesafe/configuration"
+require_relative "typesafe/retry_policy"
+require_relative "typesafe/request_options"
+require_relative "typesafe/questions/question"
+require_relative "typesafe/questions/noul"
+require_relative "typesafe/questions/choice"
+require_relative "typesafe/questions/score"
+require_relative "typesafe/questions/normalizer"
+require_relative "typesafe/http/request"
+require_relative "typesafe/http/response"
+require_relative "typesafe/http/connection_manager"
+require_relative "typesafe/http/net_http_transport"
+require_relative "typesafe/http/retrier"
+require_relative "typesafe/http/requestor"
+require_relative "typesafe/responses/reader"
+require_relative "typesafe/responses/usage"
+require_relative "typesafe/responses/answer"
+require_relative "typesafe/responses/system_one_response"
+require_relative "typesafe/responses/list_models_response"
+require_relative "typesafe/resources/models"
+require_relative "typesafe/client"
+
+# Ruby client for the TypeSafe AI System One API.
+#
+# See https://docs.typesafe.ai/ for the HTTP API this gem wraps.
+module TypeSafe
+  Noul = Questions::Noul
+  Choice = Questions::Choice
+  Score = Questions::Score
+
+  class << self
+    # Global settings used by .client. Mutate through .configure.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the default client.
+    #
+    # For example:
+    #   TypeSafe.configure do |c|
+    #     c.api_key = Rails.application.credentials.typesafe_api_key
+    #     c.logger  = Rails.logger
+    #   end
+    def configure
+      yield configuration
+      reset_client!
+      configuration
+    end
+
+    # The default client built from .configuration. Memoized until .configure is called again.
+    def client
+      @client ||= Client.new(**configuration.to_h)
+    end
+
+    # Discard the memoized default client. Mostly useful in tests.
+    def reset_client!
+      @client&.close
+      @client = nil
+    end
+
+    # Reset global configuration and the default client. Mostly useful in tests.
+    def reset!
+      reset_client!
+      @configuration = nil
+    end
+
+    # Build a yes/no question.
+    #
+    # For example:
+    #   TypeSafe.noul("Is this spam?", true: "Unsolicited advertising", false: "A real conversation")
+    def noul(instructions = nil, criteria = nil, **named)
+      Noul.new(instructions: instructions, criteria: merge_criteria(criteria, named))
+    end
+
+    # Build a choice question.
+    #
+    # For example:
+    #   TypeSafe.choice("What is the tone?", calm: nil, angry: "Shouting or threats")
+    def choice(instructions = nil, criteria = nil, **named)
+      Choice.new(instructions: instructions, criteria: merge_criteria(criteria, named) || {})
+    end
+
+    # Build a score question.
+    #
+    # For example:
+    #   TypeSafe.score("How urgent is this?", ["can wait", "this week", "today"])
+    def score(instructions = nil, criteria = nil)
+      Score.new(instructions: instructions, criteria: criteria)
+    end
+
+    private
+
+    def merge_criteria(positional, named)
+      return positional if named.empty?
+      raise ArgumentError, "pass criteria either positionally or as keywords, not both" unless positional.nil?
+
+      named
+    end
+  end
+end

data/sig/typesafe/http.rbs

@@ -0,0 +1,77 @@
+module TypeSafe
+  module HTTP
+    # Anything that can send a Request and return a Response, such as NetHTTPTransport.
+    interface _Transport
+      def call: (Request request) -> Response
+    end
+
+    class Request
+      attr_reader method: Symbol
+      attr_reader uri: URI::HTTP
+      attr_reader headers: Hash[String, String]
+      attr_reader body: String?
+      attr_reader timeout: Numeric
+
+      def initialize: (method: Symbol, uri: URI::HTTP, headers: Hash[String, String], body: String?, timeout: Numeric) -> void
+      def endpoint: () -> String
+      def with_headers: (Hash[String, String] extra) -> Request
+    end
+
+    class Response
+      attr_reader status: Integer
+      attr_reader headers: Hash[String, String]
+      attr_reader body: String
+      attr_reader request: Request?
+
+      def initialize: (status: Integer, headers: Hash[untyped, untyped], body: String?, ?request: Request?) -> void
+      def []: (String | Symbol name) -> String?
+      def request_id: () -> String?
+      def success?: () -> bool
+      def json: () -> untyped
+      def retry_after: () -> Float?
+    end
+
+    class ConnectionManager
+      IDLE_TIMEOUT: Integer
+
+      def initialize: (?clock: (^() -> Float)?) -> void
+      def connection_for: (URI::HTTP uri, timeout: Numeric) -> Net::HTTP
+      def discard: (URI::HTTP uri) -> void
+      def clear: () -> void
+      def size: () -> Integer
+    end
+
+    class NetHTTPTransport
+      TIMEOUT_ERRORS: Array[singleton(Exception)]
+      CONNECTION_ERRORS: Array[singleton(Exception)]
+
+      def initialize: () -> void
+      def call: (Request request) -> Response
+      def close: () -> void
+      def connection_manager: () -> ConnectionManager
+    end
+
+    class Retrier
+      MONOTONIC: Integer
+
+      attr_reader policy: RetryPolicy
+
+      def initialize: (RetryPolicy policy, ?sleeper: (^(Numeric) -> void)?, ?clock: (^() -> Float)?,
+                       ?random: RetryPolicy::_Random, ?on_retry: (^(Exception, Integer, Numeric) -> void)?) -> void
+      def run: [T] () { (Integer attempt) -> T } -> T
+    end
+
+    class Requestor
+      PROTECTED_HEADERS: Array[String]
+
+      attr_reader config: Configuration
+      attr_reader transport: _Transport
+
+      def initialize: (Configuration config, ?transport: _Transport?, ?sleeper: (^(Numeric) -> void)?,
+                       ?clock: (^() -> Float)?) -> void
+      def post: (String path, body: Hash[String, untyped], ?options: RequestOptions) -> Response
+      def get: (String path, ?options: RequestOptions) -> Response
+      def close: () -> void
+    end
+  end
+end

data/sig/typesafe/questions.rbs

@@ -0,0 +1,48 @@
+module TypeSafe
+  module Questions
+    class Question
+      attr_reader type: String
+      attr_reader instructions: json_content?
+      attr_reader criteria: untyped
+
+      def initialize: (String type, instructions: json_input?, criteria: untyped) -> void
+      def to_h: () -> Hash[String, untyped]
+      def to_json: (*untyped args) -> String
+      def ==: (untyped other) -> bool
+      alias eql? ==
+      def hash: () -> Integer
+    end
+
+    class Noul < Question
+      TYPE: String
+      KEYS: Array[String]
+
+      def initialize: (?instructions: json_input?, ?criteria: Hash[untyped, untyped]?) -> void
+      def self.normalize_criteria: (Hash[untyped, untyped]? criteria) -> Hash[String, json_content?]?
+    end
+
+    class Choice < Question
+      TYPE: String
+
+      def initialize: (?instructions: json_input?, criteria: Hash[untyped, untyped]) -> void
+      def self.normalize_criteria: (Hash[untyped, untyped] criteria) -> Hash[String, json_content?]
+    end
+
+    class Score < Question
+      TYPE: String
+      MIN_LEVELS: Integer
+
+      def initialize: (?instructions: json_input?, criteria: Array[untyped]) -> void
+      def self.normalize_criteria: (Array[untyped] criteria) -> Array[json_content]
+    end
+
+    module Normalizer
+      TYPES: Hash[String, singleton(Question)]
+
+      def self?.state: (json_input state) -> json_content
+      def self?.questions: (Hash[String | Symbol, question_input] questions) -> Hash[String, Hash[String, untyped]]
+      def self?.question: (question_input question, String name) -> Hash[String, untyped]
+      def self?.raw_question: (Hash[untyped, untyped] hash, String name) -> Hash[String, untyped]
+    end
+  end
+end

data/sig/typesafe/responses.rbs

@@ -0,0 +1,131 @@
+module TypeSafe
+  module Responses
+    class InvalidField < StandardError
+      attr_reader field_path: String
+
+      def initialize: (String field_path, String message) -> void
+    end
+
+    module Reader
+      def self?.validation_error: (InvalidField error, HTTP::Response response, untyped json) -> APIResponseValidationError
+      def self?.hash!: (untyped value, String path) -> Hash[String, untyped]
+      def self?.string!: (untyped value, String path) -> String
+      def self?.number!: (untyped value, String path) -> Float
+      def self?.optional_integer: (untyped value, String path) -> Integer?
+      def self?.optional_string: (untyped value, String path) -> String?
+      def self?.number_map!: (untyped value, String path) -> Hash[String, Float]
+      def self?.integer_keyed: (Hash[String, untyped] hash, String path) -> Hash[Integer, untyped]
+    end
+
+    class Usage
+      attr_reader input_tokens: Integer?
+      attr_reader output_tokens: Integer?
+
+      def self.from_hash: (untyped hash, ?String path) -> Usage
+      def initialize: (?input_tokens: Integer?, ?output_tokens: Integer?) -> void
+      def to_h: () -> Hash[String, Integer?]
+      def ==: (untyped other) -> bool
+      alias eql? ==
+      def hash: () -> Integer
+    end
+
+    class Answer
+      TYPES: Hash[String, singleton(Answer)]
+
+      attr_reader type: String
+      attr_reader raw: Hash[String, untyped]
+
+      def self.from_hash: (untyped hash, String path) -> Answer
+      def initialize: (Hash[String, untyped] raw) -> void
+      def to_h: () -> Hash[String, untyped]
+      def to_json: (*untyped args) -> String
+      def ==: (untyped other) -> bool
+      alias eql? ==
+      def hash: () -> Integer
+    end
+
+    class NoulAnswer < Answer
+      attr_reader noul: Float
+
+      def self.parse: (Hash[String, untyped] data, String path) -> NoulAnswer
+      def initialize: (Hash[String, untyped] raw, noul: Float) -> void
+    end
+
+    class ChoiceAnswer < Answer
+      attr_reader choice: String
+      attr_reader probabilities: IndifferentHash
+      attr_reader confidence: Float
+
+      def self.parse: (Hash[String, untyped] data, String path) -> ChoiceAnswer
+      def initialize: (Hash[String, untyped] raw, choice: String, probabilities: Hash[String, Float], confidence: Float) -> void
+    end
+
+    class ScoreAnswer < Answer
+      attr_reader score: Float
+      attr_reader legend: Hash[Integer, json_content]
+      attr_reader probabilities: Hash[Integer, Float]
+      attr_reader confidence: Float
+
+      def self.parse: (Hash[String, untyped] data, String path) -> ScoreAnswer
+      def initialize: (Hash[String, untyped] raw, score: Float, legend: Hash[Integer, untyped],
+                       probabilities: Hash[Integer, Float], confidence: Float) -> void
+      def raw_legend: () -> Hash[String, untyped]
+      def raw_probabilities: () -> Hash[String, Numeric]
+    end
+
+    class UnknownAnswer < Answer
+      def self.parse: (Hash[String, untyped] data, String path) -> UnknownAnswer
+    end
+
+    class SystemOneResponse
+      attr_reader model: String
+      attr_reader usage: Usage
+      attr_reader answers: IndifferentHash
+      attr_reader http_response: HTTP::Response?
+      attr_reader raw: Hash[String, untyped]?
+
+      def self.from_http: (HTTP::Response response) -> SystemOneResponse
+      def self.parse: (untyped json, HTTP::Response? response) -> SystemOneResponse
+      def self.parse_answers: (untyped answers) -> Hash[String, Answer]
+      def initialize: (model: String, usage: Usage, answers: Hash[untyped, Answer], ?http_response: HTTP::Response?,
+                       ?raw: Hash[String, untyped]?) -> void
+      def []: (String | Symbol name) -> Answer?
+      def request_id: () -> String?
+      def nouls: () -> IndifferentHash
+      def choices: () -> IndifferentHash
+      def scores: () -> IndifferentHash
+      def to_h: () -> Hash[String, untyped]
+      def to_json: (*untyped args) -> String
+    end
+
+    class ModelCard
+      attr_reader name: String
+      attr_reader description: String?
+      attr_reader release_date: String?
+      attr_reader raw: Hash[String, untyped]
+
+      def self.from_hash: (untyped hash, String path) -> ModelCard
+      def initialize: (Hash[String, untyped] raw, name: String, ?description: String?, ?release_date: String?) -> void
+      def to_h: () -> Hash[String, untyped]
+      def ==: (untyped other) -> bool
+      alias eql? ==
+      def hash: () -> Integer
+    end
+
+    class ListModelsResponse
+      include Enumerable[ModelCard]
+
+      attr_reader models: Array[ModelCard]
+      attr_reader http_response: HTTP::Response?
+      attr_reader raw: Hash[String, untyped]?
+
+      def self.from_http: (HTTP::Response response) -> ListModelsResponse
+      def self.parse_models: (untyped list) -> Array[ModelCard]
+      def initialize: (models: Array[ModelCard], ?http_response: HTTP::Response?, ?raw: Hash[String, untyped]?) -> void
+      def each: () { (ModelCard) -> void } -> void
+      def names: () -> Array[String]
+      def request_id: () -> String?
+      def to_h: () -> Hash[String, untyped]
+    end
+  end
+end