typesafe-sdk-ruby 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c2f7c356ecf7107179e8d01aeec562af105267ef4fc640b9a95a8d0c0904413f
+  data.tar.gz: 5a7657f8bc722b9c7ecae8f126b7792b2911b08bbc006a54114f16fb0bf73bb3
+SHA512:
+  metadata.gz: 62fd70fb931ccaae55504bb8ed8db5b674e347978704d938a178003e339c0061ed8f4f5de62574298471dd29b21369e6a82cf8d549985cf9e0e8c22781299a1d
+  data.tar.gz: ac8620432b7afd9cb36ec5e1a64b16fe3709590c3597234401cc71ab797558676441034af33b4b17ff4f650082a7f7627579dba5248db0a98c1ca5b734a48e04

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.6.0] - 2026-09-20
+
+Initial release. A community port of the official
+[TypeSafe JavaScript SDK](https://github.com/typesafe-ai/typesafe-sdk-js) v0.6.0.
+
+Published as the `typesafe-sdk-ruby` gem (the `typesafe-sdk` name is already taken on
+RubyGems by an unrelated project).
+
+### Added
+
+- `Typesafe::SDK::Client` with `system_one` and a `models` resource.
+- Question builders: `noul`, `score`, and `choice`, with request validation.
+- Typed answer objects: `NoulResponse`, `ChoiceResponse`, `ScoreResponse`, plus `Usage`
+  and `ModelCard`.
+- Automatic retries for HTTP 408/429/5xx, connection failures, and timeouts, with capped
+  exponential backoff, jitter, and `Retry-After` / `retry-after-ms` support.
+- Per-attempt timeouts and cooperative cancellation via `Typesafe::SDK::Signal`.
+- Typed error hierarchy: `TypeSafeError`, `APIError` subclasses per HTTP status,
+  `APIConnectionError`, `APITimeoutError`, and `APIUserAbortError`.
+- Structured logging with level filtering and credential-header redaction.
+- Configuration from `TYPESAFE_API_KEY`, `TYPESAFE_BASE_URL`, `TYPESAFE_DEFAULT_MODEL`,
+  and `TYPESAFE_LOG_LEVEL`, with explicit options taking precedence.
+- Pluggable HTTP adapter for custom transport or testing.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TypeSafe Ruby SDK Contributors
+
+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,200 @@
+# Unofficial TypeSafe AI Ruby SDK
+
+[![Gem Version](https://img.shields.io/gem/v/typesafe-sdk-ruby)](https://rubygems.org/gems/typesafe-sdk-ruby)
+[![CI](https://github.com/afurm/typesafe-sdk-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/afurm/typesafe-sdk-ruby/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Community-maintained, unofficial** Ruby SDK for [TypeSafe AI](https://typesafe.ai). Ask named
+questions about text or structured state and get typed answers back: yes/no (noul), choice, and
+score questions — with retries, timeouts, structured logging, and typed errors.
+
+> This gem is not affiliated with, endorsed by, or supported by TypeSafe AI. It is a faithful
+> community port of the official [JavaScript SDK](https://github.com/typesafe-ai/typesafe-sdk-js).
+> Official SDKs: [JavaScript](https://github.com/typesafe-ai/typesafe-sdk-js) and Python.
+
+> **Versioning:** gem versions intentionally mirror the official JavaScript SDK so it is
+> obvious which upstream release each port tracks (e.g. gem 0.6.0 ≈ JS SDK 0.6.0).
+
+## Requirements
+
+- Ruby 3.1 or newer
+- A TypeSafe API key (`TYPESAFE_API_KEY`)
+
+## Installation
+
+Install the gem:
+
+```sh
+gem install typesafe-sdk-ruby
+```
+
+Or add it to your application's `Gemfile`:
+
+```ruby
+gem "typesafe-sdk-ruby"
+```
+
+and run `bundle install`.
+
+## Quickstart
+
+```ruby
+require "typesafe-sdk-ruby"
+
+client = Typesafe::SDK::Client.new
+
+response = client.system_one(
+  state: { document: "I was charged twice. Please fix this ASAP." },
+  questions: {
+    category: Typesafe::SDK.choice("What is this ticket about?", {
+      billing: nil,
+      technical: nil,
+      other: nil,
+    }),
+  },
+)
+
+puts response.answers["category"].choice
+```
+
+Answer objects are typed by the question that produced them:
+
+| Question | Answer class | Key fields |
+| --- | --- | --- |
+| `noul` | `Typesafe::SDK::NoulResponse` | `noul` (probability of yes) |
+| `choice` | `Typesafe::SDK::ChoiceResponse` | `choice`, `confidence`, `probabilities` |
+| `score` | `Typesafe::SDK::ScoreResponse` | `score`, `confidence`, `legend`, `probabilities` |
+
+## Configuration
+
+Explicit options take precedence over environment variables, then SDK defaults.
+
+| Option | Environment variable | Default |
+| --- | --- | --- |
+| `api_key:` | `TYPESAFE_API_KEY` | — (required) |
+| `base_url:` | `TYPESAFE_BASE_URL` | `https://api.typesafe.ai` |
+| `default_model:` | `TYPESAFE_DEFAULT_MODEL` | `jev-latest` |
+| `log_level:` | `TYPESAFE_LOG_LEVEL` | `warn` |
+
+```ruby
+client = Typesafe::SDK::Client.new(
+  api_key: "sk-...",
+  base_url: "https://api.typesafe.ai",
+  default_model: "jev-latest",
+  log_level: :info,          # :debug, :info, :warn, :error, :off
+  timeout: 10,               # seconds per attempt
+  retry_policy: { max_retries: 2, backoff_initial_ms: 500 },
+  default_headers: { "X-My-Header" => "value" },
+)
+```
+
+## Retries and timeouts
+
+The SDK retries HTTP `408`, `429`, and `5xx` responses plus connection failures and timeouts,
+with capped exponential backoff and jitter. It honors `Retry-After` and `retry-after-ms`
+headers up to a cap. Every option is overridable per client or per call:
+
+```ruby
+client.system_one(
+  state: "...",
+  questions: { ... },
+  timeout: 30,
+  retry_policy: { max_retries: 0 },  # disable retries for this call
+)
+```
+
+## Error handling
+
+```ruby
+begin
+  client.system_one(state: "...", questions: { ... })
+rescue Typesafe::SDK::RateLimitError => e
+  retry_after e.retry_after_ms
+rescue Typesafe::SDK::APIError => e
+  warn "API error #{e.status} (request #{e.request_id}): #{e.body}"
+end
+```
+
+Error hierarchy:
+
+- `Typesafe::SDK::TypeSafeError` — base class
+  - `Typesafe::SDK::APIError` — non-2xx HTTP responses
+    - `BadRequestError` (400), `AuthenticationError` (401), `PermissionDeniedError` (403),
+      `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitError` (429),
+      `InternalServerError` (5xx)
+  - `Typesafe::SDK::APIConnectionError` — DNS, TLS, connection failures
+    - `Typesafe::SDK::APITimeoutError`
+  - `Typesafe::SDK::APIUserAbortError` — caller cancellation
+
+## Cancellation
+
+```ruby
+signal = Typesafe::SDK::Signal.new
+Thread.new { sleep 5; signal.cancel }
+
+client.system_one(state: "...", questions: { ... }, signal: signal)
+# raises Typesafe::SDK::APIUserAbortError once canceled
+```
+
+## Listing models
+
+```ruby
+client.models.list.each do |model|
+  puts "#{model.name}: #{model.description}"
+end
+```
+
+## Logging
+
+The default logger writes to `$stderr` with a `[typesafe-sdk-ruby]` prefix. `info` logs request
+summaries; `debug` adds headers (credentials redacted) and bodies. Pass any object responding
+to `debug`/`info`/`warn`/`error`:
+
+```ruby
+client = Typesafe::SDK::Client.new(logger: Rails.logger, log_level: :info)
+```
+
+## Ruby on Rails
+
+The gem is framework-agnostic and works out of the box in Rails. A common pattern is a
+wrapped initializer:
+
+```ruby
+# config/initializers/typesafe.rb
+TYPESAFE = Typesafe::SDK::Client.new(log_level: :info)
+```
+
+```ruby
+# app/models/concerns/typesafe_classifiable.rb
+module TypesafeClassifiable
+  def classify(text)
+    TYPESAFE.system_one(
+      state: text,
+      questions: {
+        category: Typesafe::SDK.choice("Category?", {
+          billing: nil, technical: nil, other: nil,
+        }),
+      },
+    ).answers["category"].choice
+  end
+end
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rake        # specs + RuboCop
+bundle exec rspec       # specs only
+bundle exec rubocop     # lint only
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/afurm/typesafe-sdk-ruby/issues). See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/lib/typesafe/sdk/client.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "time"
+require "uri"
+
+module Typesafe
+  module SDK
+    # Default API root.
+    DEFAULT_BASE_URL = "https://api.typesafe.ai"
+    # Default model used when a request omits `model`.
+    DEFAULT_MODEL = "jev-latest"
+
+    # Client for the TypeSafe AI API.
+    class Client
+      attr_reader :base_url, :default_model, :log_level, :logger, :retry, :timeout,
+                  :default_headers, :models
+
+      # Create a client for the TypeSafe AI API.
+      #
+      # Explicit options take precedence over environment variables, then SDK defaults.
+      # Empty or whitespace-only environment values are ignored.
+      #
+      # @param api_key [String, nil] required unless `TYPESAFE_API_KEY` is set.
+      # @param base_url [String, nil] API root; falls back to `TYPESAFE_BASE_URL`.
+      # @param default_model [String, nil] falls back to `TYPESAFE_DEFAULT_MODEL`, then `jev-latest`.
+      # @param log_level [Symbol, String, nil] falls back to `TYPESAFE_LOG_LEVEL`, then `warn`.
+      # @param logger [#debug, #info, #warn, #error] default: {ConsoleLogger}.
+      # @param retry_policy [Hash, nil] overrides for {Retry::DEFAULT_RETRY_POLICY}.
+      # @param timeout [Float, nil] timeout per attempt in seconds. Default: 10.
+      # @param default_headers [Hash, nil] additional request headers.
+      # @param http [Object] HTTP adapter responding to `request`. Default: {HTTP}.
+      # @raise [TypeSafeError] the API key is missing or configuration is invalid.
+      def initialize(api_key: nil, base_url: nil, default_model: nil, log_level: nil,
+                     logger: nil, retry_policy: nil, timeout: nil, default_headers: nil,
+                     http: nil, env: ::ENV)
+        @api_key = ENV.from_code_or_env(api_key, ENV::API_KEY, source: env)
+        raise TypeSafeError, missing_api_key_message if @api_key.nil? || @api_key.empty?
+
+        @base_url = strip_trailing_slashes(
+          ENV.from_code_or_env(base_url, ENV::BASE_URL, source: env) || DEFAULT_BASE_URL
+        )
+        @default_model = ENV.from_code_or_env(default_model, ENV::DEFAULT_MODEL, source: env) ||
+                         DEFAULT_MODEL
+        @log_level = resolve_log_level(log_level, env)
+        sink = logger || ConsoleLogger.new
+        @logger = LevelLogger.new(sink, @log_level)
+        @retry = resolve_retry_policy(Retry::DEFAULT_RETRY_POLICY, retry_policy)
+        @timeout = assert_positive("timeout", timeout || Retry::DEFAULT_TIMEOUT_S)
+        @default_headers = (default_headers || {}).dup.freeze
+        @http = http || HTTP.new
+        @models = Resources::Models.new(self)
+        @request_count = 0
+      end
+
+      # Answer named questions about text or structured state.
+      #
+      # @param state [String, Hash, Array, nil] the content to evaluate.
+      # @param questions [Hash{Symbol, String => Hash}] nonempty questions keyed by name.
+      # @param model [String, nil] model override; omitted values inherit `default_model`.
+      # @param options [Hash] per-call `timeout`, `retry`, `headers`, and `signal` settings.
+      # @return [SystemOneResult] answers keyed by question name, with model and token usage.
+      # @raise [TypeSafeError] questions are empty, or score criteria are not a list of at
+      #   least two entries.
+      # @raise [APIError] the server returns a non-2xx response after retries.
+      # @raise [APIConnectionError] the request cannot connect or times out after retries.
+      # @raise [APIUserAbortError] the caller cancels the request.
+      #
+      # @example
+      #   response = client.system_one(
+      #     state: "I was charged twice. Please help.",
+      #     questions: { billing: Typesafe::SDK.noul("Is this about billing?") },
+      #   )
+      #   response.answers[:billing].noul # => 0.93
+      def system_one(state:, questions:, model: nil, **options)
+        Questions.validate!(questions)
+        body = { state: state, questions: questions, model: model || @default_model }
+        response = request(:post, "/v1/systemone", body: body, **options)
+        SystemOneResult.new(response.body)
+      end
+
+      # Send a request and parse its response body. Internal; used by API resources.
+      #
+      # @return [Response] the parsed response, with `data`, `status`, `headers`, and `request_id`.
+      def request(method, path, body: nil, headers: {}, timeout: nil, retry_policy: nil,
+                  signal: nil)
+        resolved = {
+          method: method,
+          path: path,
+          body: body,
+          headers: merge_headers(@default_headers, headers),
+          timeout: timeout.nil? ? @timeout : assert_positive("timeout", timeout),
+          retry: resolve_retry_policy(@retry, retry_policy),
+          signal: signal
+        }
+        @request_count += 1
+        tag = "##{@request_count} #{method.to_s.upcase} #{path}"
+        fetch_with_retries(tag, resolved)
+      end
+
+      # The API key, excluded from inspection output.
+      def inspect # :nodoc:
+        "#<#{self.class.name} base_url=#{@base_url.inspect} default_model=#{@default_model.inspect}>"
+      end
+
+      private
+
+      def missing_api_key_message
+        "No API key was provided. Pass `api_key:` to Typesafe::SDK::Client.new or set the " \
+          "#{ENV::API_KEY} environment variable."
+      end
+
+      def resolve_log_level(from_code, env)
+        value = from_code || ENV.read(ENV::LOG_LEVEL, source: env) || LogLevel::DEFAULT
+        LogLevel.parse!(value, from_code ? "the `log_level` option" : ENV::LOG_LEVEL)
+      end
+
+      def strip_trailing_slashes(url)
+        url.sub(%r{/+\z}, "")
+      end
+
+      def assert_positive(name, value)
+        unless value.is_a?(Numeric) && value.positive?
+          raise TypeSafeError,
+                "`#{name}` must be a positive number, got #{value.inspect}."
+        end
+
+        value
+      end
+
+      def assert_non_negative_integer(name, value)
+        unless value.is_a?(Integer) && value >= 0
+          raise TypeSafeError, "`#{name}` must be a non-negative integer, got #{value.inspect}."
+        end
+
+        value
+      end
+
+      def assert_non_negative(name, value)
+        unless value.is_a?(Numeric) && value >= 0
+          raise TypeSafeError, "`#{name}` must be a non-negative number, got #{value.inspect}."
+        end
+
+        value
+      end
+
+      def assert_fraction(name, value)
+        unless value.is_a?(Numeric) && value >= 0 && value <= 1
+          raise TypeSafeError, "`#{name}` must be between 0 and 1, got #{value.inspect}."
+        end
+
+        value
+      end
+
+      def assert_status_set(name, statuses)
+        statuses.each do |status|
+          unless status.is_a?(Integer) && status.between?(100, 999)
+            raise TypeSafeError, "`#{name}` must contain HTTP status codes, got #{status.inspect}."
+          end
+        end
+        statuses
+      end
+
+      # Merge and validate retry overrides, copying the status list to isolate later mutations.
+      def resolve_retry_policy(base, overrides)
+        o = overrides || {}
+        {
+          max_retries: if o.key?(:max_retries)
+                         assert_non_negative_integer("retry.max_retries",
+                                                     o[:max_retries])
+                       else
+                         base[:max_retries]
+                       end,
+          backoff_initial_ms: if o.key?(:backoff_initial_ms)
+                                assert_non_negative("retry.backoff_initial_ms",
+                                                    o[:backoff_initial_ms])
+                              else
+                                base[:backoff_initial_ms]
+                              end,
+          backoff_max_ms: if o.key?(:backoff_max_ms)
+                            assert_non_negative("retry.backoff_max_ms",
+                                                o[:backoff_max_ms])
+                          else
+                            base[:backoff_max_ms]
+                          end,
+          backoff_jitter: if o.key?(:backoff_jitter)
+                            assert_fraction("retry.backoff_jitter",
+                                            o[:backoff_jitter])
+                          else
+                            base[:backoff_jitter]
+                          end,
+          http_statuses: if o.key?(:http_statuses)
+                           assert_status_set("retry.http_statuses",
+                                             o[:http_statuses].dup)
+                         else
+                           base[:http_statuses]
+                         end,
+          respect_retry_after: o.fetch(:respect_retry_after, base[:respect_retry_after]),
+          max_retry_after_ms: if o.key?(:max_retry_after_ms)
+                                assert_non_negative("retry.max_retry_after_ms",
+                                                    o[:max_retry_after_ms])
+                              else
+                                base[:max_retry_after_ms]
+                              end,
+          api_connection_error: o.fetch(:api_connection_error, base[:api_connection_error]),
+          api_timeout_error: o.fetch(:api_timeout_error, base[:api_timeout_error])
+        }.freeze
+      end
+
+      # Last value wins regardless of casing; `nil` removes a protected header.
+      def merge_headers(*sources)
+        merged = {}
+        sources.each do |source|
+          source.each do |name, value|
+            key = name.to_s.downcase
+            if value.nil?
+              merged.delete(key)
+            else
+              merged[key] = value
+            end
+          end
+        end
+        merged
+      end
+
+      # Retry eligible failures, logging attempt summaries at `info` and details at `debug`.
+      def fetch_with_retries(tag, req)
+        url = "#{@base_url}#{req[:path]}"
+        # User-supplied headers go first so they can't clobber auth or the JSON content type.
+        headers = merge_headers(req[:headers], {
+                                  "Authorization" => "Bearer #{@api_key}",
+                                  "Accept" => "application/json",
+                                  "User-Agent" => "typesafe-sdk-ruby/#{VERSION}",
+                                  "X-TypeSafe-SDK" => "typesafe-sdk-ruby/#{VERSION}",
+                                  "X-TypeSafe-Runtime" => "ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})",
+                                  "Content-Type" => req[:body].nil? ? nil : "application/json",
+                                  "X-TypeSafe-Retry-Count" => nil
+                                })
+        payload = req[:body].nil? ? nil : JSON.generate(req[:body])
+
+        attempt = 0
+        loop do
+          retries_left = req[:retry][:max_retries] - attempt
+          attempt_headers = attempt.zero? ? headers : headers.merge("X-TypeSafe-Retry-Count" => attempt.to_s)
+          @logger.debug("#{tag} -> #{url}", headers: Redaction.redact_headers(attempt_headers), body: req[:body])
+
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          begin
+            response = attempt_request(tag, url, req[:method], attempt_headers, payload, req)
+          rescue APIUserAbortError
+            raise
+          rescue APIConnectionError => e
+            raise if retries_left <= 0 || !retryable_connection_error?(e, req[:retry])
+
+            back_off(tag, attempt, retries_left, e.message, nil, req)
+            attempt += 1
+            next
+          end
+
+          request_id = response.request_id
+          elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+          @logger.info("#{tag} <- #{response.status} in #{elapsed}ms#{" (request #{request_id})" if request_id}")
+          return parse_success(tag, response) if response.ok?
+
+          error = APIError.from_response(response.status, response.body, response.headers)
+          @logger.debug("#{tag} <- error body", body: response.body)
+          raise error if retries_left <= 0 || !Retry.retryable_status?(response.status, req[:retry])
+
+          back_off(tag, attempt, retries_left, response.status.to_s, response.headers, req)
+          attempt += 1
+        end
+      end
+
+      def retryable_connection_error?(error, policy)
+        return policy[:api_timeout_error] if error.is_a?(APITimeoutError)
+
+        policy[:api_connection_error]
+      end
+
+      def parse_success(tag, response)
+        @logger.debug("#{tag} <- body", body: response.body)
+        response
+      end
+
+      # One HTTP round trip, including body delivery, with a timeout.
+      def attempt_request(tag, url, method, headers, payload, req)
+        @http.request(
+          method: method,
+          url: url,
+          headers: headers,
+          body: payload,
+          timeout: req[:timeout],
+          signal: req[:signal]
+        )
+      rescue APIUserAbortError
+        raise
+      rescue APITimeoutError
+        @logger.info("#{tag} timed out")
+        raise
+      rescue APIConnectionError => e
+        @logger.info("#{tag} connection error", error: e.message)
+        raise
+      end
+
+      # Wait before retrying; caller cancellation raises `APIUserAbortError`.
+      def back_off(tag, attempt, retries_left, reason, headers, req)
+        delay = Retry.retry_delay_ms(attempt, headers, req[:retry])
+        nth = attempt + 1
+        total = attempt + retries_left
+        @logger.info("#{tag} retrying in #{delay}ms (retry #{nth}/#{total}) after #{reason}")
+        sleep_with_signal(delay, req[:signal])
+      end
+
+      def sleep_with_signal(seconds, signal)
+        signal&.check!
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + (seconds / 1000.0)
+        loop do
+          if signal
+            signal.check!
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            signal.wait(remaining) if remaining.positive?
+            signal.check!
+          else
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            break if remaining <= 0
+
+            sleep([remaining, 0.1].min)
+          end
+          break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/env.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    # Environment variable names for client configuration. Explicit options take precedence.
+    module ENV
+      # Required API key; used when `api_key` is omitted.
+      API_KEY = "TYPESAFE_API_KEY"
+      # API root; defaults to `https://api.typesafe.ai`.
+      BASE_URL = "TYPESAFE_BASE_URL"
+      # Default model name; defaults to `jev-latest`.
+      DEFAULT_MODEL = "TYPESAFE_DEFAULT_MODEL"
+      # Log level; defaults to `warn`.
+      LOG_LEVEL = "TYPESAFE_LOG_LEVEL"
+
+      ALL = [API_KEY, BASE_URL, DEFAULT_MODEL, LOG_LEVEL].freeze
+
+      module_function
+
+      # Read a trimmed environment value, returning `nil` for missing or blank values.
+      def read(name, source: ::ENV)
+        value = source[name].to_s.strip
+        value.empty? ? nil : value
+      end
+
+      # Return the explicit value, falling back to the environment.
+      def from_code_or_env(from_code, name, source: ::ENV)
+        from_code || read(name, source: source)
+      end
+    end
+  end
+end