samagotchi 0.2.0 → 0.3.0

data/lib/samagotchi/bootstrap/config_writer.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "fileutils"
+require "ipaddr"
+require_relative "../config"
+
+module Samagotchi
+  module Bootstrap
+    # Writes the host `chi bootstrap` found into config.yml. With no file it
+    # writes a small commented one; an existing file is the edge case and
+    # gets a hosts: entry inserted as text (YAML.dump would drop the user's
+    # comments), after a backup, and is checked by parsing it again: every
+    # other key must be unchanged, or the backup goes back.
+    class ConfigWriter
+      Error = Class.new(StandardError)
+
+      # kind: :new (a fresh file), :appended, :exists (the host is already
+      #   there as +existing+; nothing written), :snippet (a file chi can't
+      #   edit safely: paste +text+ yourself), :failed (written, but the check
+      #   failed and the backup is back), :dry_run (+text+ is what would be
+      #   written or inserted, +where+ says where)
+      # model_hint: a line for the user to add when default: exists without model
+      Outcome = Data.define(:kind, :path, :backup, :text, :where, :name, :existing, :default_model, :model_hint) do
+        def self.of(kind, path:, backup: nil, text: nil, where: nil, name: nil, existing: nil, default_model: nil,
+                    model_hint: nil)
+          new(kind: kind, path: path, backup: backup, text: text, where: where, name: name, existing: existing,
+              default_model: default_model, model_hint: model_hint)
+        end
+      end
+
+      HOSTS_LINE_RE = /\Ahosts:[ \t]*(#.*)?\z/
+      DEFAULT_INDENT = 2
+      SERVER_TRANSPORTS = ConfigFile::VALID_TRANSPORTS_FOR_CONFIG
+
+      # The host part of a name: localhost/127.x → local, another IP → lan,
+      # a domain → its second-level label (api.openai.com → openai).
+      def self.derived_name(host)
+        text = host.to_s.downcase.delete_prefix("[").delete_suffix("]")
+        address = begin
+          IPAddr.new(text)
+        rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+          nil
+        end
+        return "local" if text == "localhost" || address&.loopback?
+        return "lan" if address
+
+        labels = text.split(".").reject(&:empty?)
+        name = (labels.length >= 2 ? labels[-2] : labels.first).to_s.gsub(/[^a-z0-9._-]/, "-")
+        name.match?(ConfigFile::HOST_NAME_RE) ? name : "host"
+      end
+
+      attr_reader :path
+
+      # @param path [String] config.yml (a symlink is written through)
+      # @param env [Hash] the environment for the check (SAMAGOTCHI_HOSTS_JSON
+      #   is dropped: it would replace the file's hosts)
+      # @param now [Proc] the time for the backup's name and the header
+      def initialize(path:, env: ENV, now: -> { Time.now })
+        @path = path
+        @env = env.to_h.except("SAMAGOTCHI_HOSTS_JSON")
+        @now = now
+      end
+
+      def exists? = File.file?(@path)
+
+      # The file's data: {} for an empty file, nil when there is none or it
+      # doesn't parse.
+      def data
+        return @data if defined?(@data)
+
+        @data = exists? ? (parse(File.read(@path)) || {}) : nil
+      rescue StandardError
+        @data = nil
+      end
+
+      # The hosts entries the file routes to today, name → fields: its
+      # hosts:, or with none the `default` chi makes from server.*.
+      def current_hosts
+        raw = data.is_a?(Hash) ? data["hosts"] : nil
+        return raw.to_h { |name, fields| [name.to_s.downcase, fields.is_a?(Hash) ? fields : {}] } if raw.is_a?(Hash)
+        return {} if data.is_a?(Hash) && data.key?("hosts")
+
+        { "default" => server_entry }
+      end
+
+      # The name of an existing entry that points at the same server, or nil.
+      def duplicate_of(fields)
+        current_hosts.find { |_, existing| same_server?(existing, fields) }&.first
+      end
+
+      # The entry's name: +requested+ as given (it must be free), else
+      # +base+, with -2, -3… when the name is taken or is the prefix of a
+      # model id (chi would read "openai/gpt-x" as host openai, model gpt-x).
+      def host_name(base, requested: nil, model_ids: [])
+        taken = current_hosts.keys
+        if requested
+          name = requested.to_s.strip
+          raise Error, "--name must match #{ConfigFile::HOST_NAME_RE.source}" unless name.match?(ConfigFile::HOST_NAME_RE)
+          raise Error, "config.yml already has a host named '#{name}'; pick another --name" if taken.include?(name.downcase)
+
+          return name
+        end
+
+        prefixes = [*model_ids, configured_default_model].compact.map { |id| id.to_s.split(%r{[:/]}, 2).first.downcase }
+        name = base
+        n = 1
+        name = "#{base}-#{n += 1}" while taken.include?(name) || prefixes.include?(name)
+        name
+      end
+
+      # Write the entry. @param fields [Hash] the hosts entry (string keys,
+      # in the order written) @param model [String] the model id
+      # @return [Outcome]
+      def write(name:, fields:, model:, dry_run: false)
+        default_model = "#{name}:#{model}"
+        return write_new(name, fields, default_model, dry_run) unless exists?
+
+        existing = duplicate_of(fields)
+        return Outcome.of(:exists, path: @path, name: name, existing: existing) if existing
+
+        append(name, fields, default_model, dry_run)
+      end
+
+      private
+
+      def write_new(name, fields, default_model, dry_run)
+        text = <<~YAML
+          # Written by chi bootstrap on #{@now.call.strftime("%Y-%m-%d")}; see docs/configuration.md
+          default:
+            model: #{scalar(default_model)}
+          hosts:
+          #{entry_lines(name, fields, DEFAULT_INDENT, DEFAULT_INDENT).join}# More settings: docs/configuration.md#all-settings
+        YAML
+        return Outcome.of(:dry_run, path: @path, text: text, where: "a new file", name: name, default_model: default_model) if dry_run
+
+        FileUtils.mkdir_p(File.dirname(@path))
+        atomic_write(@path, text)
+        Outcome.of(:new, path: @path, name: name, default_model: default_model)
+      end
+
+      def append(name, fields, default_model, dry_run)
+        original = File.binread(@path).force_encoding(Encoding::UTF_8)
+        return snippet(name, fields) unless data.is_a?(Hash) && !anchors?(original)
+
+        eol = original.include?("\r\n") ? "\r\n" : "\n"
+        lines = original.split(/(?<=\n)/)
+        lines[-1] = "#{lines[-1]}#{eol}" if lines.any? && !lines[-1].end_with?("\n")
+        hosts_at = lines.index { |line| line.chomp.match?(HOSTS_LINE_RE) }
+        return snippet(name, fields) if hosts_at.nil? && data.key?("hosts")
+
+        default_entry = hosts_at || !routed? ? nil : server_entry
+        add_model, model_hint = default_model_change(default_model)
+
+        if hosts_at
+          at, child, step = block_end(lines, hosts_at)
+          inserted = entry_lines(name, fields, child, step)
+          where = "in hosts:, after line #{at}"
+          lines.insert(at, *inserted.map { |line| line.sub(/\n\z/, eol) })
+        else
+          inserted = ["hosts:\n", *(default_entry ? entry_lines("default", default_entry, DEFAULT_INDENT, DEFAULT_INDENT) : []),
+                      *entry_lines(name, fields, DEFAULT_INDENT, DEFAULT_INDENT)]
+          where = "a new hosts: section at the end"
+          lines.concat(inserted.map { |line| line.sub(/\n\z/, eol) })
+        end
+        if add_model
+          model_lines = ["default:\n", "  model: #{scalar(default_model)}\n"]
+          inserted += model_lines
+          lines.concat(model_lines.map { |line| line.sub(/\n\z/, eol) })
+        end
+        text = lines.join
+        if dry_run
+          return Outcome.of(:dry_run, path: @path, text: inserted.join, where: where, name: name,
+                                      default_model: add_model ? default_model : nil, model_hint: model_hint)
+        end
+
+        real = File.realpath(@path)
+        backup = backup_path(real)
+        FileUtils.cp(real, backup, preserve: true)
+        atomic_write(real, text)
+        expected = expected_data(name, fields, default_entry, add_model ? default_model : nil)
+        unless written_ok?(real, expected, name)
+          atomic_write(real, File.binread(backup))
+          return Outcome.of(:failed, path: @path, backup: backup, text: snippet_text(name, fields), name: name)
+        end
+
+        Outcome.of(:appended, path: @path, backup: backup, name: name, default_model: add_model ? default_model : nil,
+                              model_hint: model_hint)
+      end
+
+      # Where a new entry goes in the hosts: block starting at +hosts_at+:
+      # its end (the first entry is the default host, so never first),
+      # before trailing blank lines and comments shallower than an entry.
+      # @return [index, entry indent, field indent step]
+      def block_end(lines, hosts_at)
+        stop = hosts_at + 1
+        stop += 1 while stop < lines.length && inside_block?(lines[stop])
+        children = lines[(hosts_at + 1)...stop].reject { |line| blank_or_comment?(line) }
+        child = children.first ? indent(children.first) : DEFAULT_INDENT
+        field = children.find { |line| indent(line) > child }
+        step = field ? indent(field) - child : child
+        at = stop
+        at -= 1 while at > hosts_at + 1 && (lines[at - 1].strip.empty? || (comment?(lines[at - 1]) && indent(lines[at - 1]) < child))
+        [at, child, step]
+      end
+
+      def inside_block?(line)
+        return true if line.strip.empty?
+        return false if line.start_with?("---", "...")
+
+        line.start_with?(" ", "\t") || comment?(line)
+      end
+
+      def blank_or_comment?(line) = line.strip.empty? || comment?(line)
+      def comment?(line) = line.lstrip.start_with?("#")
+      def indent(line) = line[/\A */].length
+
+      def entry_lines(name, fields, child, step)
+        ["#{" " * child}#{name}:\n", *fields.map { |key, value| "#{" " * (child + step)}#{key}: #{scalar(value)}\n" }]
+      end
+
+      # Strings double-quoted (JSON's quoting is valid YAML): model ids hold
+      # "/" and ":".
+      def scalar(value) = value.is_a?(Integer) ? value.to_s : JSON.generate(value.to_s)
+
+      def snippet(name, fields)
+        Outcome.of(:snippet, path: @path, text: snippet_text(name, fields), name: name)
+      end
+
+      def snippet_text(name, fields) = "hosts:\n#{entry_lines(name, fields, DEFAULT_INDENT, DEFAULT_INDENT).join}"
+
+      # [add default.model?, a line to print instead]
+      def default_model_change(default_model)
+        return [false, nil] if configured_default_model
+        return [false, "  model: #{scalar(default_model)}   # under default:"] if data.key?("default")
+
+        [true, nil]
+      end
+
+      def configured_default_model
+        return nil unless data.is_a?(Hash)
+
+        section = data["default"]
+        value = section.is_a?(Hash) ? section["model"] : nil
+        value ||= data[ConfigFile::DEFAULT_MODEL_KEY]
+        value.to_s.strip.empty? ? nil : value.to_s.strip
+      end
+
+      # Whether bare model names go somewhere today: a default.model or a
+      # server: section. Then a new hosts: block keeps that route as `default`.
+      def routed?
+        configured_default_model || data.key?("server") || data.keys.any? { |key| key.to_s.start_with?("SAMAGOTCHI_SERVER_") }
+      end
+
+      # The `default` hosts entry chi derives from server.* when the file has
+      # no hosts:, written out so a new hosts: block doesn't reroute bare models.
+      def server_entry
+        file = data.is_a?(Hash) ? data : {}
+        host = Config.resolve("server.host", file_data: file, env: {}, cli_overrides: {}).to_s.strip
+        port = Config.resolve("server.port", file_data: file, env: {}, cli_overrides: {}).to_i
+        transport = Config.resolve("server.transport", file_data: file, env: {}, cli_overrides: {}).to_s.strip.downcase
+        entry = { "host" => host.empty? ? "localhost" : host, "port" => port.positive? ? port : 8080 }
+        entry["transport"] = transport if SERVER_TRANSPORTS.include?(transport) && transport != "llama_cpp"
+        entry
+      end
+
+      def same_server?(existing, fields)
+        a = location(existing)
+        b = location(fields)
+        a && b && a == b
+      end
+
+      # [scheme-less host, port, path] of an entry.
+      def location(fields)
+        url = fields["url"].to_s.strip
+        unless url.empty?
+          uri = URI.parse(url)
+          return [uri.host.to_s.downcase, uri.port, uri.path.to_s.chomp("/")]
+        end
+        host = fields["host"].to_s.strip.downcase
+        return nil if host.empty?
+
+        port = fields["port"].to_s.strip.empty? ? 8080 : fields["port"].to_i
+        [host, port, fields["api"].to_s == "openai" ? "/v1" : ""]
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def expected_data(name, fields, default_entry, default_model)
+        expected = Marshal.load(Marshal.dump(data))
+        hosts = expected["hosts"].is_a?(Hash) ? expected["hosts"] : {}
+        hosts["default"] = default_entry if default_entry
+        hosts[name] = fields
+        expected["hosts"] = hosts
+        expected["default"] = { "model" => default_model } if default_model
+        expected
+      end
+
+      def written_ok?(real, expected, name)
+        parse(File.read(real)) == expected &&
+          ConfigFile.hosts_config(env: @env, path: real).key?(name.downcase)
+      rescue StandardError
+        false
+      end
+
+      def parse(text) = YAML.safe_load(text, permitted_classes: [], aliases: false)
+
+      # Anchors and aliases: chi's reader refuses aliases, and an insert
+      # can't know what an anchor shares.
+      def anchors?(text)
+        stack = [Psych.parse_stream(text)]
+        until stack.empty?
+          node = stack.pop
+          return true if node.is_a?(Psych::Nodes::Alias) || (node.respond_to?(:anchor) && node.anchor)
+
+          stack.concat(Array(node.children)) if node.respond_to?(:children)
+        end
+        false
+      rescue Psych::Exception
+        true
+      end
+
+      def backup_path(real)
+        stamp = @now.call.utc.strftime("%Y%m%dT%H%M%SZ")
+        candidate = "#{real}.bak-#{stamp}"
+        n = 1
+        candidate = "#{real}.bak-#{stamp}-#{n += 1}" while File.exist?(candidate)
+        candidate
+      end
+
+      def atomic_write(target, text)
+        tmp = "#{target}.tmp-#{Process.pid}"
+        File.binwrite(tmp, text)
+        File.chmod(File.stat(target).mode & 0o7777, tmp) if File.exist?(target)
+        File.rename(tmp, target)
+      ensure
+        FileUtils.rm_f(tmp) if tmp && File.exist?(tmp)
+      end
+    end
+  end
+end

data/lib/samagotchi/bootstrap/probe.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "json"
+require "uri"
+require "ipaddr"
+require_relative "../version"
+require_relative "../llm/openai_chat"
+
+module Samagotchi
+  module Bootstrap
+    # What `chi bootstrap TARGET` finds at a model server: llama.cpp's native
+    # API (/props), an OpenAI-compatible one (/v1/models), one that wants an
+    # API key, or nothing. One attempt per request, no retries: a refused
+    # port answers at once instead of after chi's usual backoff.
+    class Probe
+      # The ports `chi bootstrap` with no target tries on localhost.
+      LOCAL_PORTS = { 8080 => "llama.cpp", 11434 => "Ollama", 1234 => "LM Studio", 8000 => "vLLM" }.freeze
+      DEFAULT_PORT = 8080
+      # Connect and read seconds for /props and /v1/models: a remote https
+      # handshake needs more than Client#server_props' 1 s / 2 s.
+      TIMEOUT = 5
+      # Seconds a local-port scan waits per port.
+      SCAN_TIMEOUT = 1
+      TEST_TIMEOUT = 60
+      TEST_PROMPT = "Reply with the word ok."
+
+      # One place a server may be: root is scheme://host:port (llama.cpp's
+      # /props), base the OpenAI API base (<root>/v1, or a URL's own path).
+      # url is true when the user gave a URL with a path, which the config
+      # then keeps as written.
+      Candidate = Data.define(:root, :base, :url) do
+        def uri = URI(root)
+        def host = uri.host
+        def port = uri.port
+        def scheme = uri.scheme
+        def label = "#{host}:#{port}"
+      end
+
+      # kind: :native, :openai, :needs_key, :unreachable or :unknown.
+      # props: the /props JSON (native); models: [LLM::ModelInfo];
+      # status: the HTTP status that decided (:unknown, :needs_key);
+      # reason: why it's unreachable.
+      Result = Data.define(:kind, :candidate, :props, :models, :status, :reason) do
+        def self.of(kind, candidate, props: nil, models: [], status: nil, reason: nil)
+          new(kind: kind, candidate: candidate, props: props, models: models, status: status, reason: reason)
+        end
+
+        def native? = kind == :native
+        def reached? = %i[native openai].include?(kind)
+      end
+
+      # The target the user typed, as the candidates to try in order.
+      #   host, host:port, an IP  → http://host:port (port 8080 when none)
+      #   a domain without a scheme → https first, then http
+      #   a URL → as given; a path is the OpenAI base
+      # Raises ArgumentError for something that isn't a host or URL.
+      def self.candidates(target)
+        text = target.to_s.strip
+        raise ArgumentError, "no target" if text.empty?
+
+        if text.match?(%r{\A[a-z][a-z0-9+.-]*://}i)
+          uri = parse_uri(text)
+          raise ArgumentError, "not an http(s) URL: #{text}" unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+
+          root = root_url(uri.scheme, uri.host, uri.port)
+          path = uri.path.to_s.chomp("/")
+          return [Candidate.new(root: root, base: path.empty? ? "#{root}/v1" : "#{root}#{path}", url: !path.empty?)]
+        end
+
+        uri = parse_uri("http://#{text}")
+        raise ArgumentError, "not a host or URL: #{text}" unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+
+        path = uri.path.to_s.chomp("/")
+        port = text.match?(%r{:\d+(/|\z)}) ? uri.port : nil
+        schemes = domain?(uri.host) ? { "https" => 443, "http" => 80 } : { "http" => DEFAULT_PORT }
+        schemes.map do |scheme, default_port|
+          root = root_url(scheme, uri.host, port || default_port)
+          Candidate.new(root: root, base: path.empty? ? "#{root}/v1" : "#{root}#{path}", url: !path.empty?)
+        end
+      end
+
+      # scheme://host:port, without the port when it is the scheme's own
+      # (https://openrouter.ai, not https://openrouter.ai:443): it is written
+      # into config.yml as typed.
+      def self.root_url(scheme, host, port)
+        default = { "http" => 80, "https" => 443 }[scheme]
+        port == default ? "#{scheme}://#{host}" : "#{scheme}://#{host}:#{port}"
+      end
+
+      # A name with a dot that isn't an IP or localhost: reached over https
+      # on 443 first, like a browser would.
+      def self.domain?(host)
+        return false if host.nil? || host.casecmp?("localhost") || ip?(host)
+
+        host.include?(".")
+      end
+
+      def self.ip?(host)
+        IPAddr.new(host.to_s.delete_prefix("[").delete_suffix("]"))
+        true
+      rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+        false
+      end
+
+      def self.parse_uri(text)
+        URI.parse(text)
+      rescue URI::InvalidURIError
+        nil
+      end
+      private_class_method :parse_uri
+
+      # @param env [Hash] where the API key variable is read
+      # @param timeout [Numeric] connect and read seconds per request
+      def initialize(env: ENV, timeout: TIMEOUT)
+        @env = env
+        @timeout = timeout
+      end
+
+      # Probe the target's candidates in order; the next one is tried only
+      # when this one refused the connection or failed its TLS handshake
+      # (https → http), not on a timeout.
+      # @param key_env [String, nil] the API key's environment variable
+      # @return [Result]
+      def classify_target(candidates, key_env: nil)
+        result = nil
+        candidates.each do |candidate|
+          result = classify(candidate, key_env: key_env)
+          break unless result.kind == :unreachable && result.reason.to_s.match?(/refused|SSL|TLS|certificate/i)
+        end
+        result
+      end
+
+      # @return [Result]
+      def classify(candidate, key_env: nil)
+        props = begin
+          status, body = get(URI("#{candidate.root}/props"), key_env)
+          status == 200 ? parse_object(body) : nil
+        rescue *network_errors => e
+          return Result.of(:unreachable, candidate, reason: reason(e))
+        end
+        return Result.of(:native, candidate, props: props, models: native_models(candidate, props, key_env)) if native_props?(props)
+
+        begin
+          Result.of(:openai, candidate, models: list_models(candidate.base, key_env))
+        rescue LLM::ProviderError => e
+          kind = [401, 403].include?(e.status) ? :needs_key : :unknown
+          Result.of(kind, candidate, status: e.status, reason: e.status ? nil : e.message)
+        rescue *network_errors => e
+          Result.of(:unreachable, candidate, reason: reason(e))
+        end
+      end
+
+      # The ports in LOCAL_PORTS that answer as a model server, probed in
+      # parallel. @return [Array<Result>] the reached ones, in LOCAL_PORTS order
+      def scan_local(ports: LOCAL_PORTS.keys)
+        scanner = self.class.new(env: @env, timeout: SCAN_TIMEOUT)
+        ports.map do |port|
+          Thread.new { scanner.classify(Candidate.new(root: "http://localhost:#{port}", base: "http://localhost:#{port}/v1", url: false)) }
+        end.map(&:value).select(&:reached?)
+      end
+
+      # /props for one model (a llama.cpp router loads it on demand), or nil
+      # when the server doesn't answer it.
+      def model_props(candidate, model, key_env: nil)
+        status, body = get(URI("#{candidate.root}/props?#{URI.encode_www_form(model: model)}"), key_env)
+        status == 200 ? parse_object(body) : nil
+      rescue StandardError
+        nil
+      end
+
+      # One short chat request: does the server generate for +model+? Any 200
+      # with a choice counts (a thinking model may spend its 16 tokens
+      # reasoning). @return [Float] seconds taken
+      # @raise [RuntimeError] with what went wrong
+      def test_turn(candidate, model, key_env: nil, read_timeout: TEST_TIMEOUT)
+        uri = URI("#{candidate.base}/chat/completions")
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(model: model, messages: [{ role: "user", content: TEST_PROMPT }], max_tokens: 16,
+                                     stream: false)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        response = send_request(uri, request, key_env, read_timeout: read_timeout)
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        body = parse_object(response.body)
+        unless response.code.to_i == 200 && body && body["choices"].is_a?(Array) && !body["choices"].empty?
+          raise "HTTP #{response.code}: #{error_text(body, response.body)}"
+        end
+
+        elapsed
+      rescue *network_errors => e
+        raise "#{reason(e)} (#{candidate.label})"
+      end
+
+      private
+
+      def native_props?(props)
+        props.is_a?(Hash) && (props.key?("chat_template") || props.key?("build_info"))
+      end
+
+      # llama.cpp serves /v1/models too; a server that doesn't gets its
+      # model_alias.
+      def native_models(candidate, props, key_env)
+        models = begin
+          list_models(candidate.base, key_env)
+        rescue StandardError
+          []
+        end
+        return models unless models.empty?
+
+        name = props["model_alias"].to_s.strip
+        name.empty? ? [] : [LLM::ModelInfo.new(id: name, context_window: nil, supports_tools: nil, raw: {})]
+      end
+
+      def list_models(base, key_env)
+        LLM::OpenAIChat.new(base_url: base, host_name: URI(base).host, api_key_env: key_env, retries: false,
+                            timeout: @timeout, env: @env).list_models
+      end
+
+      def get(uri, key_env)
+        response = send_request(uri, Net::HTTP::Get.new(uri), key_env, read_timeout: @timeout)
+        [response.code.to_i, response.body]
+      end
+
+      def send_request(uri, request, key_env, read_timeout:)
+        request["User-Agent"] = Samagotchi::USER_AGENT
+        key = key_env && @env[key_env].to_s
+        request["Authorization"] = "Bearer #{key}" if key && !key.strip.empty?
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @timeout,
+                                            read_timeout: read_timeout) { |http| http.request(request) }
+      end
+
+      def network_errors
+        [*LLM::HTTP::NETWORK_ERRORS, OpenSSL::SSL::SSLError, Errno::EADDRNOTAVAIL, Errno::ENETDOWN, Errno::EPIPE]
+      end
+
+      def reason(error)
+        case error
+        when Errno::ECONNREFUSED then "connection refused"
+        when Net::OpenTimeout then "no answer in #{@timeout} s"
+        when Timeout::Error, IO::TimeoutError then "timed out"
+        when SocketError then "unknown host"
+        when OpenSSL::SSL::SSLError then "TLS: #{error.message}"
+        else error.message
+        end
+      end
+
+      def parse_object(text)
+        parsed = JSON.parse(text.to_s)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      def error_text(body, raw)
+        message = body.is_a?(Hash) && (body.dig("error", "message") || body["error"] || body["message"])
+        (message || raw.to_s)[0, 200].to_s.strip
+      end
+    end
+  end
+end