jevrb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b6cbd6d5e5d64de85540ed6e81c4138c52513d71d65d25d0e2392450aa9c8f31
+  data.tar.gz: c3854400cd7512cc76db614f12fb29806b34d718d8b5642f76dfe2c1d9f3bbcd
+SHA512:
+  metadata.gz: eae41617e1af7c67c64a47daba002b1ba46b48aef4e4a791cdedd9b6bfa864037c3d323893c8e850f15595b3ffd9203bd017c9af7fde803f8752409e02371e44
+  data.tar.gz: 74c0c33ae5996a765cb8c8c1bd5b2e97dff653d13e0cf62a118060935c6743bcf61069cb931b82373db5902b802897e3edfe6321613966e648dae23fc9d963a8

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maful
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,175 @@
+# Jevrb
+
+Jevrb is a synchronous Ruby client for the TypeSafe System One API. It returns immutable Ruby objects for every documented answer type.
+
+## Requirements
+
+- Ruby 3.2 or later.
+- A TypeSafe API key.
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "jevrb"
+```
+
+Install the bundle:
+
+```bash
+bundle install
+```
+
+## Quick start
+
+Set the API key:
+
+```bash
+export TYPESAFE_API_KEY="your-api-key"
+```
+
+Create a client and send a request:
+
+```ruby
+require "jevrb"
+
+client = Jev::Client.new
+
+result = client.system_one(
+  "Help! My payouts have been failing for 3 days.",
+  questions: {
+    is_urgent: Jev::Noul.build(
+      instructions: "Does this convey urgency?"
+    ),
+    department: Jev::Choice.build(
+      instructions: "Which team must handle this?",
+      criteria: {
+        billing: "Payments, invoicing, and refunds",
+        technical: "Bugs, outages, and integrations"
+      }
+    ),
+    frustration: Jev::Score.build(
+      instructions: "How frustrated is the customer?",
+      criteria: ["Calm", "Frustrated", "Very angry"]
+    )
+  }
+)
+```
+
+## Read the result
+
+Each answer is a typed object:
+
+```ruby
+result                         # Jev::Result
+result.model                   # "jev-1.13.0"
+result.usage                   # Jev::Usage
+result.answers[:is_urgent]     # Jev::NoulAnswer
+result.answers[:department]    # Jev::ChoiceAnswer
+result.answers[:frustration]   # Jev::ScoreAnswer
+```
+
+Use the grouped accessors when a request contains different question types:
+
+```ruby
+result.nouls[:is_urgent].noul
+
+result.choices[:department].choice
+result.choices[:department].probabilities
+result.choices[:department].confidence
+
+result.scores[:frustration].score
+result.scores[:frustration].legend
+result.scores[:frustration].probabilities
+result.scores[:frustration].confidence
+```
+
+## Structured content
+
+The state and instructions accept strings, hashes, and arrays. Nested values must be valid JSON values.
+
+```ruby
+question = Jev::Noul.build(
+  instructions: {
+    potential_duplicate: {
+      name: "John Smith",
+      location: "Oakland, California"
+    },
+    question: "Is the resume for the same person as `potential_duplicate`?"
+  }
+)
+```
+
+## Client options
+
+`Jev::Client.new` accepts these options:
+
+| Option | Default |
+|---|---|
+| `api_key:` | `TYPESAFE_API_KEY` |
+| `base_url:` | `TYPESAFE_BASE_URL` or `https://api.typesafe.ai` |
+| `model:` | `TYPESAFE_DEFAULT_MODEL` or `jev-latest` |
+| `timeout:` | `10.0` seconds |
+| `retry_policy:` | `Jev::RetryPolicy.new` |
+
+Set `model:` on `system_one` to replace the client model for one request.
+
+## Retries
+
+The default policy retries connection errors, timeout errors, and these HTTP responses:
+
+- `408 Request Timeout`.
+- `429 Too Many Requests`.
+- HTTP status codes from 500 through 599.
+
+The policy retries twice after the first request. It obeys `Retry-After` and `retry-after-ms` response headers.
+
+Disable retries when you create the client:
+
+```ruby
+client = Jev::Client.new(
+  retry_policy: Jev::RetryPolicy.new(max_retries: 0)
+)
+```
+
+## Errors
+
+All SDK errors inherit from `Jev::Error`.
+
+Client and response errors include these classes:
+
+- `Jev::ConfigurationError`.
+- `Jev::ConnectionError`.
+- `Jev::TimeoutError`.
+- `Jev::ResponseValidationError`.
+
+HTTP errors inherit from `Jev::APIError`. The error exposes `status`, `body`, `headers`, `endpoint`, and `request_id`.
+
+## Static types
+
+The gem includes RBS declarations in `sig/jevrb.rbs`.
+
+Validate the declarations:
+
+```bash
+bundle exec rbs -I sig validate
+```
+
+## Development
+
+Install the development dependencies:
+
+```bash
+bin/setup
+```
+
+Run the tests, RBS validation, and RuboCop:
+
+```bash
+bundle exec rake
+```
+
+## License
+
+Jevrb uses the MIT License.

data/lib/jevrb/answer.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module Jevrb
+  class ResponseDataError < StandardError
+    attr_reader :field_path
+
+    def initialize(field_path, message)
+      @field_path = field_path
+      super(message)
+    end
+  end
+  private_constant :ResponseDataError
+
+  module ResponseSupport
+    module_function
+
+    def hash(value, path)
+      return value if value.is_a?(Hash)
+
+      raise ResponseDataError.new(path, "#{path} must be an object")
+    end
+
+    def required(value, key, path)
+      return value[key] if value.key?(key)
+
+      raise ResponseDataError.new("#{path}.#{key}", "#{path}.#{key} is required")
+    end
+
+    def string(value, path)
+      return value.dup.freeze if value.is_a?(String)
+
+      raise ResponseDataError.new(path, "#{path} must be a string")
+    end
+
+    def number(value, path, range: nil)
+      unless (value.is_a?(Integer) || value.is_a?(Float)) && (!value.is_a?(Float) || value.finite?)
+        raise ResponseDataError.new(path, "#{path} must be a finite number")
+      end
+      if range && !range.cover?(value)
+        raise ResponseDataError.new(path, "#{path} must be between #{range.begin} and #{range.end}")
+      end
+
+      value.to_f
+    end
+
+    def integer_or_nil(value, path)
+      return if value.nil?
+      return value if value.is_a?(Integer) && value >= 0
+
+      raise ResponseDataError.new(path, "#{path} must be a nonnegative integer or null")
+    end
+
+    def probability_hash(value, path, integer_keys: false)
+      hash(value, path).each_with_object({}) do |(key, probability), result|
+        normalized_key = integer_keys ? integer_key(key, path) : string(key, "#{path} key")
+        result[normalized_key] = number(probability, "#{path}.#{key}", range: 0.0..1.0)
+      end.freeze
+    end
+
+    def integer_key(value, path)
+      integer = Integer(value, 10)
+      return integer if integer.to_s == value.to_s
+
+      raise ArgumentError
+    rescue ArgumentError, TypeError
+      raise ResponseDataError.new(path, "#{path} keys must be integer strings")
+    end
+
+    def json_content(value, path)
+      Support.normalize_json_content(value, path: path)
+    rescue ArgumentError => e
+      raise ResponseDataError.new(path, e.message)
+    end
+  end
+  private_constant :ResponseSupport
+
+  class Answer
+    attr_reader :type
+
+    private
+
+    def initialize(type)
+      @type = type.freeze
+    end
+
+    def finish_initialization
+      freeze
+    end
+  end
+
+  class NoulAnswer < Answer
+    attr_reader :noul
+
+    def self.from_hash(value, path:)
+      value = ResponseSupport.hash(value, path)
+      type = ResponseSupport.string(ResponseSupport.required(value, "type", path), "#{path}.type")
+      raise ResponseDataError.new("#{path}.type", "#{path}.type must be noul") unless type == "noul"
+
+      new(noul: ResponseSupport.number(
+        ResponseSupport.required(value, "noul", path),
+        "#{path}.noul",
+        range: 0.0..1.0
+      ))
+    end
+
+    def to_h
+      { type: type, noul: noul }
+    end
+
+    private
+
+    def initialize(noul:)
+      super("noul")
+      @noul = noul
+      finish_initialization
+    end
+  end
+
+  class ChoiceAnswer < Answer
+    attr_reader :choice, :probabilities, :confidence
+
+    def self.from_hash(value, path:)
+      value = ResponseSupport.hash(value, path)
+      type = ResponseSupport.string(ResponseSupport.required(value, "type", path), "#{path}.type")
+      raise ResponseDataError.new("#{path}.type", "#{path}.type must be choice") unless type == "choice"
+
+      new(
+        choice: ResponseSupport.string(ResponseSupport.required(value, "choice", path), "#{path}.choice"),
+        probabilities: ResponseSupport.probability_hash(
+          ResponseSupport.required(value, "probabilities", path),
+          "#{path}.probabilities"
+        ),
+        confidence: ResponseSupport.number(
+          ResponseSupport.required(value, "confidence", path),
+          "#{path}.confidence",
+          range: 0.0..1.0
+        )
+      )
+    end
+
+    def to_h
+      {
+        type: type,
+        choice: choice,
+        probabilities: probabilities,
+        confidence: confidence
+      }
+    end
+
+    private
+
+    def initialize(choice:, probabilities:, confidence:)
+      super("choice")
+      @choice = choice
+      @probabilities = probabilities
+      @confidence = confidence
+      finish_initialization
+    end
+  end
+
+  class ScoreAnswer < Answer
+    attr_reader :score, :legend, :probabilities, :confidence
+
+    def self.from_hash(value, path:)
+      value = ResponseSupport.hash(value, path)
+      type = ResponseSupport.string(ResponseSupport.required(value, "type", path), "#{path}.type")
+      raise ResponseDataError.new("#{path}.type", "#{path}.type must be score") unless type == "score"
+
+      new(
+        score: ResponseSupport.number(ResponseSupport.required(value, "score", path), "#{path}.score"),
+        legend: parse_legend(ResponseSupport.required(value, "legend", path), "#{path}.legend"),
+        probabilities: ResponseSupport.probability_hash(
+          ResponseSupport.required(value, "probabilities", path),
+          "#{path}.probabilities",
+          integer_keys: true
+        ),
+        confidence: ResponseSupport.number(
+          ResponseSupport.required(value, "confidence", path),
+          "#{path}.confidence",
+          range: 0.0..1.0
+        )
+      )
+    end
+
+    def self.parse_legend(value, path)
+      ResponseSupport.hash(value, path).each_with_object({}) do |(key, description), result|
+        integer_key = ResponseSupport.integer_key(key, path)
+        result[integer_key] = ResponseSupport.json_content(description, "#{path}.#{key}")
+      end.freeze
+    end
+    private_class_method :parse_legend
+
+    def to_h
+      {
+        type: type,
+        score: score,
+        legend: legend,
+        probabilities: probabilities,
+        confidence: confidence
+      }
+    end
+
+    private
+
+    def initialize(score:, legend:, probabilities:, confidence:)
+      super("score")
+      @score = score
+      @legend = legend
+      @probabilities = probabilities
+      @confidence = confidence
+      finish_initialization
+    end
+  end
+end

data/lib/jevrb/choice.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Jevrb
+  class Choice < Question
+    MAX_OPTIONS = 255
+
+    def self.build(instructions:, criteria:)
+      new(instructions: instructions, criteria: criteria)
+    end
+
+    private
+
+    def initialize(instructions:, criteria:)
+      super(type: "choice", instructions: instructions, criteria: normalize_criteria(criteria))
+    end
+
+    def normalize_criteria(criteria)
+      raise ArgumentError, "criteria must be a hash" unless criteria.is_a?(Hash)
+      raise ArgumentError, "criteria must not be empty" if criteria.empty?
+      raise ArgumentError, "criteria cannot contain more than #{MAX_OPTIONS} options" if criteria.size > MAX_OPTIONS
+
+      criteria.each_with_object({}) do |(key, value), result|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise ArgumentError, "criteria option names must be strings or symbols"
+        end
+
+        normalized_key = key.to_s
+        if result.key?(normalized_key)
+          raise ArgumentError,
+                "criteria contains duplicate option #{normalized_key.inspect}"
+        end
+
+        result[normalized_key.freeze] = Support.normalize_json_content(
+          value,
+          path: "criteria.#{normalized_key}",
+          allow_nil: true
+        )
+      end.freeze
+    end
+  end
+end

data/lib/jevrb/client.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Jevrb
+  class Client
+    NOT_GIVEN = Object.new.freeze
+    SYSTEM_ONE_PATH = "/v1/systemone"
+
+    attr_reader :api_key, :base_url, :model, :timeout, :retry_policy
+
+    def initialize(
+      api_key: NOT_GIVEN,
+      base_url: NOT_GIVEN,
+      model: NOT_GIVEN,
+      timeout: DEFAULT_TIMEOUT,
+      retry_policy: nil
+    )
+      @api_key = client_value(api_key, API_KEY_ENV)
+      @base_url = client_value(base_url, BASE_URL_ENV, DEFAULT_BASE_URL)
+      @model = client_value(model, DEFAULT_MODEL_ENV, DEFAULT_MODEL)
+      @timeout = positive_number(timeout, "timeout")
+      @retry_policy = retry_policy || RetryPolicy.new
+
+      validate_configuration
+      @transport = Transport.new(base_url: @base_url)
+    end
+
+    def system_one(state, questions:, model: nil)
+      state = Support.normalize_json_content(state, path: "state")
+      questions, key_map = serialize_questions(questions)
+      request_model = model.nil? ? @model : nonempty_string(model, "model")
+      body = JSON.generate(state: state, model: request_model, questions: questions)
+      endpoint = @transport.endpoint(SYSTEM_ONE_PATH)
+
+      retry_policy.execute do
+        response = @transport.post(
+          SYSTEM_ONE_PATH,
+          body: body,
+          headers: request_headers,
+          timeout: timeout
+        )
+        handle_response(response, endpoint: endpoint, key_map: key_map)
+      end
+    end
+
+    private
+
+    def client_value(explicit, environment_name, default = nil)
+      return normalize_client_value(explicit) unless explicit.equal?(NOT_GIVEN)
+
+      environment_value = ENV.fetch(environment_name, nil)
+      normalized = normalize_client_value(environment_value)
+      normalized.nil? ? default : normalized
+    end
+
+    def normalize_client_value(value)
+      return if value.nil?
+      return value.strip if value.is_a?(String)
+
+      value
+    end
+
+    def validate_configuration
+      raise ConfigurationError, "api_key is required" unless api_key.is_a?(String) && !api_key.empty?
+
+      raise ConfigurationError, "model must be a nonempty string" unless model.is_a?(String) && !model.empty?
+
+      validate_base_url
+      return if retry_policy.is_a?(RetryPolicy)
+
+      raise ConfigurationError, "retry_policy must be a Jevrb::RetryPolicy"
+    end
+
+    def validate_base_url
+      unless base_url.is_a?(String) && !base_url.empty?
+        raise ConfigurationError, "base_url must be an HTTP or HTTPS URL"
+      end
+
+      uri = URI.parse(base_url)
+      valid = %w[http https].include?(uri.scheme) && uri.host && !uri.userinfo && !uri.query && !uri.fragment
+      raise ConfigurationError, "base_url must be an HTTP or HTTPS URL" unless valid
+    rescue URI::InvalidURIError
+      raise ConfigurationError, "base_url must be an HTTP or HTTPS URL"
+    end
+
+    def nonempty_string(value, name)
+      return value if value.is_a?(String) && !value.empty?
+
+      raise ArgumentError, "#{name} must be a nonempty string"
+    end
+
+    def positive_number(value, name)
+      return value.to_f if (value.is_a?(Integer) || value.is_a?(Float)) && value.finite? && value.positive?
+
+      raise ConfigurationError, "#{name} must be a positive number"
+    end
+
+    def serialize_questions(questions)
+      raise ArgumentError, "questions must be a hash" unless questions.is_a?(Hash)
+      raise ArgumentError, "questions must not be empty" if questions.empty?
+
+      key_map = {}
+      serialized = questions.each_with_object({}) do |(key, question), result|
+        raise ArgumentError, "question names must be strings or symbols" unless key.is_a?(String) || key.is_a?(Symbol)
+        raise ArgumentError, "questions must contain Jevrb question objects" unless question.is_a?(Question)
+
+        normalized_key = key.to_s
+        if result.key?(normalized_key)
+          raise ArgumentError,
+                "questions contains duplicate name #{normalized_key.inspect}"
+        end
+
+        result[normalized_key] = question.to_h
+        key_map[normalized_key] = key
+      end
+
+      [serialized, key_map.freeze]
+    end
+
+    def request_headers
+      {
+        "Authorization" => "Bearer #{api_key}",
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "User-Agent" => "jevrb/#{VERSION}"
+      }
+    end
+
+    def handle_response(response, endpoint:, key_map:)
+      raise api_error(response, endpoint: endpoint) unless (200..299).cover?(response.status)
+
+      parsed = JSON.parse(response.body.to_s)
+      Result.from_hash(
+        parsed,
+        key_map: key_map,
+        request_id: response.headers["x-typesafe-request-id"]
+      )
+    rescue JSON::ParserError => e
+      raise response_validation_error(response, endpoint, "$", e.message)
+    rescue ResponseDataError => e
+      raise response_validation_error(response, endpoint, e.field_path, e.message)
+    end
+
+    def response_validation_error(response, endpoint, field_path, message)
+      ResponseValidationError.new(
+        status: response.status,
+        body: response.body,
+        headers: response.headers,
+        field_path: field_path,
+        endpoint: "POST #{endpoint}",
+        message: message
+      )
+    end
+
+    def api_error(response, endpoint:)
+      error_class = case response.status
+                    when 400 then BadRequestError
+                    when 401 then AuthenticationError
+                    when 403 then PermissionDeniedError
+                    when 404 then NotFoundError
+                    when 422 then UnprocessableEntityError
+                    when 429 then RateLimitError
+                    when 500..599 then InternalServerError
+                    else APIError
+                    end
+
+      error_class.new(
+        status: response.status,
+        body: parse_error_body(response.body),
+        headers: response.headers,
+        endpoint: "POST #{endpoint}"
+      )
+    end
+
+    def parse_error_body(body)
+      return if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+  end
+end

data/lib/jevrb/constants.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Jevrb
+  API_KEY_ENV = "TYPESAFE_API_KEY"
+  BASE_URL_ENV = "TYPESAFE_BASE_URL"
+  DEFAULT_MODEL_ENV = "TYPESAFE_DEFAULT_MODEL"
+
+  DEFAULT_BASE_URL = "https://api.typesafe.ai"
+  DEFAULT_MODEL = "jev-latest"
+  DEFAULT_TIMEOUT = 10.0
+end