gemchat 0.1.0

data/lib/gemchat/embedder.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+# The supervised child loads this file directly, so the base error has to be
+# available without loading the whole gem.
+require_relative "errors"
+
+module Gemchat
+  # Turns text into a unit vector.
+  #
+  # The seam exists so nothing else in gemchat has to know how embeddings are
+  # made. Tests use a stub embedder and never load a model; `search` works with
+  # no embedder at all. That is not only for test speed — `gemchat search` is
+  # required to work with zero models downloaded, and BM25 must never become
+  # dependent on a 146MB file being present.
+  #
+  # Embedding runs in a **supervised subprocess**, and that is not an aesthetic
+  # choice. rllama 1.2.0's prebuilt llama.cpp aborts with SIGILL inside
+  # `llama_model_load_from_file` on this machine — measured intermittently, not
+  # deterministically: the same command that failed four times in a row later
+  # passed 20 of 20 with no configuration change, and `GGML_METAL_DISABLE=1`
+  # made no reliable difference. An illegal instruction cannot be rescued, so in
+  # this process there is no way to detect it, retry it, or degrade. A child we
+  # are willing to lose is the only place that failure can be handled at all.
+  module Embedder
+    class Error < Gemchat::Error; end
+
+    # Returned when no model is available, so callers can ask for vectors without
+    # branching on "is this a real embedder". Every method is a no-op rather than
+    # raising, because a missing model is a normal state, not an error.
+    class Null
+      def available? = false
+      def null? = true
+      def identity = nil
+      def dimensions = 0
+      def embed(_texts) = []
+
+      def close
+      end
+    end
+
+    # Wraps a loaded GGUF model. Used inside the child process.
+    #
+    # Named Gguf, not Rllama, on purpose: a class called `Embedder::Rllama`
+    # shadows the `rllama` gem's own `Rllama` for the rest of this lexical
+    # scope, so `Rllama.silence_log!` inside it resolves to
+    # Gemchat::Embedder::Rllama and raises NoMethodError. Every reference to the
+    # gem is root-scoped as `::Rllama` regardless.
+    class Gguf
+      def initialize(model_path:, model_name:)
+        require "rllama"
+        ::Rllama.silence_log!
+        @model = ::Rllama::Model.new(model_path)
+        @identity = model_name
+        @dimensions = @model.n_embd
+      end
+
+      attr_reader :identity, :dimensions
+
+      def available? = true
+      def null? = false
+
+      # Returns unit vectors, so a dot product is a cosine similarity and no
+      # per-query magnitude normalisation is needed at search time.
+      def embed(texts)
+        list = Array(texts).map(&:to_s).reject { |t| t.strip.empty? }
+        return [] if list.empty?
+
+        @model.embed(list)
+      end
+
+      def close
+        @model&.close
+        @model = nil
+      end
+    end
+
+    module_function
+
+    # Never raises for a missing model: `search` depends on this returning Null
+    # rather than blowing up when no 146MB file is present.
+    def build(name = Models.default)
+      return Null.new unless Models.installed?(name)
+
+      Supervised.new(
+        model_path: Models.path(name),
+        identity: Models.identity(name),
+        prefix: Models.prefix(:document, name)
+      )
+    end
+
+    def available?(name = Models.default)
+      Models.installed?(name)
+    end
+
+    # Embeds in a supervised child process, retrying once with the GPU backend
+    # disabled. Used directly by the CLI; `Supervised` is the object callers hold.
+    class Supervised
+      # A child is given a budget of input text and no more. llama.cpp sizes its
+      # embedding context from the input, and past a certain total it aborts the
+      # process rather than returning an error -- measured on this machine: a
+      # single 216-chunk batch died with SIGILL while 128 chunks in one batch
+      # succeeded, and where exactly it dies moved between runs.
+      #
+      # The ceiling is therefore treated as unknown rather than tuned. 16KB sits
+      # far below every failure point observed (45KB passed, 90KB did not), and
+      # `embed` halves a batch and retries when one fails anyway, so correctness
+      # does not depend on this number being right.
+      BATCH_BYTES = 16_000
+
+      # Per-item ceiling, and the reason it exists is a measurement rather than a
+      # spec. Real prose from the rake docs fails to embed as a single item at
+      # 1665 bytes and succeeds at 1634; the same bytes of repeated "word " run
+      # fine to 2500, so this is not a byte count and not a clean token count.
+      # Content-independent stripping made no difference either -- pure ASCII of
+      # the same text still failed -- which points at the native embedding path
+      # rather than at anything about the input.
+      #
+      # 1200 leaves margin under the observed cliff instead of sitting on it.
+      # The cost is real and worth stating: a long prose chunk is represented by
+      # its opening, and its tail is reachable through BM25 but not through
+      # `vsearch`. Prose is already split at the chunker, so this bites the
+      # largest sections only.
+      MAX_TEXT_BYTES = 1200
+
+      def initialize(model_path:, identity:, prefix: nil)
+        @model_path = model_path
+        @identity = identity
+        @prefix = prefix
+        @dimensions = nil
+      end
+
+      attr_reader :identity, :dimensions
+
+      def available? = true
+      def null? = false
+
+      # Returns [index, vector] pairs, not a bare vector list.
+      #
+      # Partial success is the normal case, not an edge case: a batch that cannot
+      # be embedded even after backoff is left pending, and those chunks must not
+      # be written with a neighbour's vector or dropped from the count. Pairing
+      # keeps the mapping to the caller's rows explicit so a caller can persist
+      # exactly what came back.
+      #
+      # `kind` records which side of the pair is being embedded. The prefix is
+      # fixed at construction, so this is documentation of intent rather than a
+      # switch -- documents and queries land in different regions for a prefixed
+      # model, and embedding a query with the document prefix is a silent
+      # retrieval-quality bug rather than a crash.
+      def embed(texts, kind: :document)
+        list = Array(texts).map { |t| clip(t.to_s) }.reject { |t| t.strip.empty? }
+        return [] if list.empty?
+
+        results = {}
+        failed = []
+        each_batch(list) { |batch, offset| collect(batch, offset, results, failed) }
+
+        unless failed.empty?
+          warn "left #{failed.size} chunk(s) pending: could not embed " \
+            "#{failed.first(3).join(", ")}#{", …" if failed.size > 3}"
+        end
+
+        if results.empty?
+          raise Error, "no chunk could be embedded; this machine cannot run the model"
+        end
+
+        @dimensions ||= results.values.first.size
+        results.sort.map { |index, vector| [index, vector] }
+      end
+
+      def close
+      end
+
+      private
+
+      # Trims to the per-item ceiling on a word boundary. The head is kept
+      # deliberately: a chunk's searchable text opens with its title, source
+      # type and signature, which is the part that should drive a match.
+      #
+      # `scrub` is not optional. A byte slice can land in the middle of a
+      # multi-byte character, and the very next `rindex(/\s/)` on the result
+      # raises `ArgumentError: invalid byte sequence in UTF-8`. Found by
+      # embedding 22k chunks from 120 real gems, not by the 236-chunk rake index
+      # that every other measurement here used -- so `gemchat embed` crashed on
+      # any bundle whose prose contained a character straddling the boundary.
+      def clip(text)
+        return text if text.bytesize <= MAX_TEXT_BYTES
+
+        cut = text.byteslice(0, MAX_TEXT_BYTES)
+        cut.force_encoding(text.encoding)
+        cut = cut.scrub("") unless cut.valid_encoding?
+
+        boundary = cut.rindex(/\s/)
+        (boundary ? cut[0...boundary] : cut).strip
+      end
+
+      def each_batch(list)
+        batch = []
+        bytes = 0
+        start = 0
+
+        list.each_with_index do |text, i|
+          if batch.empty?
+            start = i
+          end
+
+          batch << text
+          bytes += text.bytesize
+
+          next unless bytes >= BATCH_BYTES
+
+          yield(batch, start)
+          batch = []
+          bytes = 0
+        end
+
+        yield(batch, start) unless batch.empty?
+      end
+
+      # Binary backoff: a batch that dies is retried as two halves, so a
+      # size-triggered abort costs one batch rather than the run.
+      def collect(texts, offset, results, failed)
+        vectors, dimensions, error = Embedder.attempt(
+          texts, model_path: @model_path, identity: @identity, prefix: @prefix
+        )
+        @dimensions ||= dimensions
+
+        if error.nil?
+          texts.each_index { |i| results[offset + i] = vectors[i] }
+          return
+        end
+
+        if texts.size == 1
+          failed << "##{offset + 1}"
+          warn "  chunk ##{offset + 1} failed to embed: #{error}"
+          return
+        end
+
+        half = texts.size / 2
+        collect(texts.first(half), offset, results, failed)
+        collect(texts.drop(half), offset + half, results, failed)
+      end
+    end
+
+    # One supervised attempt: plain backend, then Metal disabled.
+    # Returns [vectors, dimensions, error].
+    def attempt(texts, model_path:, identity:, prefix: nil)
+      [{}, {"GGML_METAL_DISABLE" => "1"}].each do |attempt_env|
+        vectors, dimensions, error = run_child(
+          texts, model_path:, identity:, env: attempt_env, prefix:
+        )
+        return [vectors, dimensions, nil] if error.nil?
+
+        @last_error = error
+      end
+
+      [nil, nil, @last_error]
+    end
+
+    # The child body. Kept as one string because it has to run in a fresh
+    # process with no gemchat state, and because its correctness is easier to
+    # read here than split across two files.
+    def child_script
+      <<~RUBY
+        $stdout.sync = true
+        $LOAD_PATH.unshift(#{File.expand_path("..", __dir__).inspect})
+        require "json"
+        require "gemchat/embedder"
+        payload = JSON.parse($stdin.read)
+        embedder = Gemchat::Embedder::Gguf.new(
+          model_path: payload["model_path"], model_name: payload["identity"]
+        )
+        prefix = payload["prefix"].to_s
+        vectors = embedder.embed(payload["texts"].map { |t| prefix + t })
+        $stdout.write(JSON.generate({ "dimensions" => embedder.dimensions, "vectors" => vectors }))
+        embedder.close
+      RUBY
+    end
+
+    def run_child(texts, model_path:, identity:, env:, prefix: nil)
+      out, status = Open3.capture2e(env, RbConfig.ruby, "-e", child_script,
+        stdin_data: JSON.generate({
+          "texts" => texts, "model_path" => model_path,
+          "identity" => identity, "prefix" => prefix.to_s
+        }))
+      unless status.success?
+        return [nil, nil, "exit #{status.exitstatus}#{detail(out)}"]
+      end
+
+      payload = JSON.parse(out)
+      dims = payload["dimensions"].to_i
+      vectors = payload["vectors"]
+      if vectors.empty? || vectors.first.size != dims
+        return [nil, nil, "child returned #{vectors.size} vectors of dim #{vectors.first&.size} (expected #{dims})"]
+      end
+
+      [vectors, dims, nil]
+    rescue JSON::ParserError => e
+      [nil, nil, "unparseable child output: #{e.message}"]
+    rescue => e
+      [nil, nil, "#{e.class}: #{e.message}"]
+    end
+
+    def detail(out)
+      line = out.to_s.lines.reject { |l| l.strip.empty? }.last
+      line ? " (#{line.strip[0, 120]})" : ""
+    end
+  end
+end

data/lib/gemchat/env.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Gemchat
+  # Boolean environment parsing. This is the only thing we would have wanted
+  # from ActiveSupport, and depending on it would drag in 13 gems
+  # (concurrent-ruby, i18n, tzinfo, drb, connection_pool, ...) for a CLI that
+  # needs none of them. Plain Ruby instead.
+  module Env
+    TRUTHY = %w[1 true t yes y on].freeze
+    FALSEY = %w[0 false f no n off].freeze
+
+    module_function
+
+    # Unset or unrecognised => default, so a typo never silently disables a
+    # feature or silently enables one.
+    def truthy?(key, default: false)
+      raw = ENV[key]
+      return default if raw.nil?
+
+      value = raw.strip.downcase
+      return true if TRUTHY.include?(value)
+      return false if FALSEY.include?(value)
+
+      default
+    end
+  end
+end

data/lib/gemchat/errors.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Gemchat
+  # Base class for every error gemchat raises deliberately, so the CLI can
+  # rescue one thing and print a message instead of a backtrace.
+  #
+  # Its own file because subclasses live in files that are required before the
+  # module body of lib/gemchat.rb has been evaluated.
+  class Error < StandardError; end
+end

data/lib/gemchat/hook.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Deliberately requires only what the hook needs, not all of gemchat. Bundler
+# loads this from a fresh child process during `bundle install`, where eagerly
+# pulling in the store and the indexer would mean opening SQLite on every install
+# in a project that has gemchat as a plugin.
+require "json"
+require "rbconfig"
+require_relative "paths"
+require_relative "lockfile"
+require_relative "manifest"
+require_relative "trust"
+
+module Gemchat
+  # The logic behind the Bundler plugin hook.
+  #
+  # Kept in lib/ rather than in plugins.rb on purpose. plugins.rb is the copy
+  # Bundler loads from the *plugin* install, and a dual `gem` + `plugin`
+  # declaration installs two physical copies with nothing pinning them together
+  # (§15.4). A file that contains only the `add_hook` registration and delegates
+  # here — reached through the bundled copy — has nothing to drift.
+  #
+  # Contract, all of it measured or tested in test/plugin_shim_test.rb:
+  #   * never raises; a raising plugins.rb fails the whole install
+  #   * silent unless there is genuinely something to say
+  #   * at most one prefixed line
+  module Hook
+    HOST_GEM = "gemchat"
+    SUPPORTED = Gem::Requirement.new(">= 0.1.0")
+    PREFIX = "[gemchat] "
+
+    class << self
+      def auto_index
+        return if quiet_environment?
+        return report("#{HOST_GEM} is not in the bundle") unless host_spec
+        return report("skipped: outside supported range") unless SUPPORTED.satisfied_by?(host_spec.version)
+
+        project = Dir.pwd
+        return report("not trusted for #{project}; run `gemchat index` yourself") unless ::Gemchat::Trust.trusted?(project)
+
+        digest = ::Gemchat::Lockfile.digest(project)
+        return if digest.nil?
+        return if ::Gemchat::Manifest.new(project).up_to_date?(digest)
+
+        run_index(project)
+      rescue => e
+        report "auto-index skipped (#{e.class}: #{e.message})"
+      end
+
+      def host_spec
+        @host_spec ||= ::Bundler.load.specs.find { |s| s.name == HOST_GEM }
+      end
+
+      # The hook runs on CI and on deploy installs, where any output is noise and
+      # any work is wasted. Checked before the trust lookup because it is free.
+      #
+      # Deliberately not keyed on RAILS_ENV, which is how the Hyperdrive shim
+      # gates itself. gemchat is not a Rails tool, so in any plain Ruby project
+      # RAILS_ENV is unset and such a guard would silence the hook permanently —
+      # a no-op that looks installed and does nothing.
+      def quiet_environment?
+        !ENV["CI"].nil? || ENV["GEMCHAT_NO_AUTO_INDEX"].to_s == "1"
+      end
+
+      # Shells out rather than indexing in-process. Two reasons: the hook must
+      # not hold Bundler's stdout or leave an open SQLite handle behind a bundle
+      # install, and a subprocess that dies cannot take the install with it.
+      def run_index(project)
+        summary = index_summary(project)
+        return if summary.nil?
+
+        if summary["changed"].to_i.positive?
+          report("indexed #{summary["changed"]} #{pluralise(summary["changed"], "gem")} " \
+            "(#{summary["chunks"]} chunks)")
+        end
+      end
+
+      # Runs the executable from the *bundled* gem, not whatever `gemchat` is on
+      # PATH. Under `bundle install` there may be no gemchat on PATH at all, and
+      # if there is one it may be a different version -- the same drift the shim
+      # design exists to prevent. A missing or unparseable result returns nil and
+      # the caller stays silent, rather than failing somebody's install.
+      def index_summary(project)
+        exe = File.join(host_spec.full_gem_path, "exe", "gemchat")
+        return nil unless File.executable?(exe)
+
+        raw = IO.popen(
+          {
+            "GEMCHAT_HOME" => ::Gemchat::Paths.root,
+            "GEMCHAT_CONFIG_HOME" => ::Gemchat::Paths.config_home
+          },
+          [RbConfig.ruby, exe, "index", "--json"],
+          chdir: project, err: [:child, :out]
+        ) { |io| io.read.to_s }
+
+        JSON.parse(raw.lines.last.to_s)
+      rescue
+        # Never propagate. A failure here must not surface as a failed
+        # `bundle install`; the caller simply stays quiet and the index waits
+        # for the next explicit `gemchat index`.
+        nil
+      end
+
+      def pluralise(count, word)
+        (count == 1) ? word : "#{word}s"
+      end
+
+      def report(message)
+        warn "#{PREFIX}#{message}"
+      end
+    end
+  end
+end

data/lib/gemchat/hosted.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Gemchat
+  # Client for gemchat.org's hosted index.
+  #
+  # This is the opt-in tier, and the rules around it are stricter than the code
+  # suggests. It is **never** a fallback: a local-first privacy tool that silently
+  # sent queries to a server would be a different product, and a user with a
+  # populated local index has no reason to expect their questions leaving the
+  # machine. So nothing here is ever reached unless the user asked, and a
+  # failure here stops rather than retrying locally.
+  #
+  # Speaks `POST /api/v1/query` rather than the MCP endpoint. MCP is for agents
+  # and returns prose; a CLI needs rows, and parsing formatted Markdown breaks
+  # silently the first time the server reformats a line.
+  class Hosted
+    DEFAULT_ENDPOINT = "https://gemchat.org/api/v1/query"
+    CREDENTIALS = "credentials"
+    TIMEOUT = 30
+    MAX_LIMIT = 20
+
+    class Error < Gemchat::Error; end
+    class Unauthorized < Error; end
+
+    # The server's search could not run, as distinct from a search that ran and
+    # matched nothing. Kept separate because the two mean opposite things: this
+    # is a broken or misconfigured server, and retrying or widening the query
+    # will not help.
+    class SearchUnavailable < Error; end
+
+    Result = Struct.new(:rows, :version_note, :missing, :notice, :scope)
+
+    def self.enabled?
+      endpoint = ENV["GEMCHAT_HOST"]
+      return true if endpoint && !endpoint.strip.empty?
+
+      !api_key.nil?
+    end
+
+    # Where the key lives: an env var first so CI can set it without a file, then
+    # `~/.gemchat/credentials`, which is where §12.1 says it goes.
+    def self.api_key
+      from_env = ENV["GEMCHAT_API_KEY"]
+      return from_env unless from_env.nil? || from_env.strip.empty?
+
+      credentials_file
+    end
+
+    def self.credentials_path
+      File.join(Gemchat.config_home, CREDENTIALS)
+    end
+
+    # Reads the key, accepting the two shapes people actually write:
+    #
+    #   GEMCHAT_API_KEY=abc…    explicit, so the file can hold more later
+    #   abc…                    bare, which is what a hand-written file usually is
+    #
+    # The bare form is not a nicety. A parser that only understands the first
+    # shape returns nil for a file that plainly contains a key, and the CLI then
+    # says "hosted backend not configured" -- which sends the user looking for a
+    # setting problem when the secret is sitting on disk. Failing to parse a
+    # credentials file must never look like there being no credentials.
+    #
+    # Anything else non-empty is returned as-is rather than discarded, so a
+    # malformed value produces a 401 from the server -- which names the real
+    # problem -- instead of silence. Only an empty or all-comment file is nil.
+    def self.credentials_file
+      path = credentials_path
+      return nil unless File.file?(path)
+
+      lines = File.read(path).lines.map(&:strip).reject { |line| line.empty? || line.start_with?("#") }
+      return nil if lines.empty?
+
+      assigned = lines.find { |line| line.match?(/\A(?:export\s+)?GEMCHAT_API_KEY\s*=/) }
+      if assigned
+        value = assigned.sub(/\A(?:export\s+)?GEMCHAT_API_KEY\s*=\s*/, "").strip
+        return value.delete_prefix("\"").delete_suffix("\"").delete_prefix("'").delete_suffix("'").strip
+      end
+
+      lines.first
+    end
+
+    def initialize(key: nil, endpoint: nil)
+      @key = key || self.class.api_key
+      @endpoint = endpoint || ENV["GEMCHAT_HOST"]
+    end
+
+    attr_reader :key, :endpoint
+
+    def configured?
+      !key.nil? && !key.to_s.strip.empty?
+    end
+
+    def url
+      base = @endpoint.to_s.strip
+      return URI.parse(DEFAULT_ENDPOINT) if base.empty?
+
+      # GEMCHAT_HOST is documented as a host, so accept a bare host or a full URL
+      # and always land on the versioned path. Any path in the variable is
+      # ignored: §12.1 names a host, and letting a stray path through would send
+      # queries somewhere the user never indicated.
+      uri = base.include?("://") ? URI.parse(base) : URI.parse("https://#{base}")
+      uri.path = "/api/v1/query"
+      uri
+    end
+
+    # `gem_names` and `gem_versions` come straight from the local lockfile.
+    # Passing the pins is what makes a hosted answer about the version that is
+    # actually installed rather than whatever the server happens to have indexed;
+    # the server reports any pin it could not apply, so nothing is silently wrong.
+    def query(text, limit: 5, gem_names: nil, gem_versions: nil, auto_index: false)
+      unless configured?
+        raise Unauthorized, "no API key; set GEMCHAT_API_KEY, or write GEMCHAT_API_KEY=... to #{self.class.credentials_path}"
+      end
+
+      body = {
+        query: text,
+        limit: [limit.to_i, 1].max.clamp(1, MAX_LIMIT),
+        gem_names: Array(gem_names),
+        gem_versions: Array(gem_versions),
+        auto_index: auto_index
+      }.compact
+
+      response = post(url, body)
+      payload = parse(response)
+
+      raise Unauthorized, hosted_message(payload, "Unauthorized") if response.code == "401"
+
+      unless response.is_a?(Net::HTTPSuccess)
+        detail = hosted_message(payload, "")
+
+        # A server that could not run the search says so in a field of its own.
+        # Reporting it as a generic failure loses the one fact that separates a
+        # broken server from an empty index, and they call for opposite reactions:
+        # one is worth retrying later, the other means widen the query.
+        if payload.is_a?(Hash) && payload["error"] == "search_unavailable"
+          reason = payload["reason"].to_s.strip
+          raise SearchUnavailable,
+            "gemchat.org's search could not run#{" (#{reason})" unless reason.empty?}. " \
+            "This is not an empty result -- nothing was searched. `gemchat search` still works offline."
+        end
+
+        raise Error, "hosted query failed: HTTP #{response.code}#{" #{detail}" unless detail.to_s.empty?}"
+      end
+
+      Result.new(
+        rows: Array(payload["results"]),
+        version_note: payload["version_note"],
+        missing: Array(payload["missing"]),
+        notice: payload["notice"],
+        scope: payload["scope"].is_a?(Hash) ? payload["scope"] : nil
+      )
+    end
+
+    # Public so tests can replace it and a future `--insecure-proxy` can wrap it.
+    # Everything above it is policy; this is the wire.
+    def post(uri, body)
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = "Bearer #{key}"
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request.body = JSON.generate(body)
+
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
+        http.request(request)
+      end
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise Error, "hosted query timed out after #{TIMEOUT}s (#{e.class}). `gemchat search` still works offline."
+    rescue SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH => e
+      raise Error, "cannot reach #{uri.host} (#{e.class}). `gemchat search` still works offline."
+    end
+
+    private
+
+    def parse(response)
+      JSON.parse(response.body.to_s)
+    rescue JSON::ParserError
+      # A proxy or a login page can return 200 with HTML in it. Saying "invalid
+      # JSON" is technically true and practically useless.
+      raise Error, "hosted endpoint returned #{response.code} with a non-JSON body (#{response.body.to_s[0, 80].inspect})"
+    end
+
+    # No ActiveSupport here: this gem is plain Ruby, so no `presence`.
+    def hosted_message(payload, fallback)
+      error = payload.is_a?(Hash) ? payload["error"].to_s.strip : ""
+      return error unless error.empty?
+
+      fallback.to_s.strip.empty? ? nil : fallback.to_s.strip
+    end
+  end
+end