typesafe-sdk 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a54e918b7e673dea30f00fb5fa85ea16396686bb9b36a6e8ed46454435eb56eb
+  data.tar.gz: 259eada336581f878ab36ace53984b78fcaaac272b6be94e8f77060bbbc196a1
+SHA512:
+  metadata.gz: ff55db6ad6fe6c4b0a1fcc559b7435a3d9fa5e692b6a43d0be4c07e2e9ebbc0c24f55eadbea6887717b15a30f8701b036a9787722629b09aebf9ef5501d19979
+  data.tar.gz: 84cf649d5ad68239bf4c914853cd392f5c3ee498cf05fe0f456df5feb89228edd7089ae1de552d4e8db862ac9425c4e538cfb16ee7b90fe7a74cf040e4fab469

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-09-16
+
+- Initial release, mirroring the TypeSafe Python SDK 0.6.0
+- `Client#system_one` for Noul, Choice, and Score questions, with typed answers
+- `Client#models.list` for the models available to your account
+- Retry policy with exponential backoff, jitter, `Retry-After` support, and a total retry budget
+- Typed errors for every documented status, plus connection, timeout, and response validation errors
+- Thread-safe, fork-aware keep-alive connection pool on `Net::HTTP`
+- Standard library HTTP and JSON, with Zeitwerk as the only runtime dependency

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Josh Brody
+
+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,359 @@
+# typesafe-sdk
+
+A Ruby client for the [TypeSafe](https://typesafe.ai) System One API. 
+
+## Installation
+
+```bash
+bundle add typesafe-sdk
+```
+
+Or without bundler:
+
+```bash
+gem install typesafe-sdk
+```
+
+Requires Ruby 3.1 or newer.
+
+## Quick start
+
+Grab an API key from the [TypeSafe console](https://console.typesafe.ai/settings/keys) and hand it to the client. It uses `jev-latest` unless you tell it otherwise.
+
+```ruby
+require "typesafe/sdk"
+
+client = Typesafe::SDK::Client.new(api_key: "sk-...")
+
+ticket = "Hi, I've been trying to connect my Stripe account for 3 days and it keeps failing. " \
+         "I'm losing sales. Please help ASAP."
+
+response = client.system_one(
+  state: ticket,
+  questions: {
+    department: Typesafe::SDK::Choice.new(
+      instructions: "Which team should handle this",
+      criteria: {
+        billing: "Payment or subscription issues",
+        technical: "Bugs or integration problems",
+        sales: "Pricing or account questions"
+      }
+    ),
+    frustration: Typesafe::SDK::Score.new(
+      instructions: "How frustrated the customer appears",
+      criteria: ["Calm, just stating facts", "Frustrated but civil", "Very angry, strong language"]
+    ),
+    is_urgent: Typesafe::SDK::Noul.new(instructions: "The message conveys urgency or time-sensitivity")
+  }
+)
+
+response.choices["department"].choice
+response.scores["frustration"].score
+response.nouls["is_urgent"].noul
+```
+
+## Questions
+
+There are three question types. Every question takes optional `instructions`, and `instructions` and criteria can be a string, a hash, or an array if you need more structure than a sentence. See [primitives](https://docs.typesafe.ai/primitives) for when to reach for which.
+
+`Noul` is a yes/no question. The answer is the probability of yes, from 0 to 1. Criteria are optional.
+
+```ruby
+Typesafe::SDK::Noul.new(
+  instructions: "Is this message spam?",
+  criteria: { true: "Unsolicited advertising", false: "A real conversation" }
+)
+```
+
+`Choice` picks one option from a set. Criteria are required; use `nil` when the option name speaks for itself.
+
+```ruby
+Typesafe::SDK::Choice.new(
+  instructions: "What is the tone?",
+  criteria: { calm: nil, frustrated: nil, angry: "Shouting, threats, or profanity" }
+)
+```
+
+`Score` rates the state against ordered levels. Criteria are an array, and each level's position is its score starting at zero.
+
+```ruby
+Typesafe::SDK::Score.new(
+  instructions: "How urgent is this?",
+  criteria: ["Can wait", "Needs attention this week", "Needs attention today"]
+)
+```
+
+You can also pass a plain hash with a `type` key, and you can mix hashes and question objects in the same request. Extra keys go to the API untouched, which is handy when the API ships a field before this gem knows about it.
+
+```ruby
+client.system_one(
+  state: { message: "I was charged twice." },
+  questions: {
+    billing: { type: "noul", instructions: "Is this about billing?", weight: 2 },
+    tone: Typesafe::SDK::Choice.new(criteria: { calm: nil, angry: nil })
+  }
+)
+```
+
+The SDK checks the obvious mistakes before sending anything (no questions, a score with no levels, a hash choice with no criteria, a `Float::NAN` buried in your state) and raises `Typesafe::SDK::Error`, so you don't burn a round trip finding out.
+
+## State
+
+State is whatever you want the questions to be about: a string, a hash, or an array. Symbols and symbol keys get converted to strings; anything that responds to `as_json` gets converted through that. Anything else raises instead of silently sending `"#<Object:0x000...>"` to the model. See [state](https://docs.typesafe.ai/concepts/state) for how to structure it.
+
+## Answers
+
+`system_one` returns a `Typesafe::SDK::SystemOneResponse`.
+
+```ruby
+response.model
+response.usage.input_tokens
+response.usage.output_tokens
+response.request_id
+
+response.answers
+response.nouls
+response.choices
+response.scores
+response[:department]
+```
+
+`answers` holds everything keyed by the name you gave the question. Names always come back as strings, even when you sent symbols, which is why `response[:department]` exists. `nouls`, `choices`, and `scores` are the same answers filtered by type.
+
+`NoulAnswer#noul` is a float from 0 to 1.
+
+`ChoiceAnswer` has `choice`, `confidence`, and `probabilities`, a hash of option name to probability.
+
+`ScoreAnswer` has `score`, `confidence`, `legend`, and `probabilities`. `score` is probability-weighted, so it can land between levels (1.6 is a real answer). `legend` and `probabilities` are keyed by integer level, same as the Python SDK.
+
+Every answer object is frozen and has a `to_h`.
+
+Confidence is the thing you want to gate actions on. Low confidence means the model is telling you it isn't sure, which is useful information and not a failure. The [confidence docs](https://docs.typesafe.ai/confidence) have a good pattern for picking thresholds by risk.
+
+```ruby
+action = response.choices["action"]
+
+if action.confidence < 0.5
+  route_to_human(message)
+elsif action.choice == "approve_transfer" && action.confidence > 0.9
+  confirm_then_execute(account)
+end
+```
+
+If the API sends back an answer type this version doesn't know about, the SDK logs a warning and skips it. The raw response is still on `response.http_response` if you need it:
+
+```ruby
+response.http_response.json["answers"]
+```
+
+## Models
+
+```ruby
+client.models.list.each do |model|
+  puts "#{model.name} #{model.release_date} #{model.description}"
+end
+```
+
+Pick a default model on the client, or override it per call:
+
+```ruby
+client = Typesafe::SDK::Client.new(api_key: api_key, model: "jev")
+client.system_one(state: "hi", questions: questions, model: "jev-latest")
+```
+
+## Configuration
+
+Everything is set on the client. The SDK never reads environment variables, so where the key comes from (Rails credentials, `ENV.fetch`, a vault) is your call.
+
+```ruby
+client = Typesafe::SDK::Client.new(
+  api_key: Rails.application.credentials.dig(:typesafe, :api_key),
+  model: "jev-latest",
+  timeout: 5
+)
+```
+
+| Option | Default |
+| --- | --- |
+| `api_key:` | required |
+| `base_url:` | `https://api.typesafe.ai` |
+| `model:` | `jev-latest` |
+| `timeout:` | `10.0` seconds per HTTP operation |
+| `headers:` | `{}` |
+| `user_agent:` | `typesafe-sdk-ruby/VERSION` |
+| `logger:` | none |
+| `retry_policy:` | `Typesafe::SDK::RetryPolicy.new` |
+| `transport:` | `Typesafe::SDK::NetHttpTransport.new` |
+
+`system_one` also takes `model:`, `timeout:`, `retry_policy:`, `extra_headers:`, and `extra_body:` for a single call. `models.list` takes everything except the body stuff.
+
+`extra_body:` is shallow-merged over the request body last, so it wins any collision with `state`, `model`, or `questions`. Use it for request fields the API has and this gem doesn't yet:
+
+```ruby
+client.system_one(state: "I was charged twice.", questions: questions, extra_body: { beam_width: 4 })
+```
+
+`User-Agent` defaults to `typesafe-sdk-ruby/VERSION`. Set `user_agent:` on the client to change it for every request, or pass it in `extra_headers:` to change it for one call:
+
+```ruby
+client = Typesafe::SDK::Client.new(api_key: api_key, user_agent: "my-app/1.0")
+client.user_agent
+client.system_one(state: state, questions: questions, extra_headers: { "User-Agent" => "nightly-import/1.0" })
+```
+
+A `User-Agent` in the client's `headers:` works too, but `user_agent:` wins if you pass both. `Authorization`, `Accept`, `X-TypeSafe-SDK`, and `X-TypeSafe-Runtime` always win over anything you pass.
+
+## Retries
+
+The client retries 408, 429, and every 5xx (including TypeSafe's 529 overloaded), plus connection failures and timeouts. It does two retries by default with exponential backoff and jitter, honors `Retry-After` and `retry-after-ms`, and gives up once the whole call would blow past a 30-second budget.
+
+```ruby
+policy = Typesafe::SDK::RetryPolicy.new(
+  max_retries: 3,
+  backoff_initial: 0.5,
+  backoff_max: 5.0,
+  backoff_jitter: 0.25,
+  http_statuses: [429, 500, 502, 503, 504, 529],
+  respect_retry_after: true,
+  api_connection_error: true,
+  api_timeout_error: true,
+  exceptions: [],
+  predicate: nil,
+  timeout: 30.0
+)
+
+client = Typesafe::SDK::Client.new(api_key: api_key, retry_policy: policy)
+client.system_one(state: state, questions: questions, retry_policy: Typesafe::SDK::RetryPolicy.new(max_retries: 0))
+```
+
+`timeout` on a retry policy is the total budget for the call across every attempt and sleep, and `nil` turns it off. That's a different thing from the client's `timeout:`, which caps each individual HTTP operation. Retries after the first attempt send an `X-TypeSafe-Retry-Count` header.
+
+`exceptions` and `predicate` let you retry on things the built-in rules don't cover:
+
+```ruby
+Typesafe::SDK::RetryPolicy.new(predicate: ->(error) { error.is_a?(Typesafe::SDK::APIError) && error.status == 409 })
+```
+
+## Errors
+
+Everything the SDK raises inherits from `Typesafe::SDK::Error`.
+
+```ruby
+begin
+  client.system_one(state: state, questions: questions)
+rescue Typesafe::SDK::RateLimitError => e
+  e.retry_after_ms
+rescue Typesafe::SDK::APIError => e
+  e.status
+  e.body
+  e.headers
+  e.request_id
+rescue Typesafe::SDK::APIConnectionError => e
+  e.message
+end
+```
+
+| Error | When |
+| --- | --- |
+| `Error` | bad input, a missing API key, or an invalid option, raised before any request goes out |
+| `APIError` | any non-2xx response without a more specific class below |
+| `BadRequestError` | 400 |
+| `AuthenticationError` | 401 |
+| `PermissionDeniedError` | 403 |
+| `NotFoundError` | 404 |
+| `UnprocessableEntityError` | 422 |
+| `RateLimitError` | 429, with `retry_after_ms` |
+| `InternalServerError` | 500 and up, including 529 |
+| `APIResponseValidationError` | a 2xx whose body is missing something required, with `field_path` like `"answers.tone.confidence"` |
+| `APIConnectionError` | the request never got a response |
+| `APITimeoutError` | a subclass of `APIConnectionError`, with `timeout` |
+
+Error messages pull the useful part out of the API's error body and include the endpoint and request ID, so a log line like this is usually enough to go on:
+
+```
+POST https://api.typesafe.ai/v1/systemone: 401 Cannot authenticate with the server. Please check your API key and try again. (request_id=req_01a0aa64a96a...)
+```
+
+Those are raised after retries run out. Errors that aren't retryable (a 422, say) are raised on the first attempt.
+
+## Logging
+
+Pass anything that responds to `debug`, `info`, and `warn`, like `Logger`:
+
+```ruby
+Typesafe::SDK::Client.new(api_key: api_key, logger: Logger.new)
+```
+
+Or use the built-in stderr logger with a level of `debug`, `info`, `warn`, or `error`:
+
+```ruby
+Typesafe::SDK::Client.new(api_key: api_key, logger: Typesafe::SDK::StderrLogger.new(level: "info"))
+```
+
+No logger means no logging. The `info` level logs one line per request. The `debug` level adds request and response headers and bodies. `Authorization`, cookies, API keys, and any header with `token` or `secret` in the name get redacted. Bodies do not, so be careful turning on `debug` in production if your state has anything sensitive in it.
+
+## Connections and threads
+
+A client keeps a small pool of keep-alive connections, so you only pay for the TLS handshake once instead of on every call. It's safe to share one client across threads; each in-flight request checks out its own connection. The pool notices when your process forks (Puma, Unicorn, Sidekiq swarm) and starts fresh in the child instead of sharing sockets with the parent.
+
+Call `close` when you're done, or use the block form, which closes for you:
+
+```ruby
+Typesafe::SDK::Client.open(api_key: api_key) do |client|
+  client.system_one(state: state, questions: questions)
+end
+```
+
+Proxies come from the usual `http_proxy`/`https_proxy` environment variables, because that's what `Net::HTTP` does.
+
+## Custom transports
+
+`transport:` takes any object with a `call(request)` method. It gets a `Typesafe::SDK::HTTPRequest` (`http_method`, `url`, `headers`, `body`, `timeout`) and must return a `Typesafe::SDK::HTTPResponse`. Raise `APITimeoutError` or `APIConnectionError` when the request fails without a response so the retry policy can do its thing. Implement `close` if you hold resources.
+
+This is mostly for tests, or for when you want to use Faraday or HTTPX anyway:
+
+```ruby
+class RecordingTransport
+  def call(request)
+    Typesafe::SDK::HTTPResponse.new(
+      status: 200,
+      headers: { "content-type" => "application/json" },
+      body: File.read("spec/fixtures/system_one.json")
+    )
+  end
+end
+
+Typesafe::SDK::Client.new(api_key: "test", transport: RecordingTransport.new)
+```
+
+## Differences from the Python SDK
+
+There's no async client. Use threads, or wrap calls in whatever concurrency library you already have, since the client is thread-safe.
+
+`retry` is a reserved word in Ruby, so the option is `retry_policy:`.
+
+There are no environment variables. The Python SDK reads `TYPESAFE_API_KEY` and friends; this one only takes what you pass to the client.
+
+`request_id` returns `nil` when the header is missing instead of raising.
+
+`timeout:` is a single number of seconds. There's no equivalent to `httpx.Timeout` for setting connect and read separately.
+
+The SDK identifies itself as `typesafe-sdk-ruby` in `X-TypeSafe-SDK`, and in `User-Agent` unless you override it.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake test
+bin/console
+```
+
+The tests use minitest. The transport tests stand up a real local TCP server, so there's no HTTP mocking library involved and nothing hits the real API.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/joshmn/typesafe-sdk.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/typesafe/sdk/answer_parser.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class AnswerParser
+      ANSWER_CLASSES = {
+        NoulAnswer::TYPE => NoulAnswer,
+        ChoiceAnswer::TYPE => ChoiceAnswer,
+        ScoreAnswer::TYPE => ScoreAnswer
+      }.freeze
+
+      def initialize(request_logger)
+        @request_logger = request_logger
+      end
+
+      def parse(answers)
+        FieldReader.object(answers, path: "answers").each_with_object({}) do |(name, raw), result|
+          path = FieldReader.join(path: "answers", key: name)
+          answer = FieldReader.object(raw, path: path)
+          type = FieldReader.string(hash: answer, key: "type", path: path)
+          answer_class = ANSWER_CLASSES[type]
+          if answer_class.nil?
+            request_logger.warn("ignoring answer #{name.inspect} with unrecognized type #{type.inspect}")
+            next
+          end
+
+          result[name] = answer_class.from_hash(answer, path: path)
+        end
+      end
+
+      private
+
+      attr_reader :request_logger
+    end
+  end
+end

data/lib/typesafe/sdk/api_error.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class APIError < Error
+      MAX_BODY_LENGTH = 200
+
+      attr_reader :status, :body, :headers, :endpoint
+
+      def initialize(status:, body:, headers:, message: nil, endpoint: nil)
+        @status = status
+        @body = body
+        @headers = headers
+        @endpoint = endpoint
+        super(full_message_for(message || default_message))
+      end
+
+      def request_id
+        headers[REQUEST_ID_HEADER]
+      end
+
+      private
+
+      def default_message
+        detail = ErrorMessage.extract(body)
+        return detail if detail
+        return "status code (no body)" if body.nil?
+
+        raw = body.is_a?(String) ? body : JSON.generate(body)
+        return raw if raw.length <= MAX_BODY_LENGTH
+
+        "#{raw[0, MAX_BODY_LENGTH]}..."
+      end
+
+      def full_message_for(detail)
+        text = detail.to_s.empty? ? status.to_s : "#{status} #{detail}"
+        text = "#{endpoint}: #{text}" if endpoint
+        text = "#{text} (request_id=#{request_id})" if request_id
+        text
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/api_error_factory.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class APIErrorFactory
+      STATUS_ERRORS = {
+        400 => BadRequestError,
+        401 => AuthenticationError,
+        403 => PermissionDeniedError,
+        404 => NotFoundError,
+        422 => UnprocessableEntityError,
+        429 => RateLimitError
+      }.freeze
+
+      class << self
+        def build(response:, endpoint:)
+          error_class_for(response.status).new(
+            status: response.status,
+            body: BodyDecoder.decode(response.body),
+            headers: response.headers,
+            endpoint: endpoint
+          )
+        end
+
+        private
+
+        def error_class_for(status)
+          return STATUS_ERRORS[status] if STATUS_ERRORS.key?(status)
+          return InternalServerError if status >= 500
+
+          APIError
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/api_response_validation_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class APIResponseValidationError < APIError
+      attr_reader :field_path
+
+      def initialize(status:, body:, headers:, field_path:, endpoint: nil)
+        @field_path = field_path
+        super(
+          status: status,
+          body: body,
+          headers: headers,
+          message: "invalid response data at #{field_path.inspect}",
+          endpoint: endpoint
+        )
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/api_timeout_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class APITimeoutError < APIConnectionError
+      attr_reader :timeout
+
+      def initialize(timeout:)
+        @timeout = timeout
+        super("request timed out (timeout=#{timeout})")
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/body_decoder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class BodyDecoder
+      class << self
+        def decode(body)
+          return if body.nil? || body.empty?
+
+          text = body.dup.force_encoding(Encoding::UTF_8)
+          JSON.parse(text)
+        rescue JSON::ParserError, EncodingError
+          text.scrub
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/choice.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class Choice
+      TYPE = "choice"
+
+      attr_reader :criteria, :instructions
+
+      def initialize(criteria:, instructions: nil)
+        raise(Error, "choice criteria must be a hash of options to descriptions") unless criteria.is_a?(Hash)
+
+        @criteria = criteria
+        @instructions = instructions
+        freeze
+      end
+
+      def type
+        TYPE
+      end
+
+      def to_h
+        hash = { "type" => TYPE }
+        hash["instructions"] = JsonValue.normalize(instructions, path: "instructions") unless instructions.nil?
+        hash["criteria"] = JsonValue.normalize(criteria, path: "criteria")
+        hash
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, to_h].hash
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/choice_answer.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class ChoiceAnswer
+      TYPE = "choice"
+
+      attr_reader :choice, :confidence, :probabilities
+
+      class << self
+        def from_hash(hash, path:)
+          new(
+            choice: FieldReader.string(hash: hash, key: "choice", path: path),
+            confidence: FieldReader.number(hash: hash, key: "confidence", path: path),
+            probabilities: FieldReader.number_map(hash: hash, key: "probabilities", path: path)
+          )
+        end
+      end
+
+      def initialize(choice:, confidence:, probabilities:)
+        @choice = choice
+        @confidence = confidence
+        @probabilities = probabilities.freeze
+        freeze
+      end
+
+      def type
+        TYPE
+      end
+
+      def to_h
+        { type: TYPE, choice: choice, confidence: confidence, probabilities: probabilities }
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, to_h].hash
+      end
+    end
+  end
+end